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, imageUrls[], categories[], weight, dimensions{depth,height,width}, and identifiers[{type,value}]. Optional fields include 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 attribute to
WEIGHTED and use details.weightedItemInfo.valueCentsPerMeasurementUnit for per-unit pricing (for example, price per pound).Pick & pack
Pick & pack turns an order into an item-level fulfillment job: 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.picked_items array describing what the picker actually put in the bag, including the picked sku, quantity, requested_quantity, weight, price_cents, 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 picked_items 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.