Shipments
The shipment object and the allowed CRUD operations on the related resource endpoint
Last updated
API reference
The shipment object and the allowed CRUD operations on the related resource endpoint
Last updated
Commerce Layer automatically manages shipments, stock transfers, and stock line items creation based on one of the you set at the level. The default strategy is , 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 order contains line items from more than one stock location.
The order contains line items belonging to more than one shipping category.
You opted for that generates (at least) one separate shipment per each line item of type skus in the order.
In general, the combination of stock locations and shipping categories determines the number of shipments. Each shipment gets fulfilled separately.
If you set a for a market, all the shipments that belong to the market's orders and that are not already associated with a shipping method will be automatically associated with the default one. Specifically:
Any new shipment will be automatically associated with the default shipping method at creation time. Then, if needed, you can change the shipping method by patching the shipment and .
If a shipment is already associated with a shipping method and the association is , the shipment will be automatically associated with the default shipping method.
Existing shipments with no shipping method associated will not be automatically associated with the default one until a new validation on the shipment is caused (e.g. triggering a status change).
In any case, the associated line item of type shipments will be created/recreated accordingly and the default shipping method will be listed in the available_shipping_methods array associated with the shipment.
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_progress you have the possibility to manually manage the shipments (e.g. after the order approval). Specifically:
Update any existing shipment's shipping_category, inventory_stock_location, and shipping_address relationships.
Create new shipments.
Delete already generated shipments (in this case any related stock reservation is removed and the corresponding stock is automatically released, unless you have chosen to manually manage these actions too by setting the related flag at the level).
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 true to 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 pending status (i.e. with no expiration date).
_decrement_stock — set it to true to 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 true to remove the related stock reservation(s).
Some attributes (e.g. changing the shipment status, except moving it to upcoming and to cancelled) can be updated by before the order placement. For any other action available after the order approval (e.g. updating the shipment's shipping_category, inventory_stock_location, and shipping_address relationships, passing the _upcoming and _cancel_ trigger attrubutes, creating new shipments, or deleting existing shipments) you need to use API credentials. 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.
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 ). The very same triggers are exposed also at the stock line item level, in case you need more granular control on your manual stock decrementation process.
Check the related to learn more about the available inventory model strategies, how they work, and how shipments are managed based on each of them.