Learning PathModule

Inventory management

Learn about the InventoryEntry entity.

Copy for LLM

View as Markdown

After completing this page, you should be able to:

Understand how inventory is associated to an SKU and the different representations of the InventoryEntry entity.

Inventory management is the backbone of successful commerce operations. It empowers businesses to meticulously track and control product availability, ensuring a seamless customer experience. While not all products demand rigorous inventory tracking (for example: digital downloads, services, and insurance), it's essential for most physical goods and products susceptible to stock-outs. Inventory management in Composable Commerce touches various aspects of the Project, including Products, Quotes, Carts, Orders, Order returns, and Order Edits. This module focuses on each of these areas, providing a comprehensive understanding of inventory management within the Composable Commerce ecosystem.

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

Understand InventoryEntry

The InventoryEntry entity acts as the single source of truth for the physical stock level of a specific Product Variant at a given location or channel. It's crucial to understand its structure and attributes.

InventoryEntry attributes:

id: a unique identifier automatically generated by Composable Commerce for each InventoryEntry.
version: an integer representing the current version of the InventoryEntry. This value is used for optimistic concurrency control.
key: a user-defined, unique identifier for the InventoryEntry. Setting a key can be beneficial for simplifying queries and updates. For example, you could use a combination of the SKU and warehouse location as the key.
sku: the ProductVariant SKU associated with this InventoryEntry. This attribute links the inventory record to a specific Product Variant. Importantly, the SKU does not have to exist as a Product within Composable Commerce. This allows you to manage inventory for products even before they are fully defined in your product catalog.
supplyChannel: a ChannelReference that indicates the specific channel that supplies this inventory. This is important for multi-channel inventory management, allowing you to track inventory levels separately for different sales channels like online stores, marketplaces, or physical stores.
quantityOnStock: the total amount of stock currently available, calculated as availableQuantity + reserved. This represents the overall physical stock level.
availableQuantity: the portion of the quantityOnStock that is currently available for sale. This value is dynamically updated based on orders, reservations, and other inventory movements. It's crucial to use this field for determining what can be sold to avoid overselling.
minCartQuantity: The minimum quantity of a Line Item, matching the sku and supplyChannel of this InventoryEntry, that can be added to a Cart. Minimum quantities are often used by wholesale retailers.
maxCartQuantity: The maximum quantity of a Line Item, matching the sku and supplyChannel of this InventoryEntry, that can be added to a Cart. A maximum quantity can be used to prevent denial of inventory scenarios.
restockableInDays: an informational field that represents the typical restocking frequency in days. This field's interpretation depends on your business logic and how you utilize it within your application. For instance, you might use it to display estimated restocking times to customers or to trigger automated replenishment processes.
expectedDelivery: an informational field that indicates the estimated date and time of the next restock. Similar to restockableInDays, its meaning is context-dependent and can be leveraged for various purposes within your inventory management workflows.
custom: allows you to add one or more Custom Fields to the InventoryEntry. This provides flexibility in extending the data model to store additional information relevant to your specific inventory management needs. For example, you could use Custom Fields to track batch numbers, expiry dates, or specific storage locations within a warehouse.
createdAt: a timestamp indicating when the InventoryEntry was initially created in the system.
createdBy: information about the user or system that created the InventoryEntry.
lastModifiedAt: a timestamp indicating the last time the InventoryEntry was modified.
lastModifiedBy: information about the user or system that last modified the InventoryEntry.

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 inventory features provided by Composable Commerce. 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 to InventoryEntry are strongly consistent. This means that any changes made to an InventoryEntry are immediately reflected in the data. Use InventoryEntry for:

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

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.
Real-time inventory updates	`InventoryEntry`	Provides immediate visibility into stock changes.
Displaying general availability	`ProductVariantAvailability`	Simplifies data retrieval and is suitable for non-critical displays.
Adding items to a Cart	`InventoryEntry`	Ensures accurate availability check before checkout.

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 and advanced product modeling for strategies to manage this complexity.

Availability in Product Search and Product Projection Search: the ProductVariantAvailability information is also reflected in Product Search and Product Projection Search 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: Product Search and Product Projection Search offer powerful filtering capabilities based on ProductVariantAvailability and channel-specific availability. This makes them valuable for complex product searches. However, 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:

Inventory management

Learn about the InventoryEntry entity.

Understand InventoryEntry.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Understand quantityOnStock.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Product Variant availability: Strong vs. Eventual Consistency.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

InventoryEntry.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

ProductVariantAvailability.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Choose the correct resource.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Important considerations.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}