Skip to main content

Use Cases of updateShipmentStatus API

The payload examples below are used in updateShipmentStatus API.

1. Full Confirmation​

Use when you want to move an entire shipment to the bag_confirmed state. This transition is typically required after all items in the shipment are validated and ready for further processing in the order lifecycle.

2. Bag Invoiced Transition​

When the seller has confirmed the order and created the invoice, the status will automatically change to DP Assigned (except MTO orders, where the status will change to ready_for_dp_assignment state).

3. Full Cancellation with Same Reason Applied to All Products​

Use this transition when you need to cancel every product in a shipment for the same reason, such as "Product Not Available." This approach is best suited when the entire shipment is unfulfillable and must be cancelled in a single action for a common cause. All items within the specified shipment will transition to the bag_not_confirmed state, representing a total cancellation. This option is applicable when none of the products in the shipment can proceed further in the fulfillment process.

4. Partial Confirmation at Products and Quantity Level​

Confirmed items in the shipment transition to the next state specified in status (for example, bag_confirmed). Items that are not confirmed will transition to the state defined in exclude_bags_next_state (for example, bag_not_confirmed). For instance, if a shipment contains 10 items and you confirm five, those five items move to bag_confirmed, while the remaining five will move to bag_not_confirmed state.

5. Partial Cancellation (Without Affecting Status of Other Items)​

The cancelled items move to the next allowed state, as defined in the status (here, bag_not_confirmed). Items that are not confirmed do not change state because exclude_bags_next_state is set to null; they remain in their current state. For example, if an order has 10 items and five are updated to bag_not_confirmed, the remaining five remain in the same state (e.g., placed).

6. Delivery Partner Assignment​

Delivery Partner Assignment involves updating the shipment status to indicate that a delivery partner has been successfully assigned (usually with "status": "dp_assigned").

7. Split Shipments​

Split Shipments enable you to separate a single shipment into multiple shipments, each containing specific products of your choosing. This is particularly useful when different products within the same shipment need to be shipped from different locations, have varying availability, or require distinct fulfillment processes and timelines.

For example, if a shipment consists of several products but only some are ready to be shipped or handled differently, you can use the split shipment feature. By specifying which products (using their identifiers and quantities) need to be split out, and setting the split_shipment flag to true in your payload, the system automatically creates a new shipment with its own unique identifier. The selected products are moved into this new shipment and assigned the designated status (such as placed), while the rest of the products remain in the original shipment with no changes to their states.

8. DP not Assigned​

Use this transition when the assignment of a delivery partner to a shipment has failed. The shipment status should be updated to dp_not_assigned to reflect that no delivery partner could be allocated.