Inventory overview

Overview of the concepts related to inventory management.

Ask about this Page
Copy for LLM
View as Markdown

Inventory tracks sellable stock per SKU across supply locations. It enables you to manage stock levels, enforce purchase limits, and reserve stock to ensure availability during the checkout process.

General concepts

Inventory modes

InventoryMode defines how stock is managed when Line Items are added to a Cart. The following table summarizes the available inventory modes:
Inventory ModeDescriptionUse Cases
NoneThe default inventory mode. Stock levels are not checked or updated when Line Items are added to the Cart.- Products that are always in stock (for example: digital goods).
- Businesses that do not require inventory management.
- Businesses that manage their inventory externally.
TrackOnlyStock levels are checked when Line Items are added to the Cart, but stock is only updated when the Order is created.
Allows Orders to be placed even if the required stock is not available at that moment.		- Products with high stock levels where reservations are unnecessary.
- Businesses that want to monitor stock without reserving it.
- Allows for overselling scenarios and accepting backorders.
ReserveOnOrderStock levels are checked when Line Items are added to the Cart, but stock is only reserved and updated when the Order is created.
Prevents Orders from being placed if the required stock is not available at that moment.		- Standard inventory management where stock is only deducted upon Order creation.
- Businesses that want to avoid holding stock before the order is finalized.
ReserveOnCart BETAStock levels are checked and reserved when Line Items are added to the Cart. Reservations expire after a set time.- High-demand products where stock needs to be secured during checkout.
- Businesses that want to minimize the risk of stockouts during checkout.

Inventory modes can be set at the Cart level and/or individually for each Line Item. The Line Item's inventory mode takes precedence over the Cart's mode.

Manage inventory with InventoryEntry

An InventoryEntry represents stock for a single SKU in an optional supply Channel. Only one InventoryEntry exists for each SKU and supply Channel pair.

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.
These limits are enforced when you create or update a Cart, and the Line Item's SKU and supply channel match the Inventory Entry. 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.

The following applies:

  • Quantity limits are independent of InventoryMode: the minCartQuantity and maxCartQuantity limits are enforced regardless of which InventoryMode is used (None, TrackOnly, ReserveOnOrder, or ReserveOnCart). The inventory mode controls when and how stock is reserved or updated, but does not affect quantity limit enforcement.
  • Each Line Item is evaluated independently: each Line Item that matches an InventoryEntry record is evaluated independently against that InventoryEntry's defined quantity limits, regardless of whether other Line Items in the Cart use the same SKU, Product Variant, or supply Channel. This applies both when you have multiple Line Items for the same SKU and supply Channel (for example, distinguished by Custom Fields) and when you have Line Items for the same SKU across different supply Channels, allowing you to enforce distinct quantity constraints per Line Item context.
When you introduce or change limits, it can potentially affect Line Items that are already present in Carts. For more information, see the Set Inventory Limits update action documentation.

Enforcement scenarios

The following table details when quantity limits are enforced:

ScenarioEnforcementNotes
Cart creationYesIf any Line Item exceeds its quantity limits, the Cart creation fails.
Cart updateYesIf any Cart update action results in a Line Item violating quantity limits, the entire request fails.
Order creation from CartYesQuantity limits are enforced when creating an Order from a Cart. If any Line Item in the Cart violates the current limits (for example, after limits change or for Frozen Carts), the order creation fails.
Order EditsNoQuantity limits are not enforced during order edits.
Order ImportsNoQuantity limits are not enforced during order imports.
While Composable Commerce enforces quantity limits 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.

Stock level notifications BETA

To stay informed about inventory changes, you can set up stock level notifications. These notifications alert you when the quantityOnStock amount of an InventoryEntry falls below or rises above certain thresholds.
To get notified, set your required threshold amounts on the stockLevels field of each InventoryEntry.
FieldPurposeTypical use casesMessage sent
reorderPointEarly-warning threshold indicating stock is low and should be replenished before running out during lead time.- Trigger notifications or automations (ERP/OMS) to create purchase orders.
- Show "low stock" messaging on the storefront.
- Highlight low stock levels in internal dashboards.		InventoryEntryReorderPoint
safetyStockCritical minimum threshold showing that inventory has reached an urgent, buffer-level quantity.- Signal a critical low-stock situation.
- Allow OMS/ERP to limit or stop selling.
- Display "very low stock" or hide items on certain sales channels.		InventoryEntrySafetyStock

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:

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.

Supply channels versus distribution channels

Composable Commerce distinguishes supply channels (where stock is held) from distribution channels (used for price selection). An InventoryEntry optionally links to a supply channel through the supplyChannel field. A Cart bound to a Store filters available stock and prices using the Store's configured channels.

To fulfill a single SKU from multiple inventory locations, you can add multiple Line Items to the Cart, each specifying a different supply channel.

Reservations BETA

A Reservation temporarily holds stock for an individual Line Item in a Cart. 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.
When a reservation is created, the availableQuantity of the corresponding InventoryEntry is decreased by the reserved amount. When a reservation expires, or is released, the availableQuantity is increased accordingly.
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.

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: