# Inventory management

Inventory management tracks product availability across Products, Quotes, Carts, Orders, Order returns, and Order Edits.

Before we start, let's familiarize ourselves with the core component of inventory management: the `InventoryEntry` entity.

#### Understand InventoryEntry

The [InventoryEntry](/urn?urn=ctp%3Aapi%3Atype%3AInventoryEntry) entity acts as the single source of truth for the physical stock level of a specific Product Variant at a given location or Channel. Each `InventoryEntry` tracks several key aspects:

- **Identity and linking**: each entry has a unique `id`, a user-defined `key` for simplified queries, and an `sku` field that links the record to a specific Product Variant. The SKU doesn't have to exist as a Product, allowing you to manage Inventory for Products before they are fully defined.
- **Stock and availability**: the `quantityOnStock` field represents the total stock level, while `availableQuantity` reflects the portion available for sale (dynamically updated based on Orders and reservations). Cart quantity boundaries (`minCartQuantity` and `maxCartQuantity`) can restrict how many units a Customer can add.
- **Supply Channel association**: the `supplyChannel` field indicates the specific Channel that supplies the Inventory, enabling multi-Channel Inventory management with separate tracking for online stores, marketplaces, or physical stores.
- **Restocking information**: informational fields (`restockableInDays` and `expectedDelivery`) support display of estimated restock times and automated replenishment workflows.
- **Extensibility**: the `custom` field lets you add Custom Fields to store additional information relevant to your Inventory needs (for example, batch numbers, expiry dates, or storage locations).

For the complete list of `InventoryEntry` fields and their types, see [InventoryEntry](/urn?urn=ctp%3Aapi%3Atype%3AInventoryEntry) in the API reference.

#### Understand quantityOnStock

The `quantityOnStock` attribute within an `InventoryEntry` is central to managing product availability effectively. However, its use can be tailored to your specific business rules and inventory management strategies.

Here are some potential use cases for `quantityOnStock`:

- **Aggregated inventory:** in scenarios with multiple warehouses or fulfillment centers, `quantityOnStock` can represent the total available stock across all locations. This aggregated view simplifies availability checks but requires careful management to avoid overselling from individual locations.
- **Virtual inventory:** `quantityOnStock` can be used to represent a calculated value that goes beyond physical stock levels. This might include anticipated incoming shipments, pre-ordered items, or stock allocated for specific channels or promotions. Using virtual inventory allows for greater flexibility but demands accurate forecasting and management to prevent discrepancies between virtual and actual stock levels.
- **Buffered inventory:** safety buffers, either positive or negative, can be applied to the `quantityOnStock` to mitigate risks associated with inventory fluctuations. Negative buffers account for potential delays in inventory updates or in-transit inventory, preventing overselling. Conversely, positive buffers might represent expected incoming stock, allowing for pre-orders or backorders.

The key takeaway is that the effective meaning of `quantityOnStock` is determined by your business logic and how you leverage the available inventory features. You should define what this value represents within your system and ensure consistent application of your chosen logic across all integrations and processes. This clarity is essential for accurate inventory reporting, effective order management, and preventing stock-outs or overselling scenarios.

#### Product Variant availability: Strong vs. Eventual Consistency

Product Variants have a system generated field named `availability` (of type:`ProductVariantAvailability`), containing all `InventoryEntry` records for a SKU. The values are added to the Product by the system using an eventually consistent approach. This means there's a distinction between the strongly consistent inventory data stored in `InventoryEntry` records and the aggregated representation of availability on the `ProductVariant` itself.

##### InventoryEntry

As the source of truth for inventory, updates directly to an `InventoryEntry` are strongly consistent. This means updates such as `AddQuantity` are immediately reflected in the data. However, updates to an `InventoryEntry` resulting from Order operations using the `ReserveOnOrder` or `TrackOnly` inventory modes are [eventually consistent](/api/general-concepts.md#eventual-consistency). Additionally, reservations on Carts that use the `ReserveOnCart` [Inventory Mode](/api/projects/carts.md#inventorymode) are also [eventually consistent](/api/general-concepts.md#eventual-consistency). These operations can take up to 10 seconds to change the `availableQuantity` or `quantityOnStock` of an `InventoryEntry`. Learn more about [using the ReserveOnCart Inventory Mode](/tutorials/reserve-stock-on-cart.md).

Use `InventoryEntry` for:

- **Order fulfillment:** ensuring accurate stock deductions when an order is placed.
- **Near real-time inventory views:** Displaying current stock levels.

Instead of polling an `InventoryEntry` to check `quantityOnStock`, you can detect when the inventory is out of stock by [subscribing](/api/projects/subscriptions.md) to the [`InventoryEntryOutOfStockMessage`](/api/projects/messages/product-catalog-messages.md#inventoryentry-out-of-stock). This message is published when `quantityOnStock` of an `InventoryEntry` reaches 0. This is useful when working with [eventually consistent](/api/general-concepts.md#eventual-consistency) inventory operations, where changes may take up to 10 seconds to be reflected. See [Inventory checks and consistency](/api/inventory-overview.md#inventory-checks-and-consistency) for more information.

##### ProductVariantAvailability

The `ProductVariantAvailability` object on the `ProductVariant` is eventually consistent and provides a convenient summary of available quantities across all matching `InventoryEntries` for a given SKU. It simplifies availability checks without querying multiple `InventoryEntry` resources. However, updates to `ProductVariantAvailability` are asynchronous, meaning there can be a slight delay between an inventory change and its reflection in this field. Use `ProductVariantAvailability` for:

- **Product page displays:** showing general availability information to customers browsing your online store. This can be useful for determining which Product Variants can be added to the Cart.
- **Non-critical availability checks:** suitable for scenarios where a minor delay in availability information is acceptable.

##### Choose the correct resource

| Operation | Recommended resource | Reason |
| :--- | :--- | :--- |
| Order fulfillment | `InventoryEntry` | Guarantees accurate stock information for critical operations. Use the `ReserveOnCart` or `ReserveOnOrder` [Inventory Modes](/api/projects/carts.md#inventorymode) to ensure availability of Line Items when ordering a Cart. |
| Near real-time inventory updates | `InventoryEntry` | Provides near immediate visibility into stock changes. |

##### Important considerations

**Impact of multiple `InventoryEntries` on Product size**: keep in mind that having numerous `InventoryEntries` associated with a single SKU will increase the size of the `Product` JSON object. This is because the `ProductVariantAvailability` field, which aggregates data from all related `InventoryEntries`, is part of the `Product` data structure. If you have a large number of `InventoryEntries` per SKU, consider the potential impact on performance and API response times, especially for product-heavy operations. Refer to the documentation on [product limits](/api/limits.md#product-catalog) and [advanced product modeling](/learning-model-your-product-catalog/advanced-product-data-modeling/overview.md) for strategies to manage this complexity.

**Availability in Product Search and Product Projection Search**: the `ProductVariantAvailability` information is also reflected in [Product Search](/api/projects/product-search.md#boolean-fields) and [Product Projection Search](/api/projects/product-projection-search.md#filter-by-product-variant-availability) to enable filtering and querying products based on availability. However, similar to the `ProductVariant` itself, the synchronization of availability data to Product Search and Product Projection Search is asynchronous. This introduces an additional layer of eventual consistency, meaning the availability information in Product Search and Product Projection Search might lag slightly behind the actual `ProductVariantAvailability`.

**Key considerations for Product Search and Product Projection Search:**

- **Increased eventual consistency:** be mindful that availability data in Product Search and Product Projection Search experiences a longer synchronization delay compared to the `ProductVariant` itself.
- **Filtering and querying:** use [Product Search availability filters](/api/projects/product-search.md#boolean-fields) or [Product Projection Search availability filters](/api/projects/product-projection-search.md#filter-by-product-variant-availability) for product queries based on availability. Keep in mind the eventual consistency when using these features and consider the potential for slight discrepancies between search results and real-time inventory levels.

By understanding the different levels of consistency and the trade-offs between strong and eventual consistency, you can choose the appropriate strategy for using inventory data.

The following diagram illustrates the synchronization flow:

```mermaid
graph LR
  subgraph Orders
	  E[Order <br> ReserveOnOrder/TrackOnly]
  end
  subgraph Inventory
	  A[InventoryEntry]
  end
  subgraph Products
	  B[Product <br> - ProductVariantAvailability]
  end
  subgraph Product Search
	  C[Product Search]
  end
  subgraph Product Projection Search
	  D[Product Projections <br> Search]
  end

  E -- Asynchronous update<br/>up to 10s --> A
  A -- Asynchronous sync --> B
  B -- Asynchronous sync --> C
  B -- Asynchronous sync --> D
```

## Related pages

- [Area overview page with navigation](/learning-model-your-product-catalog.md)
- [Previous page: Overview](/learning-model-your-product-catalog/inventory-modeling/overview.md)
- [Next page: Manage inventory with the Cart](/learning-model-your-product-catalog/inventory-modeling/cart-inventory.md)