Learning PathModule

Model and query inventory

Learn about how you can model and query inventory.

Ask about this Page

Copy for LLM

View as Markdown

After completing this page, you should be able to:

Understand different modeling strategies and efficient query patterns.

Flexibility is available in modeling your inventory data to align with your specific business needs. This typically involves using a combination of supplyChannel attributes, Custom Fields on both supplyChannel and InventoryEntry objects, and the inherent structure of the InventoryEntry object itself. However, effective inventory modeling goes hand-in-hand with efficient querying. You need to be able to access the right inventory data at the right time, especially during critical stages of the customer journey.

Common inventory queries

Let's first outline some common scenarios where you'll need to query inventory data:

Add to Cart: before adding an item to the Cart, you may want to verify that sufficient inventory exists to fulfill the requested quantity. This prevents frustrating scenarios where a customer adds items to their cart only to discover later that they are unavailable.
Update Line item quantity in Cart: similarly, when a customer updates the quantity of an item in their cart, you may need to re-validate inventory levels to ensure that the new quantity can be fulfilled.
Checkout process: a final inventory check is typically performed during or around the checkout payment process, just before the order is placed. This ensures that the inventory hasn't changed since the items were added to the cart and that the order can be fulfilled successfully.
Inventory segmentation: you might need to query inventory based on specific criteria, such as inventory allocated for pickup from a physical store, inventory reserved for a particular sales channel, or inventory with specific characteristics (for example: batch number or expiry date).

Leverage fields for effective queries

Now, let's explore how you can leverage the available fields on supplyChannel and InventoryEntry to structure your data for efficient querying:

Field	Supply Channel	InventoryEntry	Usage example
`key`	Yes	No	A user-defined key that represents business-meaningful values such as warehouse code, inventory type, and SKU (for example, `WH-MAIN-SALE-APPLE`) to enable targeted queries based on specific business criteria.
`name`	Yes	N/A	Helps to filter or display Supply Channels in a user-friendly manner (for example, "Main Warehouse" or "Sydney Store").
`address`	Yes	N/A	Useful for running proximity-based queries, such as finding Supply Channels near a Customer's shipping address.
`geoLocation`	Yes	N/A	Useful for finding Supply Channels within a specific radius for displaying nearby inventory to Customers.
`sku`	N/A	Yes	Useful for retrieving all InventoryEntries associated with a specific SKU. However, be aware this may return more data than necessary when multiple entries exist across different Channels or with different characteristics.
`custom`	Yes	Yes	Custom Fields offer great flexibility for both data modeling and querying. You can create highly targeted queries: for example, a Custom Field can indicate inventory availability for specific Customer Groups, sales Channels, or the inventory bin and aisle number.

Important considerations:

Geolocation-based queries: geolocation-based queries are only supported on the Channel resource. While you can replicate address information on InventoryEntry using custom fields to enable address-based queries, you can't directly query InventoryEntry based on geolocation. Keep this in mind when designing your inventory data model and queries.
Query optimization: when querying inventory, you should strive to fetch only the data that you need for the specific operation. Avoid retrieving all InventoryEntries for a SKU if you only need to check availability for a particular channel or with specific characteristics.
Indexing: if you frequently query inventory based on fields other than the id, consider creating indexes on those fields to improve query performance. Indexes can significantly speed up data retrieval.

Custom inventory query engines

If the provided querying options for Channels and InventoryEntries don't fully meet your needs, and integrating a third-party inventory management service isn't desirable, you can implement a custom inventory query engine. This engine would return InventoryEntry IDs, which you can then use for efficient, low-latency queries to retrieve the available quantity using the Inventory API. Remember that querying a resource by id is the lowest-latency approach to get data. This approach allows you to tailor your querying logic to your specific requirements, potentially incorporating external data sources or complex business rules.

Using a custom query engine alongside the core InventoryEntry functionality offers several key benefits:

