# Inventory APIs overview

**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](/api/inventory-overview.md).

## APIs in this topic

| Resource | Purpose | Reference |
| --- | --- | --- |
| Inventory | Track stock quantity per SKU and optionally per supply channel. | [Inventory](/api/projects/inventory.md) |
| Reservations | Temporarily reserve available quantity for customers when they add a Line Item to a Cart. | [Reservations](/api/projects/reservations.md) |

## 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](/search.md?urn=ctp:api:type: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](/search.md?urn=ctp:api:type:InventoryEntryDraft), or update them on an existing InventoryEntry using the [Set Inventory Limits](/api/projects/inventory.md#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](/api/projects/inventory.md) or [ProductVariantAvailability](/search.md?urn=ctp:api:type: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](/search.md?urn=ctp:api:type: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](/api/projects/project.md#set-reservation-expiration-in-minutes) 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](/api/inventory-apis-overview.md#inventory-checks-and-consistency).

#### Set the default expiration

To use reservations, you must first [set the Project-level reservation expiration time](/api/projects/project.md#set-reservation-expiration-in-minutes). After you set this default, you'll be able to use the `ReserveOnCart` [InventoryMode](/search.md?urn=ctp:api:type: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](/api/projects/inventory.md#set-reservation-expiration-in-minutes) update action.

#### Reserve items

[Reservations](/api/projects/reservations.md#reservation) expire based on the `reservationExpirationInMinutes` value set in the corresponding [InventoryEntry](/search.md?urn=ctp:api:type: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](/api/general-concepts.md#reference-expansion) 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](/api/types.md#cannotcreatereservation-warning) 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](/api/projects/carts.md#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](/api/types.md#cannotcreatereservation-warning) 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](/api/types.md#cannotcreatereservation-warning) 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](/api/projects/carts.md#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](/api/projects/carts.md#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](/api/projects/carts.md#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](/api/types.md#cannotchangereservationexpiry-warning) 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](/api/projects/carts.md#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:

| Warning | Appearance |
| --- | --- |
| [CannotCreateReservationWarning](/api/types.md#cannotcreatereservation-warning) | Appears when creating a Cart with `ReserveOnCart` but one or more Line Items lack sufficient stock. No reservation is created. See [Reserve items](/api/inventory-apis-overview.md#reserve-items). |
| [CannotUpdateReservationWarning](/api/types.md#cannotupdatereservation-warning) | Appears when updating a Line Item's quantity but the reservation cannot be updated (usually due to insufficient stock). The Line Item quantity remains unchanged. |
| [CannotChangeReservationExpiryWarning](/api/types.md#cannotchangereservationexpiry-warning) | Appears 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:

- [Reserve stock on Cart](/guides/reserve-stock-on-cart.md): learn how to automatically reserve items in a Cart.
- [Reserve stock on demand and freeze prices](/guides/reserve-stock-on-demand.md): learn how to reserve items on demand while freezing all prices.

## Eventual consistency

### Inventory checks and consistency

While [InventoryEntry](/search.md?urn=ctp:api:type: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](/api/projects/inventory.md) are [strongly consistent](/api/general-concepts.md#strong-consistency) and immediately visible.
- Order operations using the `ReserveOnOrder` or `TrackOnly` inventory modes are [eventually consistent](/api/general-concepts.md#eventual-consistency). 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](/api/general-concepts.md#eventual-consistency). 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:
  - [Create Order from Cart](/search.md?urn=ctp:api:endpoint:/{projectKey}/orders:POST)
  - [Cart update actions](/search.md?urn=ctp:api:endpoint:/{projectKey}/carts/{id}:POST) `changeLineItemQuantity`, `addLineItem`, `removeLineItem`, and `setLineItemInventoryMode`.

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](/search.md?urn=ctp:api:type: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](/learning-model-your-product-catalog/inventory-modeling/overview.md) 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](/search.md?urn=ctp:api:type:InventoryEntryReorderPointMessage) and [InventoryEntrySafetyStock](/search.md?urn=ctp:api:type:InventoryEntrySafetyStockMessage).

## Related pages

- [Area overview page with navigation](/api.md)
- [Previous page: Overview](/api/inventory-overview.md)
- [Next page: Inventory](/api/projects/inventory.md)
- [Search documentation and API specs](/search.md)