Inventory APIs overview

Ask about this Page
Copy for AI
View as Markdown

How to work with the APIs for inventory management.

This page describes rules that apply across the Inventory APIs. For what Inventory and Reservations are and how they behave, see the Inventory overview.

APIs in this topic

ResourcePurposeReference
InventoryTrack stock quantity per SKU and optionally per supply channel.Inventory
ReservationsTemporarily reserve available quantity for customers when they add a Line Item to a Cart.Reservations

Data model

An InventoryEntry optionally links to a supply channel through the supplyChannel field.

Working with the APIs

Quantity limits

To restrict the quantity of a SKU that can be added to a Cart, you can set minimum and maximum limits on the InventoryEntry:
  • minCartQuantity: the minimum allowed quantity for a Line Item in the Cart. This prevents customers from adding quantities below the specified threshold.
  • maxCartQuantity: the maximum allowed quantity for a Line Item in the Cart. This caps the quantity a customer can purchase at once.
You set these limits when creating an InventoryEntry using the InventoryEntryDraft, or update them on an existing InventoryEntry using the Set Inventory Limits update action.
While quantity limits are enforced on the backend, it is recommended that your application performs client-side checks using the Inventory API or ProductVariantAvailability object to fetch and display quantity limits to customers. This prevents failed cart updates or order creations and improves the customer experience.

Workarounds

If a customer needs to purchase more than the maxCartQuantity for a single Product Variant, consider the following options:
  • Custom field workaround: add custom fields with different values to Line Items. This allows creating multiple Line Items for the same Product Variant, each subject to the quantity limits individually. The total quantity across all Line Items can exceed the limit of a single Line Item.
  • Adjust or remove quantity limits: modify the minCartQuantity or maxCartQuantity values on the InventoryEntry, or remove the limits entirely.
  • Use another InventoryEntry: create or use a different InventoryEntry for the same SKU without quantity limits, potentially with a different supply channel.

Reservations

Reservations are created automatically if the Project-level reservation expiration is set, and one of the following occurs:
  • The Cart's inventory mode is ReserveOnCart.
  • One or more Line Item's inventory mode is set to ReserveOnCart but the Cart has a different inventory mode.
Reservation-based changes to InventoryEntry are eventually consistent. For more information, see Inventory checks and consistency.

Set the default expiration

To use reservations, you must first set the Project-level reservation expiration time. After you set this default, you'll be able to use the ReserveOnCart InventoryMode on Carts or individual Line Items. This step ensures that stock is not held indefinitely. You only have to set this once per Project.
You can optionally set the default expiration time for individual InventoryEntries using the Set Reservation Expiration In Minutes update action.

Reserve items

Reservations expire based on the reservationExpirationInMinutes value set in the corresponding InventoryEntry, or if absent, the Project-level reservation expiration time. Reserved Line Items include a reservation field containing the reservation reference, which you can then expand to view additional details. There is no dedicated API endpoint to query or manage Reservation resources directly; they are only accessible through reference expansion on a Cart's Line Items.

Reserve all items in a Cart

To reserve stock for all Line Items in a Cart, set the Cart's inventory mode to ReserveOnCart during Cart creation.

The following applies:

  • If all items could be reserved, the Cart creation succeeds, and no warnings are present in the response.
  • If some items could not be reserved, the Cart creation succeeds, however, those items are not added to the Cart. The response will contain a CannotCreateReservation warning for each Line Item that could not be reserved/added.
  • If no Line Items could be reserved, the Cart creation fails.

Reserve individual Line Items

To reserve stock for individual Line Items in a Cart, set the Line Item's inventory mode to ReserveOnCart. You can do this when adding items to a Cart, or for existing items, using the Set LineItem InventoryMode update action.

The following applies:

  • When changing an existing Line Item's inventory mode to ReserveOnCart and there is insufficient stock available, the response contains a CannotCreateReservation warning. The Line Item remains in the Cart and the inventory mode remains unchanged.
  • When adding a new Line Item with the inventory mode set to ReserveOnCart, and there is insufficient stock available, the response contains a CannotCreateReservation warning, and the Line Item is not added to the Cart.

Update a reservation

The following scenarios illustrate how to update an existing reservation:

Change the reserved quantity

To change the quantity of a reserved Line Item, use the Change LineItem Quantity update action on the Cart. If successful, the platform updates the availableQuantity of the associated InventoryEntry and extends the reservation expiration time.
Because changing the quantity also updates the expiration time, you may want to synchronize the expiration across all Line Items in the Cart. To do this, use the Set Reservation Expiration in Minutes update action on the Cart after updating the quantity.

Extend the reservation expiration

To extend the expiration time of all reservations in a Cart, use the Set Reservation Expiration in Minutes update action on the Cart. If successful, all reservations will have the same expiration time, based on the new value provided.
If a reservation cannot be updated, the response will contain a CannotChangeReservationExpiryWarning which provides details about the failure. When this occurs, the expiration time of the affected reservation remains unchanged.

To prevent Order creation failures due to a last-second expiration, the platform automatically attempts to renew expired Cart reservations during the Order creation process.

Release a reservation

To release a reservation, change the Line Item's inventory mode from ReserveOnCart to another inventory mode using the Set LineItem InventoryMode update action. This action increases the availableQuantity of the associated InventoryEntries accordingly.

Handle reservation warnings

The following warnings may appear in Cart responses when working with reservations:

WarningAppearance
CannotCreateReservationWarningAppears when creating a Cart with ReserveOnCart but one or more Line Items lack sufficient stock. No reservation is created. See Reserve items.
CannotUpdateReservationWarningAppears when updating a Line Item's quantity but the reservation cannot be updated (usually due to insufficient stock). The Line Item quantity remains unchanged.
CannotChangeReservationExpiryWarningAppears when trying to extend an expired reservation but insufficient stock prevents reacquiring it. The action succeeds, but the reservation expiry cannot be extended.

Further reading

To learn more about implementing reservations, see the following tutorials:

Eventual consistency

Inventory checks and consistency

While InventoryEntry is the source of truth for stock levels, the time it takes for changes to be reflected depends on where those changes originate:
  • Direct updates to InventoryEntry using the Inventory API are strongly consistent and immediately visible.
  • Order operations using the ReserveOnOrder or TrackOnly inventory modes are eventually consistent. This means that changes to the availableQuantity and quantityOnStock fields of the corresponding InventoryEntry may take up to 10 seconds to appear.
  • Reservation-based updates to resources using the ReserveOnCart inventory mode are eventually consistent. This means that changes to the availableQuantity and quantityOnStock fields of the corresponding InventoryEntry may take up to 10 seconds to appear. The following endpoint and update actions are affected if the Cart or Line Items use the ReserveOnCart inventory mode:
Reservations are guaranteed regardless of the eventual consistency delay. The reservation logic acquires stock from an internal real-time SKU availability collection, which ensures that stock checks and reservations are accurate at the time they are made. The availableQuantity and quantityOnStock fields on the InventoryEntry are eventually aligned with this internal collection, but the delay does not affect reservation guarantees or cause failed Order placements due to stockouts.

To obtain the most accurate stock data (for example, when adding items to a cart, performing fulfillment checks, etc.), query the corresponding InventoryEntry. We recommend that you only fetch the data that you need. For example, avoid loading all InventoryEntries for a SKU when you only need supply channel availability or specific stock details.

For non-critical availability checks, such as for displaying a quantity on a product listing page, you can use the availability field in ProductVariant. This provides an overview of stock levels which may lag behind real-time stock levels by a few seconds. However, checking inventory in this manner reduces the need to query the Inventory API directly.
Learn more about InventoryEntry, including querying best practices in our self-paced Inventory modeling module.

Messages and events

To get notified when the stock quantity of an InventoryEntry reaches a threshold, set the reorderPoint and safetyStock thresholds on the stockLevels field of each InventoryEntry. For the Messages sent, see InventoryEntryReorderPoint and InventoryEntrySafetyStock.