Requesting a shipment through the API and checking its status

Summary

With POST /api/wms/shipments the customer's system tells the warehouse "ship this". The shipment arrives already confirmed —it skips draft— and the system tries to reserve stock right away. With GET /api/wms/shipments/{id} you check how it is going. It is the equivalent of Creating a shipment and confirming it.

Before you start

The key and the warehouse ready: see The key, the warehouse and error responses.
The SKUs must exist in the customer's catalog or the warehouse's general catalog.
For anything to be reserved, there must be available stock for that customer in the warehouse.

The fields

Field	Required	Accepts	If left empty
`reference`	No	Text, up to 64. The reference the warehouse sees on screen.	No reference.
`external_ref`	No	Text, up to 128. The order in the customer's system.	It cannot be matched to their order.
`carrier_name`	No	Text, up to 255.	The warehouse fills it in when loading.
`requested_ship_date`	No	A date: `2026-10-09`.	No requested date: it does not count in on-time shipping KPIs and never shows as late.
`ship_to_name`	No	Text, up to 255.	No consignee.
`ship_to_city`	No	Text, up to 255.	No city.
`ship_to_state`	No	Text, up to 64.	No state.
`notes`	No	Free text.	No notes.
`lines`	Yes	At least one line.	422.
`lines[].sku`	Yes	Text, up to 64. Must exist.	422.
`lines[].qty`	Yes	A number greater than zero.	422.
`lines[].uom`	No	Text, up to 16.	The product's base unit.

How stock is reserved

As soon as the shipment is created, the system reserves stock line by line with a fixed rule: what expires first goes out first; among lots with no expiration date, what came in first. It only takes available stock: stock on hold, damaged, quarantined or reserved for another shipment does not count. See Changing stock status.

Everything is covered: the shipment becomes Allocated.
Only part is covered: it reserves what there is and becomes Partially allocated. The rest is not reserved automatically later: someone has to reserve again when more stock comes in.
Nothing is available: it stays Confirmed, with no reservation. The response is still 201: the shipment exists.

Example with a partial reservation

Northern Trading Co. orders 60 cases of NT-1001 and 30 of NT-2040, but only 18 of the second are available:

POST /api/wms/shipments
Authorization: Bearer 7|...
X-Warehouse-Code: DAL-01
Content-Type: application/json
Accept: application/json

{
  "reference": "SO-5512",
  "external_ref": "ERP-2026-5512",
  "carrier_name": "Southern Logistics",
  "requested_ship_date": "2026-10-09",
  "ship_to_name": "Valley Distributors",
  "ship_to_city": "Dallas",
  "ship_to_state": "TX",
  "lines": [
    { "sku": "NT-1001", "qty": 60, "uom": "CS" },
    { "sku": "NT-2040", "qty": 30 }
  ]
}

HTTP/1.1 201 Created
{
  "id": 1204,
  "shipment_number": "SH-NT-00077",
  "status": "partially_allocated",
  "reference": "SO-5512",
  "external_ref": "ERP-2026-5512",
  "lines": [
    { "product_id": 3301, "ordered_qty": 60, "allocated_qty": 60 },
    { "product_id": 3302, "ordered_qty": 30, "allocated_qty": 18 }
  ]
}

The warehouse sees the shipment with the second line short. It can pick and load what there is, or wait for more to come in and reserve again. Whatever it decides shows in the next look-up and in the callback on close.

Looking up the shipment

GET /api/wms/shipments/1204
Authorization: Bearer 7|...
Accept: application/json

It returns the same shape as the create response, with current values. If the id does not exist or belongs to another customer, it returns 404.

The statuses

Value	On screen	Meaning
`confirmed`	Confirmed	Exists but has nothing reserved.
`allocated`	Allocated	Everything ordered is reserved.
`partially_allocated`	Partially allocated	Part of it is reserved.
`loading`	Loading	The warehouse started loading.
`shipped`	Shipped	Closed: the truck left.
`cancelled`	Cancelled	Cancelled at the warehouse.

The look-up does not include the loaded quantity per line; that comes in the "shipment closed" callback. See Callbacks.

What happens next

At the warehouse: the shipment shows up in the list, ready for picking (with no visible mark that it came through the API); operators get the new-shipment notification if the warehouse has it configured.
On loading and closing: stock goes down, the bill of lading and packing list are generated, the outbound charge is created, the customer is emailed if they have it on and the callback goes out. See Closing a shipment and From order to departure.
In the KPIs: it counts toward on-time shipping (against the requested date), fill rate and order cycle time from the moment the request arrived.

Errors

Response	Cause	What to do
422 `unknown_sku`	A SKU does not exist. Nothing is created.	Add the product and resend.
422 with `errors.lines.N.qty`	A quantity is zero, negative or not a number.	Send quantities greater than zero.
422 with `errors.requested_ship_date`	The date cannot be read.	Use `YYYY-MM-DD`.
404 on the look-up	The id does not exist or belongs to another customer.	Use the `id` returned on creation, not the shipment number.

Running out of stock is not an error: the shipment is created anyway, with no reservation or a partial one.

Good practices

Always send the requested date: without it the shipment never shows as late and the warehouse does not know when it is urgent.
Check the status in the response: a partially_allocated or confirmed is an early warning that stock is missing.
One order per destination. Two destinations on the same truck are two shipments.

Frequently asked questions

Can I send the full destination address?

Through the API only name, city and state are accepted. Street, postal code and country are entered at the warehouse, on the shipment. If the customer needs the full address on the bill of lading, it is worth having it set up as one of the customer's ship-to addresses.

Can I ask for a specific lot?

No. The reservation follows the expiration rule. If the customer needs a particular lot, they say so in notes and the warehouse adjusts the reservation on screen.