Products & inventory
The catalog has two layers:- Products are the master records for the items you sell — names, images, categories, identifiers, weight, and dimensions. They are organization-wide and referenced by both inventory and orders.
- Store inventory links a product to a specific store location and records its real-time availability, pricing, quantity, and physical location (aisle, bay, shelf) for efficient picking.
- Products
- Inventory
Manage products in bulk with Create or update products (
POST /v1/products) and read them back with Get products (GET /v1/products).Required fields include name, categories[], weight, dimensions{depth,height,width}, and identifiers[{type,value}]. Optional fields include imageUrls[], externalIdentifier, sku, description, attributes[] (such as WEIGHTED), and details.Limits: up to 1,000 products per request, 10 requests per second per organization.For variable-weight products such as produce or deli items, set the product’s
attributes to WEIGHTED, and set per-unit pricing on the store-inventory entry’s details.weightedItemInfo.valueCentsPerMeasurementUnit (for example, price per pound).Pick & pack
Pick & pack turns an order into an item-level fulfillment job (delivery): the catalog and inventory tell a courier what to pick and where to find it, and the system tracks what was requested, what was picked, and any substitutions. Enable it by includingpick_and_pack in the order’s requirements array when you create the order — see Order requirements. The lifecycle is:
Status updates
Picking progress is reported in real time. When picking finishes, the order reaches
items_pick_complete and is ready for handoff to delivery.pickedItems array describing what the picker actually put in the bag, including the picked sku, quantity, requestedQuantity, weight, priceCents, and any scanned barcode data. For the full field reference and worked examples — straight picks, weighted items, substitutions, and multi-scan items — see the Pick and Pack background page.
You can track the
items_pick_complete status via your order retrieval endpoints, or subscribe to status-change events through Webhooks.Item-level details
When you create an order, each package’sitems array describes the individual items in that package. Per item you can set:
| Field | Type | Description |
|---|---|---|
id | string | The merchant ID of the item |
description | string | The description of the item |
count | integer | The quantity of the item |
dimensions | object | height, width, depth (in centimeters) |
weight | number | The weight of the item in kilograms (kg) |
valueCents | integer | The value of the item in cents |
category | string | The category of the item |
requirements | array | Requirements specific to this item |
barcode | string | Barcode value for this item |
metadata | object | Key-value data to attach to the item |
subItems | array | Nested sub-items (used for pick & pack substitutions) |
Each item carries a single
barcode value. The richer parsed barcode payloads (format, variable weight, price, expiration) appear on the pickedItems results after picking, not on the items you submit — see the Pick and Pack page.subItems array supports substitution handling: a sub-item can carry a sku and a substitution object describing the preference (such as refund or substitute), the source of the decision, and the chosen substituteItems[].
Next steps
Create or update products
Bulk-manage your master product catalog.
Create or update inventory
Track per-store availability, pricing, and aisle location.
Pick and Pack
The full pick-and-pack model and picked-items reference.
Get inventory
Query inventory by store or product.