Leverage existing features: by keeping your inventory data in commercetools, you continue to benefit from built-in features like:
- ProductVariantAvailability: this entity provides a convenient summary of available quantities across all matching InventoryEntries for a given SKU.
- Cart inventory modes: use the InventoryMode settings on the Cart to manage inventory reservations and prevent overselling based on your business rules.
- Product availability facets: leverage ProductVariantAvailability (which is built from InventoryEntry data) for product filtering and searching based on availability.
Flexibility and customization: the custom query engine gives you the flexibility to:
- Integrate external data: incorporate inventory data and rules from external systems (for example: legacy systems or warehouse management systems) into your queries.
- Implement complex logic: apply sophisticated business rules and algorithms to your inventory queries that go beyond the standard filtering options. This could include custom allocation logic, prioritized inventory sources, or complex pricing tiers based on availability.
- Optimize for performance: tailor your queries to retrieve only the necessary data, minimizing API calls and improving response times. This is especially valuable for high-volume operations or complex inventory structures.
Cost savings: avoid the additional infrastructure and development costs associated with storing inventory data in an external database and building custom APIs to manage that data. Leveraging the existing infrastructure simplifies your architecture, uptime, and reduces operational overhead.
Extensibility: this approach is highly extensible. As your business needs evolve, you can easily adapt and enhance your custom query engine without disrupting the core functionality.

By carefully considering your inventory querying needs during the data modeling phase and leveraging the available fields and query optimization techniques, you can create an efficient and performant inventory management system.

Closed-loop inventory synchronization for data integrity

When integrating your existing systems with the inventory management capabilities, a well-designed, closed-loop architecture is crucial for maintaining data integrity and operational efficiency. This involves careful consideration of several key factors:

System of record: explicitly define which system serves as the single source of truth for inventory data. This is typically your ERP (Enterprise Resource Planning) system or a dedicated inventory management system. Ideally, inventory comes directly from the system of record to the InventoryEntry.
Synchronization frequency: establish how frequently you need to synchronize inventory data between your system of record and commercetools. The ideal frequency depends on your business volume and the volatility of your inventory levels. High-volume businesses with fast changing inventory might require near real-time synchronization, while others may find hourly or daily updates sufficient. The chosen frequency directly impacts the accuracy of your inventory data.
Inventory depletion: determine which systems are authorized to deplete inventory levels. While you may track inventory for display and validation purposes, you need to decide whether Order creation should directly decrease inventory, or if this should be managed by an external system (like the system of record). This decision impacts how you manage inventory consistency across systems.
Order processing speed: minimize the delay between Order creation and its transmission to the inventory system of record. Faster processing ensures more accurate inventory reflection and reduces the risk of overselling, especially in high-volume scenarios. If near real-time order processing is the goal, you can use Subscriptions to help achieve a low-latency integration.

Example flow

Consider the following diagram illustrating a typical closed-loop inventory synchronization flow. Note that this diagram focuses only on commercetools and the inventory system of record, omitting other systems or processes that feed into it.

In this example:

An order is created, potentially decrementing the InventoryEntry based on the chosen InventoryMode.
The order information is sent to a message queue or web-hook for asynchronous processing.
The inventory system of record receives the order information, updates its internal inventory levels, and sends an inventory update notification back to commercetools.
The inventory update is received and the corresponding InventoryEntry is updated, ensuring data consistency.

Manage returns and Order Edits

Keep in mind that if you use the returns or Order Edits functionality to handle refunds or order modifications, these actions don't update the InventoryEntry. If your business relies on these features for managing returns and order adjustments, you'll need to implement mechanisms to synchronize these inventory changes with your inventory system of record. This ensures that your inventory data remains consistent across all systems.

By addressing these considerations and establishing a robust closed-loop integration between your systems, you can ensure consistent inventory data across all platforms, minimize errors, and provide a reliable foundation for order fulfillment and customer satisfaction. This proactive approach prevents discrepancies, reduces the risk of overselling and stock-outs, and streamlines your overall commerce operations.

Model and query inventory

Learn about how you can model and query inventory.

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

Leverage fields for effective queries.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Custom inventory query engines.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Closed-loop inventory synchronization for data integrity.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

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