Quick start
1
Set up your Product Catalog
Define your master product data with names, images, categories, and identifiers
2
Configure Store Inventory
Track per-store availability, pricing, and aisle locations for efficient picking
3
Process Pick and Pack Orders
Handle substitutions, track picking status, and manage item-level fulfillment
Product catalog
Your product catalog serves as the master data source for all items across your stores. It defines the core product information that drives inventory management, order processing, and picking operations.
Key fields
- Required fields:
name,categories[],weight,dimensions{depth,height,width},identifiers[{type,value}]. - Optional fields:
imageUrls[],externalIdentifier,sku,description,attributes[](e.g.,WEIGHTED), anddetails(sizeSpecification,packSizeSpecification,weightedItemInfo).
Rate limits
- 10 requests per second per organization
- 1,000 products per request
API endpoints
- Create/Update Products:
POST /v1/products- Bulk create or update products - List Products:
GET /v1/products- Retrieve products with pagination
Product Catalog Examples
Ready-to-use sample payloads for common product types
Store inventory
Store inventory tracks the real-time availability, pricing, and location of products within each of your store locations. This data powers accurate order fulfillment by ensuring pickers know exactly what’s available and where to find it.
Key fields
- Required field:
available(boolean). - Common fields:
externalProductId,externalStoreLocationId,quantity,valueCents,currency,location{aisle,bay,shelf}.
Weighted items
For variable-weight products (produce, deli items, etc.):- Set the product attribute to
WEIGHTEDin your product catalog - Set per-unit pricing on the store inventory entry’s
details.weightedItemInfo.valueCentsPerMeasurementUnit(e.g., price per pound)
Rate limits
- 10 requests per second per organization
- 10,000 inventory items per request
API endpoints
- Create/Update Inventory:
POST /v1/inventory- Bulk inventory updates - Get Inventory:
GET /v1/inventory- Query inventory with filters:externalStoreLocationId: Filter by store locationexternalProductId: Filter by product- Pagination:
pageIndex,numResultsPerPage
Pick and Pack orders
Orders with Pick and Pack enabled use your product catalog and store inventory to enable precise item-level fulfillment. The system tracks exactly what was requested, what was picked, and any substitutions made during the process.To enable Pick and Pack functionality, include
pick_and_pack in the order.requirements array when creating orders. See the complete list in Order Requirements.Order lifecycle
- Order Creation: Customer places order with specific items with substitution preferences
- Picking: 3rd party courier picks items, handling substitutions as needed
- Status Updates: Real-time updates on picking progress
- Delivery: Order handed off to delivery provider once picking is complete
Sub-item fields
item.subItems[].sku: optional SKU for the specific sub-item being picked.item.subItems[].substitution: object describing substitution preferences and chosen replacements.preference: e.g.,refundorsubstitute.source: who made the decision (e.g., merchant, customer).substituteItems[]: list of{ id, sku, quantity }representing the chosen replacements.
Status
items_pick_complete: emitted when item picking for the order has finished and it is ready for handoff to delivery. Track this status via your order retrieval endpoints and/or subscribe to status change events in Webhooks.
Picked items
Each delivery carries apickedItems array describing what the picker actually put in the bag. The REST response always emits the same fields per item; values are nullable, but fields are never omitted.
A substitution is identifiable by
sku != requestedSku (or equivalently, id == null).
Example — straight pick, packaged item
Example — straight pick, weighted item (single scan)
weight is populated; scannedBarcode is a GS1 in-store label encoding GTIN + weight + price. scans is null because the item was captured in a single scan.
Example — substitution
Example — loose produce (no scan)
Items sold “each” have no physical barcode. Identify bysku.
Example — weighted item with multiple scans
Variable-weight items picked across multiple physical units produce onescans[] entry per scan, each with a parsed GS1 payload. For richer parsed output, read scans[].barcodes[] instead of re-parsing scannedBarcode yourself.