Skip to main content

Download Order Labels

GET 
/api/pinnacle/instances/:instance/orders/:order/labels

Downloads the order's piece labels from Pinnacle as a file attachment named pinnacle-labels-{tracking_number}.{pdf|zpl}. Each request fetches the labels live from Pinnacle (requests are throttled), so it always returns Pinnacle's current copy.

Not yet available to API tokens

This endpoint currently requires session authentication; Personal Access Token scope support is in progress.

Query: format (optional, pdf or zpl, case-insensitive, default pdf). The response is a file, not JSON: application/pdf for PDF labels, text/plain; charset=UTF-8 for ZPL (raw printer commands for thermal label printers). Any other format returns 422.

Errors (JSON { message, code }):

  • 422 not_registered — the order was never registered with Pinnacle (no tracking number, or a placeholder created while shipping-provider dispatch was disabled).
  • 422 cancelled — Pinnacle cancelled or closed the order, so its documents are no longer available.
  • 404 not_available — Pinnacle has no labels for the order (or returned an empty document).
  • 422 api_error — Pinnacle refused or failed the request; the message carries Pinnacle's reason.
  • 404 when the order does not belong to the instance.

Check can_download_documents / documents_unavailable_reason on the order (GET …/orders/{order}) to know in advance whether the download is possible.

Authentication: requires a Bearer token (Personal Access Token).

Requires the integrations.show permission; without it the request is refused with 403.

Request​

Responses​

OK

Response Headers
    Content-Type
    Content-Disposition