Download Shipment Label

Downloads the shipping label for a specific shipment. For multi-parcel shipments, this returns a combined label containing all parcels.

Endpoint

GET /v1/shipments/{id}/label

Authentication

API key required. Include it in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Path Parameters

Parameter	Type	Description
id	string	The ID of the shipment to download the label for.

Response

200 OK

A successful request returns a JSON object containing the label content and metadata.

Field	Type	Description
shipment_id	string	The ID of the shipment.
reference_number	string	Your internal reference number.
provider_shipment_id	string	Provider's shipment ID.
label.content	string	Base64-encoded label content.
label.format	string	Label format (pdf, zpl).
label.mime_type	string	MIME type of the label.
label.size	integer	Size of the label in bytes.

Multi-Parcel Labels

For shipments with multiple parcels, the label contains all parcel labels combined into a single file. Each parcel's label is included on a separate page (for PDF) or as concatenated content (for ZPL).

Response Example

{
  "data": {
    "shipment_id": "sh_123456",
    "reference_number": "ORD-2025-001",
    "provider_shipment_id": "20655836776",
    "label": {
      "content": "JVBERi0xLjQKJeLjz9MKMiAwIG9iago8PC9UeXBlL1hPYmplY3QvU3VidHlwZS9JbWFnZS9XaWR0aCAx...",
      "format": "pdf",
      "mime_type": "application/pdf",
      "size": 45678
    }
  },
  "message": "Label retrieved successfully"
}

Error Responses

Status Code	Description
401	Unauthorized - Invalid or missing API key
403	Forbidden - You don't have permission to access this shipment's label
404	Not Found - The specified shipment or its label could not be found
429	Too Many Requests - Rate limit exceeded
500	Server Error - Something went wrong on our end

Example Request

cURL

curl -X GET \
  https://api.shipping-channels.com/v1/shipments/sh_123456/label \
  -H "Authorization: Bearer YOUR_API_KEY"

PHP

<?php
$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.shipping-channels.com/v1/shipments/sh_123456/label', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
    ],
]);

$data = json_decode($response->getBody(), true);

// The label content is base64 encoded
$labelContent = base64_decode($data['data']['label']['content']);

// Get the file extension from format
$extension = $data['data']['label']['format'];

// Save the label to a file
file_put_contents("label.{$extension}", $labelContent);

echo "Label saved as label.{$extension}";

JavaScript

fetch('https://api.shipping-channels.com/v1/shipments/sh_123456/label', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json'
  }
})
.then(response => response.json())
.then(data => {
  // The label content is base64 encoded
  const labelContent = data.data.label.content;
  const mimeType = data.data.label.mime_type;
  const format = data.data.label.format;

  // Convert base64 to blob
  const byteCharacters = atob(labelContent);
  const byteNumbers = new Array(byteCharacters.length);
  for (let i = 0; i < byteCharacters.length; i++) {
    byteNumbers[i] = byteCharacters.charCodeAt(i);
  }
  const byteArray = new Uint8Array(byteNumbers);
  const blob = new Blob([byteArray], { type: mimeType });

  // Create download link
  const link = document.createElement('a');
  link.href = window.URL.createObjectURL(blob);
  link.download = `label.${format}`;
  link.click();
})
.catch(error => console.error('Error:', error));

Label Formats

The label format depends on the label_format specified when creating the shipment.

Format	MIME Type	Description
pdf	application/pdf	PDF format, suitable for standard printers
zpl	text/plain	ZPL (Zebra Programming Language) for thermal printers

Notes

• Labels are only available after a shipment has been successfully created with the provider
• For multi-parcel shipments, all parcel labels are combined into a single file
• The label content is base64 encoded and must be decoded before saving or displaying
• Label availability can be checked via the has_label field in the shipment response