Skip to content

Documentation

Shipments & labels

Buy a label, fetch the document, list what you have bought, and void what you no longer need.

Buy a label

POST /v1/shipments

The body is a quote request plus the courier and service_code you chose from the rates, and the label_format you want back.

FieldTypeNotes
courierstringRequired. The courier from the rate you chose.
service_codestringRequired. The service_code from that rate.
label_formatstringpdf, zpl or png, if the carrier supports it.
from, to, parcels–Required, exactly as in a quote.
customs, options, deliver_to–As in a quote.
referencestringYour own reference for the consignment.
Request 
curl -X POST https://api.shipstack.example/v1/shipments \
  -H "Authorization: Bearer $SHIPSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10432-attempt-1" \
  -d '{
    "courier": "dpd",
    "service_code": "1^16",
    "label_format": "pdf",
    "reference": "ORDER-10432",
    "from": {
      "name": "Acme Supplies", "line1": "1 Mill Lane",
      "city": "Leeds", "postcode": "LS1 4DL", "country": "GB"
    },
    "to": {
      "name": "Sam Reed", "line1": "44 Bright Street",
      "city": "Bristol", "postcode": "BS1 5TR", "country": "GB"
    },
    "parcels": [
      { "weight_g": 1200, "length_mm": 300, "width_mm": 200, "height_mm": 100 }
    ]
  }'
201 Created 
{
  "id": "shp_01HQ8W3ZK9V2A7",
  "courier": "dpd",
  "service_code": "1^16",
  "service_name": "DPD Next Day",
  "tracking_number": "15012345678901",
  "total": { "amount": 749, "currency": "GBP" },
  "label_format": "pdf",
  "reference": "ORDER-10432",
  "created_at": "2026-09-01T10:24:11Z"
}

Download the label

GET /v1/shipments/:id/label

The document is returned with the appropriate content type: a PDF to print, ZPL to send straight to a label printer, or a PNG.

Save the document 
curl https://api.shipstack.example/v1/shipments/shp_01HQ8W3ZK9V2A7/label \
  -H "Authorization: Bearer $SHIPSTACK_API_KEY" \
  -o label.pdf

International consignments also carry their customs paperwork, such as a CN23, where the carrier issues one.

Retrieve one shipment

GET /v1/shipments/:id
Request 
curl https://api.shipstack.example/v1/shipments/shp_01HQ8W3ZK9V2A7 \
  -H "Authorization: Bearer $SHIPSTACK_API_KEY"

List shipments

GET /v1/shipments

Shipments are returned newest first and paginated by keyset rather than by page number, so results stay stable while new shipments are being created. Follow next_cursor until it is absent.

First page, then the next 
curl "https://api.shipstack.example/v1/shipments?limit=50" \
  -H "Authorization: Bearer $SHIPSTACK_API_KEY"

curl "https://api.shipstack.example/v1/shipments?limit=50&cursor=shp_01HQ8W3ZK9V2A7" \
  -H "Authorization: Bearer $SHIPSTACK_API_KEY"
200 OK 
{
  "shipments": [
    {
      "id": "shp_01HQ8W3ZK9V2A7",
      "courier": "dpd",
      "tracking_number": "15012345678901",
      "total": { "amount": 749, "currency": "GBP" },
      "created_at": "2026-09-01T10:24:11Z"
    }
  ],
  "next_cursor": "shp_01HQ8W3ZK9V2A7"
}

Void a label

POST /v1/shipments/:id/void

Voiding cancels a label you have bought but not used. Carriers set their own rules: most refuse once the parcel has entered the network, and some do not support voiding at all. Check the capability matrix before relying on it.

Request 
curl -X POST https://api.shipstack.example/v1/shipments/shp_01HQ8W3ZK9V2A7/void \
  -H "Authorization: Bearer $SHIPSTACK_API_KEY"