Stock reservations

The stock reservation object and the allowed CRUD operations on the related resource endpoint

Stock reservations typically are used to reserve the stock associated with an order's line items of type skus or bundles until the order is approved. If needed, you can also create stock reservations that are not associated with a specific order's line item.

Active stock reservations (if any) determine the actual availability of the associated stock items.

Line item stock reservation

Manual stock reservation before order placement

You can temporarily reserve the stock associated with a line item before the order placement by sending a specific trigger attribute when adding the line item to the order. This way the necessary stock reservations are created in draft status, with an expiration date of 1 hour (you can change the default value at the inventory model level). If the order isn't placed before the expiration date or the line item is removed, the corresponding reserved stock is released and any associated active stock reservation is deleted.

Stock reservations act on the whole line item quantity. If the available stock is split between different stock locations, multiple stock reservations are created.

Automatic stock reservation at order placement

When the order is placed any existing active stock reservation associated with its line items is moved from draft to pending. If no draft stock reservation is associated with the order's line items, the stock reservations needed to block the whole order's stock are automatically created in pending status and the associated stock is reserved without decrementing the stock item quantities. Once the order is approved, the stock item quantities are decremented and the involved stock reservations are deleted, unless you have chosen to manually manage these actions by setting the related flag at the inventory model level. If the order is cancelled before approval, the reserved stock is released becoming available again and the involved stock reservations are deleted.

Generic stock reservation

Stock reservations can also be created outside of the order scope as long as their quantity is less or equal to the quantity of the associated stock item. Like the ones associated with a line item they get created in draft status, with a default expiration date of 1 hour. Before they expire, you can move them to the pending status by passing the _pending trigger attribute.

Only draft stock reservations have an expiration date before order placement. Once the order is placed (or a generic draft stock reservation is manually moved to pending) the stock is reserved until the order is approved or cancelled.

For security reasons, stock reservations can be managed using integration API credentials only.

Data model

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

Last updated