Warehouses
Overview
What a warehouse is and how it fits into stock.
A warehouse is where the seller keeps the goods. The stock balance is per Variant and per warehouse, and the Variant balance is their sum.
Where it fits in the journey: Catalog and stock. The full model, with diagrams: Catalog and inventory.
Endpoints
| Method | Path | What it does |
|---|---|---|
POST | /v1/sellers/{sellerId}/warehouses | Create warehouse |
GET | /v1/warehouses | List warehouses |
GET | /v1/warehouses/{warehouseId} | Get warehouse |
PATCH | /v1/warehouses/{warehouseId} | Update warehouse |
DELETE | /v1/warehouses/{warehouseId} | Archive warehouse |
Rules
- Every seller starts with a default warehouse (
name: "Default"), created together with the seller. A movement withoutwarehouseIdgoes to it. - Only one warehouse is the default. To change it, mark another one with
isDefault: true. DELETEarchives: the movement history keeps pointing to the warehouse. The API refuses (409,warehouse_in_use) to archive the default or a warehouse with balance.- An archived warehouse accepts no movement (
409,warehouse_archived). Reactivate it withPATCHandstatus: "active". - A movement only accepts a warehouse of the same seller as the Variant. From another seller or another account, the response is
404. - A transfer between warehouses writes one outbound and one inbound, and the Variant total does not change. See Record inventory movement.
- Deleting the seller deletes its warehouses.
- No warehouse route talks to the marketplace: they are local records.
Webhooks
warehouse.created, warehouse.updated and warehouse.archived. The default warehouse of a new seller arrives as warehouse.created, right after seller.created. See Receiving webhooks.