Create a shipment
Create a shipment for an order and attach a track and trace code so the customer can follow their delivery.
Endpoint
POST /v2/orders/shipments
Request
{
"orderId": 20131,
"status": "IN_TRANSIT",
"expectedDeliveryAt": "2026-03-26T14:00:00.000Z",
"items": [
{
"orderItemId": 30565,
"quantity": 2,
"name": "Wireless Bluetooth Headset Pro",
"sku": "WBH-PRO-500"
}
],
"trackAndTraces": [
{
"code": "3SYZTR20394857",
"carrierId": 1
}
]
}
Response
{
"id": "432b65ee-9b2e-4c1c-951d-0cc6e3e37349",
"orderId": 20131,
"status": "IN_TRANSIT",
"expectedDeliveryAt": "2026-03-26T14:00:00.000Z",
"createdAt": "2026-03-24T11:06:21.579Z",
"lastModifiedAt": "2026-03-24T11:06:21.579Z",
"items": [
{
"id": "50dd3075-a113-409c-bb5a-633b0160570a",
"shipmentId": "432b65ee-9b2e-4c1c-951d-0cc6e3e37349",
"orderItemId": 30565,
"quantity": 2,
"name": "Wireless Bluetooth Headset Pro",
"sku": "WBH-PRO-500",
"createdAt": "2026-03-24T11:06:21.579Z",
"lastModifiedAt": "2026-03-24T11:06:21.579Z"
}
],
"trackAndTraces": [
{
"id": "b29acd7b-4031-4b6a-9510-d2451f5eb9fc",
"shipmentId": "432b65ee-9b2e-4c1c-951d-0cc6e3e37349",
"code": "3SYZTR20394857",
"carrierId": 1,
"createdAt": "2026-03-24T11:06:21.579Z",
"lastModifiedAt": "2026-03-24T11:06:21.579Z"
}
]
}
How it works
Use POST /v2/orders/shipments to create a shipment linked to an order. Each shipment contains one or more items (referencing order item IDs) and optionally one or more track and trace entries. The status field accepts values like CREATED, IN_TRANSIT, DELIVERED and CANCELED. For split shipments, create multiple shipments for the same order, each covering a subset of the order items.
Each item must be a product line of the shipment's order. An order line of another order is refused with SHIPMENT_ITEM_ORDER_MISMATCH_ERROR, and a surcharge or other line that is not a product with SHIPMENT_ITEM_NOT_SHIPPABLE_ERROR. Cluster options and bundle components are lines of their own and ship separately. Shipping more than was ordered is accepted, with an OVER_SHIPPED warning in the warnings of the response.