Shipments

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 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 a specific strategy 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.

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.

Default shipping method

If you set a default shipping method 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 updating the relationship.

• If a shipment is already associated with a shipping method and the association is removed, 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.

Manual shipments management

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. change what is going to be shipped 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 inventory model level).

Shipments are still manually creatable and updatable even when the associated order's fulfillment status is fulfilled.

Some attributes (e.g. changing the shipment status, except moving it to upcoming and to cancelled) can be updated by sales channels 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 integration 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.

Manual stock management

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).

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). 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.

Data model

Check the related ER diagram and explore the flowchart that illustrates how the shipment resource relates to the other API entities.

How-to

Check the related guide to learn more about the available inventory model strategies, how they work, and how shipments are managed based on each of them.