Multi-location inventory

Track product inventory across multiple locations. This feature, updated in April 2023, enables granular inventory tracking and provides location-specific access control through assignments.

InventoryRecord model

The InventoryRecord resource manages location-specific inventory data:

{
  "ID": "",
  "OwnerID": "",
  "AddressID": "",
  "Address": {}, // read-only Address object
  "OrderCanExceed": false,
  "QuantityAvailable": 0,
  "LastUpdated": "2022-01-04T00:00:00.00+00:00",
  "AllowAllBuyers": true,
  "xp": {}
}

Optional assignment model for controlling location access:

{
  "InventoryRecordID": "",
  "BuyerID": "",
  "UserGroupID": ""
}

Key properties and behaviors:

• Context: The InventoryRecord exists within a Product or Product Variant context
• ID: Follows standard writable ID format
• OwnerID: Writable only by Marketplace Owner, otherwise reflects creating Supplier
• Product.Inventory: Remains on Product resource
  • With InventoryRecords: QuantityAvailable shows sum of all records
  • Manual updates not reflected when InventoryRecords exist
• Address: Read-only object derived from provided AddressID
• Multiple records: Allowed for same Product/Address combination
  • Useful for tracking different fulfillment methods
• AddressID: Must be owned by the OwnerID
• AllowAllBuyers: Defaults to true
  • Set false to enable granular assignment control

API endpoints

Product inventory

• GET v1/products/{productID}/inventoryrecords
• GET v1/products/{productID}/inventoryrecords/{inventoryRecordID}
• POST v1/products/{productID}/inventoryrecords
• PUT v1/products/{productID}/inventoryrecords/{inventoryRecordID}
• PATCH v1/products/{productID}/inventoryrecords/{inventoryRecordID}
• DELETE v1/products/{productID}/inventoryrecords/{inventoryRecordID}
• GET v1/products/{productID}/inventoryrecords/assignments
• POST v1/products/{productID}/inventoryrecords/assignments
• DELETE v1/products/{productID}/inventoryrecords/{inventoryRecordID}/assignments

Variant inventory

• GET v1/products/{productID}/variants/{variantID}/inventoryrecords
• GET v1/products/{productID}/variants/{variantID}/inventoryrecords/{inventoryRecordID}
• POST v1/products/{productID}/variants/{variantID}/inventoryrecords
• PUT v1/products/{productID}/variants/{variantID}/inventoryrecords/{inventoryRecordID}
• PATCH v1/products/{productID}/variants/{variantID}/inventoryrecords/{inventoryRecordID}
• DELETE v1/products/{productID}/variants/{variantID}/inventoryrecords/{inventoryRecordID}
• GET v1/products/{productID}/variants/{variantID}/inventoryrecords/assignments
• POST v1/products/{productID}/variants/{variantID}/inventoryrecords/assignments
• DELETE v1/products/{productID}/variants/{variantID}/inventoryrecords/{inventoryRecordID}/assignments

User endpoints

• GET v1/me/products/{productID}/inventoryrecords
• GET v1/me/products/{productID}/variants/{variantID}/inventoryrecords

Additional properties

LineItem.InventoryRecordID

• Only writable before order submission
• References the InventoryRecord for quantity updates
• Required when using Inventory Records
  • Without InventoryRecordID, no inventory updates occur
  • Applies when any Inventory Records exist for the Product

OrderCalculateResponse.LineItemOverrides.InventoryRecordID

• Enables InventoryRecordID override for line items
• No validation against AllowAllBuyers setting
• No validation for explicit assignments

Implementation example

Use case: Store pickup

A business offers three physical locations where customers can pick up their online orders.

Admin setup

1. Create InventoryRecords for each product location:

   POST v1/products/{productID}/inventoryrecords
   

2. Associate each record with the physical location's address

3. Configure available quantities per location

4. Optional: Use assignments to restrict shopper access to specific locations

Shopper workflow

1. Navigate product catalog to item detail page

2. Check available pickup locations:

   GET v1/me/products/{productID}/inventoryrecords?QuantityAvailable=>1
   

3. Add to cart with location selection:

   POST v1/cart/lineitems
   

   Include LineItem.InventoryRecordID to specify pickup location

4. System automatically updates location inventory on order submission

5. Optional: Implement pre-webhooks to require InventoryRecordID on all line items

Related reading

• Inventory management
• Inventory change tracking
• Using Extended Properties