Announce an inbound shipment

The warehouse endpoints let you manage your own products in the Shirtee warehouse and announce inbound shipments. The flow has four steps.

Required scopes: warehouse:read to read, warehouse:write to create and change. For finer control use warehouse:shipment_write, warehouse:shipment_cancel and warehouse:document_write.

1. Create a warehouse product

POST /api/warehouse/products creates a warehouse product with its variants as a draft (DRAFT). The server assigns the article SKU (SWP_ plus 8 characters), the variant SKU is <article SKU>__<color>__<size> and never changes. The product always belongs to the customer of your key. GET /api/warehouse/products lists your products with stock.

2. Check a shipping list (optional)

If you have an Excel shipping list, POST /api/warehouse/shipments/import reads it and returns a proposal for the shipment. The call creates nothing. The file is sent as multipart/form-data in the field file, .xlsx, at most 20 MB. Only the first sheet is read.

3. Announce the shipment

POST /api/warehouse/shipments announces the shipment. It is created with status ANNOUNCED and the number WHS_<id>. Each variant may appear at most once, otherwise the API answers 400 with extra.error = INVALID_ITEMS.

The call is not idempotent: every successful call creates another shipment. After a timeout, do not retry blindly; check GET /api/warehouse/shipments first.

4. Attach documents

POST /api/warehouse/shipments/{shipment_id}/documents attaches a shipping list or delivery note (.xlsx or PDF, at most 20 MB, one file per call). The file type is checked by content; CSV and .xls are rejected with 400 and INVALID_FILE_TYPE. A signed download URL (valid for 15 minutes) comes from GET …/documents/{document_id}/url.

Change and cancel

• PUT /api/warehouse/shipments/{shipment_id} replaces the whole state. Missing fields are cleared, missing items are removed.
• DELETE /api/warehouse/shipments/{shipment_id} cancels. This only works in status ANNOUNCED, otherwise 409 with SHIPMENT_NOT_EDITABLE. The shipment stays retrievable with status CANCELED.

All endpoints with examples are in the API reference.