Labels¶

Last updated October 19, 2026

Base URL

All examples assume BASE_URL=https://api.omnishelf.com and OMNI_KEY=omni_sk_YOUR_KEY.

Labels are returned as base64-encoded PDF inside JSON — no signed URLs, no binary streaming — with the parcel_id and tracking_number travelling alongside each one. Decode label_base64 with a standard base64 decoder (not base64url) and write it to a .pdf file.

Labels are fetched live on every call

Each label request fetches the PDF from the carrier system at call time. Expect about 2 seconds per call that returns a label, against about 0.5 seconds for a label_not_ready response. Set your client timeouts accordingly.

The PDF bytes differ on every call even when the label has not changed: only the PDF's /CreationDate and file /ID differ, and the printed label is the same. Don't dedupe labels or detect changes by hashing the file. Key them by parcel_id and tracking_number instead.

GET /v1/fulfilment-orders/{order_id}/labels¶

Every parcel label on the order, across all its shipments, in one request.

Path parameters¶

Parameter	Example	Notes
`order_id`	`OMN-KONW-00042`	Omnishelf order ID.

Request¶

curl -s "$BASE_URL/v1/fulfilment-orders/OMN-KONW-00042/labels" \
  -H "Authorization: Bearer $OMNI_KEY"

Response — 200¶

{
  "data": {
    "order_id": "OMN-KONW-00042",
    "shipment_count": 2,
    "parcel_count": 3,
    "labels_available": 2,
    "labels": [
      {
        "parcel_id": "OMN-KONW-00042-1-1",
        "parcel_number": 1,
        "tracking_number": "1Z0K49Y40312446341",
        "carrier": "ups",
        "label_format": "pdf",
        "label_base64": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL1BhZ2UvUGFyZW50...",
        "content_length": 24817,
        "error": null,
        "shipment_id": "OMN-KONW-00042-1"
      },
      {
        "parcel_id": "OMN-KONW-00042-2-1",
        "parcel_number": 1,
        "tracking_number": "9405511899223197428431",
        "carrier": "stamps_com",
        "label_format": null,
        "label_base64": null,
        "content_length": null,
        "error": "label_not_ready",
        "shipment_id": "OMN-KONW-00042-2"
      }
    ]
  }
}

A 200 is returned as long as at least one label is available. Per-parcel failures appear on the entry itself as error (label_not_ready or fetch_failed) with null label fields, so one missing label never blocks the rest. Compare labels_available to parcel_count to know whether to come back later.

Decode every available label to disk:

curl -s "$BASE_URL/v1/fulfilment-orders/OMN-KONW-00042/labels" \
  -H "Authorization: Bearer $OMNI_KEY" \
  | jq -r '.data.labels[] | select(.label_base64 != null) | .parcel_id + " " + .label_base64' \
  | while read -r id b64; do echo "$b64" | base64 -d > "$id.pdf"; done

Errors¶

404 not_found — unknown order, or another seller's order.
409 label_not_ready — the order has no shipments yet, or not a single parcel has a label.
413 too_many_parcels — more than 20 parcels on the order. Fetch per shipment instead.

GET /v1/shipments/{shipment_id}/labels¶

Every parcel label for a single shipment.

Path parameters¶

Parameter	Example	Notes
`shipment_id`	`OMN-KONW-00042-1`	Omnishelf shipment ID.

Request¶

curl -s "$BASE_URL/v1/shipments/OMN-KONW-00042-1/labels" \
  -H "Authorization: Bearer $OMNI_KEY"

Response — 200¶

{
  "data": {
    "shipment_id": "OMN-KONW-00042-1",
    "carrier": "ups",
    "parcel_count": 2,
    "labels_available": 2,
    "labels": [
      {
        "parcel_id": "OMN-KONW-00042-1-1",
        "parcel_number": 1,
        "tracking_number": "1Z0K49Y40312446341",
        "carrier": "ups",
        "label_format": "pdf",
        "label_base64": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL1BhZ2UvUGFyZW50...",
        "content_length": 24817,
        "error": null
      }
    ]
  }
}

Errors¶

404 not_found — unknown shipment, or another seller's shipment.
409 label_not_ready — no parcel on the shipment has a label yet.
413 too_many_parcels — more than 20 parcels. Fetch them one at a time.

GET /v1/parcels/{parcel_id}/label¶

One label for one box. The narrowest and cheapest label call.

Path parameters¶

Parameter	Example	Notes
`parcel_id`	`OMN-KONW-00042-1-2`	Omnishelf parcel ID.

Request¶

curl -s "$BASE_URL/v1/parcels/OMN-KONW-00042-1-2/label" \
  -H "Authorization: Bearer $OMNI_KEY"

Response — 200¶

{
  "data": {
    "parcel_id": "OMN-KONW-00042-1-2",
    "parcel_number": 2,
    "tracking_number": "1Z0K49Y40301020133",
    "carrier": "ups",
    "label_format": "pdf",
    "label_base64": "JVBERi0xLjQKJeLjz9MKNSAwIG9iago8PC9UeXBlL1BhZ2UvUGFyZW50...",
    "content_length": 24790
  }
}

Errors¶

404 not_found — unknown parcel, or another seller's parcel.
409 label_not_ready — the parcel has no label yet. Retryable.
502 label_fetch_failed — the label exists but the carrier system did not return it. Retryable.