PlatformMarketplacesPricingDashboardStart for free
Warehouses

Create warehouse

Creates a warehouse for a seller.

POST
/v1/sellers/{sellerId}/warehouses

Use it when the seller keeps stock in more than one place. The default warehouse already exists, because it is born with the seller. Here you create the others.

Send name and, to link it to your ERP, externalId, which is unique within the seller. With isDefault: true, the new warehouse is born as the default and the previous one stops being it. Without it, the default stays the same.

curl -X POST "$BACKEND_URL/v1/sellers/$SELLER_ID/warehouses" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Campinas branch","externalId":"CD-02"}'

The response is 201 with the warehouse. The warehouse.created event reaches your webhooks. If the new one is the default, the previous default gets warehouse.updated.

Repeat with the same Idempotency-Key and the same body if the network fails: you get the original response and no new warehouse.

Common errors

  • 404: the seller does not exist or belongs to another account.
  • 409 with details.field = "externalId": another warehouse of the same seller already uses this externalId.

Authorization

api_key
headerAuthorizationBearer <token>

API key (mk_...)

Path Parameters

sellerId*string

Seller the new resource belongs to.

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid

Header Parameters

Idempotency-Key?string

Optional. A unique value (for example a UUID), 1 to 255 characters, that makes the request safe to retry: repeating it with the same body within 24h returns the original response with Idempotency-Replayed: true instead of running the operation again. Scoped to your account. Reusing it with a different body returns 409.

Length1 <= length <= 255

Request Body

application/json
  1. body

A new warehouse of the seller in the path.

name*string

Display name of the warehouse. Required, 1 to 200 characters; leading and trailing spaces are removed.

Length1 <= length <= 200
externalId?|

Optional. Your own identifier for this warehouse, 1 to 120 characters after trimming. Must be unique within the seller. Accepts null.

Length1 <= length <= 120
isDefault?true

Optional. Send true to make this the seller's default warehouse right away, replacing the current one. Omit it to leave the current default in place. false does not exist: a new warehouse is not the default unless you ask.

Value intrue

Response Body

The created warehouse.

application/json
  1. response

A place where a seller keeps stock. Inventory is counted per variant and warehouse.

id*string

Opaque unique identifier of the warehouse, generated by the API. Use it in the /v1/warehouses/{warehouseId} routes and as warehouseId of an inventory movement.

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
sellerId*string

The seller that owns this warehouse. A warehouse never moves to another seller.

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
name*string

Display name of the warehouse.

externalId*|

Your own identifier for this warehouse, such as its code in your ERP, so you can find the record without storing ours. null when it was never set. Unique within the seller.

isDefault*boolean

true for the seller's default warehouse: the one an inventory movement uses when it names no warehouse. A seller has exactly one, created together with the seller. To change it, send isDefault: true for another warehouse.

status*string

Lifecycle state. An active warehouse takes inventory movements and shows in the balance of every variant of the seller. An archived one stays for the ledger history and takes no new movement.

Value in"active""archived"
createdAt*string

When the warehouse was created, in ISO-8601 (UTC).

Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Formatdate-time
updatedAt*string

When the warehouse was last changed, in ISO-8601 (UTC).

Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Formatdate-time
curl -X POST "https://example.com/v1/sellers/b6a1c0de-3f0c-4f53-9c6e-2a1d7d3b9e10/warehouses" \  -H "Content-Type: application/json" \  -d '{    "name": "Overflow warehouse",    "externalId": "erp-wh-02"  }'
{  "id": "b7e2a1c4-5d3f-4e8a-9b6c-2f1d0a8e7c35",  "sellerId": "3d1c8a52-7f0e-4b0a-8a65-9c1b2f6d7e01",  "name": "Default",  "externalId": null,  "isDefault": true,  "status": "active",  "createdAt": "2026-10-10T12:00:00.000Z",  "updatedAt": "2026-10-10T12:00:00.000Z"}

Overview

What a warehouse is and how it fits into stock.

List warehouses GET

Lists the account warehouses, paginated.