j1.1.0
API Overview
The Inventory Lists API provides comprehensive management capabilities for product inventory records within inventory lists. Use this API to:
- Retrieve current inventory information for products.
- Create and update inventory records with allocation and availability data.
- Manage pre-order and backorder configurations.
- Track stock levels, turnover, and available-to-sell (ATS) quantities.
- Configure perpetual stock for always-available products.
- Handle custom inventory attributes.
Authentication & Authorization
For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request.
The API client must also have at least one of the following OAuth scopes: sfcc.inventory-lists scope for read-only operations and sfcc.inventory-lists.rw for modifications.
You must include the relevant scope(s) in the client ID used to generate the token. For a full list of permissions, see the Authorization Scopes Catalog.
For detailed setup instructions, see the Authorization for Admin APIs guide.
Key Concepts
Product Inventory Record
A product inventory record represents the inventory information for a specific product within an inventory list. Each record contains:
- Product identification: Product ID and name
- Stock information: Current stock level, ATS quantity, turnover
- Allocation: Quantity allocated for sale and reset date
- Availability dates: Expected in-stock dates
- Pre-order/backorder handling: Configuration for products not currently in stock
- Custom attributes: Extensible with custom properties (c_* fields)
Inventory List
An inventory list is a container for product inventory records. Each inventory list is identified by a unique ID and can contain multiple product inventory records.
Available to Sell (ATS)
ATS represents the quantity of items available for purchase. It is calculated as:
ATS = Allocation + PreOrderBackOrderAllocation - InventoryTurnover
Stock Level
Stock level represents the current physical inventory. It is calculated as:
Stock Level = Allocation - InventoryTurnover
Inventory Turnover
Inventory turnover is the sum of all inventory transactions (both increments and decrements) recorded since the allocation reset date. This value can be negative if there are more decrements than increments.
Perpetual Stock
Products with the perpetual flag set to true are treated as always available, regardless of actual stock levels. This is useful for:
- Digital products
- Made-to-order items
- Products with unlimited availability
Pre-order and Backorder Handling
This API supports three modes for handling products that are not currently in stock:
- none: No pre-order or backorder capability
- preorder: Product can be ordered before it becomes available
- backorder: Product can be ordered when temporarily out of stock
Use Cases
Availability & Monitoring
- Verify product stock status and calculated fields (such as ATS) before displaying items to shoppers.
- Monitor current stock levels, allocation, and turnover history to determine replenishment needs.
Lifecycle Management
- Perform the first-time setup for new products or execute a complete inventory reset/replacement.
- Modify specific fields—such as in-stock dates, pre-order/backorder settings, or perpetual stock flags—without affecting the rest of the record.
- Adjust specific allocation amounts dynamically as stock moves.
- Permanently remove records for discontinued products or obsolete entries during list reorganization.
Best Practices
Inventory Updates
- Use PATCH for partial updates: When only updating specific fields, use PATCH to avoid accidentally clearing other data.
- Monitor concurrent updates: Handle 409 Conflict responses appropriately when multiple systems update the same record.
- Validate allocations: Ensure allocation amounts are non-negative.
- Reset dates: Update the allocation reset date when resetting inventory to accurately track turnover.
Stock Management
- Regular synchronization: Keep inventory records synchronized with your inventory management system.
- ATS monitoring: Monitor ATS values to ensure products don't oversell.
- Turnover tracking: Use turnover data to understand inventory movement patterns.
- Perpetual stock usage: Use perpetual stock flag only for appropriate product types.
Pre-order and Backorder
- Clear handling mode: Set appropriate pre-order/backorder handling based on product availability strategy.
- Allocation planning: Use preOrderBackOrderAllocation to control how many pre-orders or backorders are accepted.
- In-stock dates: Provide accurate in-stock dates for pre-order items to set customer expectations.
Security and Access Control
- Read vs. Write access: Use
sfcc.inventory-listsscope for read-only operations andsfcc.inventory-lists.rwfor modifications. - Organization context: Scope all operations to an organization to ensure proper data isolation.
- Global scope: Perform inventory operations at the global level, not site level.
Custom Attributes
The Product Inventory Record schema supports custom attributes using the c_* naming convention. These attributes allow you to extend the standard inventory model with custom business logic and data.
Example custom attributes:
c_supplierCode: Track supplier information.c_warehouseLocation: Store warehouse location data.c_minimumOrderQuantity: Define minimum order quantities.c_leadTime: Track expected lead times.
Rate Limiting
For load shedding and rate limiting information, see Load Shedding and Rate Limiting.
Related APIs
- Products API: Manage product catalog information.
- Inventory Availability API: Query real-time inventory availability across locations.
- Inventory Reservation API: Reserve inventory for orders.
- Orders API: Process orders with inventory allocation.
Let us know so we can improve!