Skip to main content

Downloading Shipping Labels

Audience: developers integrating a merchant's order system, ERP or customer-service tooling with Logitrail's Outbound Shipment API, who need the carrier shipping label PDF of a shipment — for example to attach it to a support case or to reprint it.

This guide explains how to fetch download links for shipping labels, which shipments have them, and how to handle the links safely. It assumes you already have Logitrail API credentials with the outbound_shipments:read scope — see Authentication if you don't.

1. Which shipments have labels​

Labels are available only for shipments that Logitrail booked through its own carrier integration. For any other shipment — for example one booked with a carrier in another way — no labels are returned.

Every outbound shipment returned by GET /v1/outbound-shipments and GET /v1/outbound-shipments/{id} carries a labelsAvailable flag. Check it before asking for labels.

2. Labels of one shipment​

GET /v1/outbound-shipments/{id}/labels
Authorization: Bearer <access_token>
x-logitrail-merchant-id: <your merchant id>
{
  "shipment_id": "6706a1f2c3b4d5e6f7a8b9c0",
  "shipment_number": "S5GH7800",
  "labels": [
    {
      "index": 1,
      "tracking_code": "S5GH7800-1",
      "download_url": "https://…",
      "download_url_expires_at_utc": "2026-10-11T18:05:00.000Z"
    }
  ]
}

There is one label per parcel, in parcel order. Add ?parcel_index=2 to get only the second parcel's label.

3. Labels of every shipment of an order​

GET /v1/outbound-shipments/labels?order_id={order id}

The response lists every outbound shipment of the order, newest first. Each entry has labels_available and labels; labels is empty when no labels are available for that shipment.

  • A download_url expires 5 minutes after it is issued (download_url_expires_at_utc). Fetch a fresh link every time you need the label, and download the PDF right away.
  • Anyone holding the link can download the PDF until it expires — no credentials are needed. Treat it like a password: do not log it, store it, or send it to anyone who should not see the label.
  • The link returns the PDF directly, so it can be opened in a browser or downloaded with any HTTP client.

5. Errors​

Errors have the body { "message", "error_code", "details" }.

Statuserror_codeMeaning
400—order_id or parcel_index is missing or invalid.
404shipment_not_foundThe shipment does not exist, or it belongs to another merchant.
404parcel_not_foundThe shipment has no parcel with that parcel_index.
404order_not_foundThe order does not exist, or it belongs to another merchant.
409labels_not_availableNo labels are available for this shipment (see section 1).
502labels_fetch_failedThe labels could not be retrieved right now. Retry later.