Comment on page
The shipment object and the allowed CRUD operations on the related resource endpoint
Commerce Layer automatically manages shipments, stock transfers, and stock line items creation based on one of the available strategies you set at the inventory model level. The default strategy is no split, meaning that just a single shipment from a single stock location is always created. If a different strategy is selected the orders fulfillment can be split into more shipments for one of the following reasons:
The combination of stock locations and shipping categories determines the number of shipments. Each shipment gets fulfilled separately.
In case the inventory model strategy is left as default – no split – shipping categories are ignored: just one shipment is created with no specific category associated.
If you're happy with the selected inventory strategy, there's no additional action required from your side. All the the necessary resources are automatically generated according to a predefined logic, based on the strategy of your choice. If you need to modify those resources or build custom / more complex inventory strategies, you still have the option to do it. Speaking about shipments, they keep being generated and re-built according to the selected inventory strategy logic for the first part of the order lifecycle, but as soon as the associated order's fulfillment status moves to
in_progressyou have the possibility to manually manage the shipments (e.g. change what is going to be shipped after the order approval). Specifically:
- Update any existing shipment's
- Create new shipments.
- Delete already generated shipments (in this case any related stock reservation is removed and the corresponding stock is automatically released).
Some attributes (e.g. changing the shipment status, except moving it to
upcoming) can be updated by a sales channel before the order placement. For any other action available after the order approval (e.g. updating the shipment's
shipping_addressrelationships, passing the
_upcomingtrigger attrubute, creating new shipments, or deleting existing shipments) you need to use an integration application. To manually create a new shipment, specifying the associated inventory stock location is mandatory: make sure that it belongs to the inventory model associated with the related order's market, otherwise the API will return an error.
If you choose not to rely on the automatic shipments management that comes with one of the available inventory strategy and manually manage shipments, you need also to consistently update the involved stock. To do that, you can leverage some specific trigger attributes:
_reserve_stock— set it to
trueto check if the shipment is associated with one or more stock line items and (if so and if the related stock quantity is enough) create the necessary stock reservation(s) directly in
pendingstatus (i.e. with no expiration date).
_decrement_stock— set it to
trueto decrement the quantity of the stock item(s) associated with the stock line item(s) and remove the related stock reservation(s).
_release_stock— set it to
trueto remove the related stock reservation(s).
All the trigger attributes listed above take effect only if sent when patching the shipment and if the fulfillment status of the order associated with the shipment is
in_progress. They are all atomic so that any accidental repeated action on the same stock line item (e.g. reserving/decrementing/releasing the stock multiple times) is prevented (unless you manually modify the stock line item).