Skip to main content

OrderShippingLabels

A short-lived link to an order's printable labels, rendered as a single PDF with one page per package. It is the only resource in the API that is not a stored record: it is produced on demand by GET /orders/{id}/shippingLabels and never kept.

{
  "url": "https://storage.googleapis.com/.../W3kJpzQm9q4LV2BdH7sNuT.pdf?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Expires=3600&X-Goog-Signature=...",
  "expiresAt": 1778514703
}
FieldMeaning
urlA signed link to the PDF. It carries its own authorization, so fetching it needs no API key.
expiresAtWhen the link stops working, in seconds since epoch. One hour after it was issued.

The host and path are storage details rather than contract. Treat the whole URL as opaque and follow it exactly as given.

Treat the URL as a secret with a short fuse​

The link needs no API key, which is what makes it convenient and what makes it sensitive. Anyone holding it can read the label until it expires.

Fetch the PDF server-side as soon as you receive the link, and store the file yourself if you need to keep it. Do not put the URL in an email, a queue message, or anything a person opens later. One hour is deliberately too short for that, and it is not a limit you should design around.

Every call renders afresh​

There is no caching. Each request re-renders the PDF from the order's current packages and signs a new URL, so the label always matches the order. Two consequences follow:

  • Ask again rather than storing the link. A second call is cheap and always correct, where a stored link is stale the moment the order changes and dead within the hour.
  • The label follows packageCount. Change packageInfo.packageCount and the barcodes are regenerated, so the next render has a different number of pages.

What is on the label​

A6 pages, one per package, each carrying one Code 128 barcode from the order's barcodes array. An order with packageCount: 3 produces a three-page PDF with three distinct barcodes.

An order with no barcodes cannot produce a label and answers 422 order_invalid_fields with param: "barcodes". Orders created through this API get their barcodes at creation time, so this normally only affects orders that reached your account another way.