Labels request

The Shipments platform can generate its own despatch labels, enabling Shipments customers to download labels without having to request them directly from the carrier. This page explains how to get labels for a specific shipment or an individual package within a shipment.

Getting labels is a key part of the Shipment platform workflows, as an unlabelled shipment cannot be despatched. When a shipment is allocated, Shipments can generate delivery labels for all of that shipment’s contents properties.

Labels are usually retrieved before a shipment has been manifested.

Shipments API offers label extensions, which enable customers to specify custom text, images and QR codes on their labels. Each Shipments customer can have a single label extension, which is configured during the onboarding process.

Getting all labels for a shipment

The Get Labels endpoint retrieves all labels for the specified shipment. To call Get Labels, send a GET request to https://api.sorted.com/pro/labels/{shipment_reference}/{format}(/dpi), where {shipment_reference} is the unique reference of the shipment you want to get labels for, {format} is the file format required (either PDF, ZPL or BMP), and {dpi} indicates the resolution required.

Get Labels also has optional parameters;

?include_extension=bool boolean (true/false) parameter enabling you to specify whether you want the returned labels to include your custom label extensions. If you do not provide an include_extension query then the Shipments platform returns label extensions by default.

?rotation=string string (left/right) parameter enabling you to specify whether you want to rotate the label 90 degrees (counter)clockwise. This parameter is only permissible for labels in BMP format.

For a full reference on the Get Labels endpoint, see the Shipments API reference

Example get labels calls

  • GET https://api.sorted.com/pro/labels/sp_00668400124857422605561635799040/zpl - Get all labels for shipment sp_00668400124857422605561635799040 in ZPL format at the default resolution (203 DPI).
  • GET https://api.sorted.com/pro/labels/sp_00668400124857422605561635799040/zpl/300 - Get all labels for shipment sp_00668400124857422605561635799040 in ZPL format at 300 DPI resolution.
  • GET https://api.sorted.com/pro/labels/sp_00668400124857422605561635799040/pdf/600?include_extension=false - Get all labels for shipment sp_00668400124857422605561635799040 in PDF format at 600 DPI resolution, without label extensions.
  • GET https://api.sorted.com/pro/labels/sp_00668400124857422605561635799040/bmp/300?rotation=left - Get all labels for shipment sp_00668400124857422605561635799040 in BMP format at 300 DPI resolution and rotate the label 90 degrees counter-clockwise.

Getting a label for a specific item of contents

The Get Contents Label endpoint retrieves the label for a specific item of shipment contents. To call Get Contents Label, send a GET request to https://api.sorted.com/pro/labels/{shipment_reference}/contents/{contents_reference}/{format}/{dpi}, where {shipment_reference} is the unique reference of the shipment that the contents belong to, {contents_reference} is the unique reference of the contents object you want to get the label for, {format} is the file format required (either PDF or ZPL), and {dpi} indicates the resolution required.

Get Contents Label also has an optional ?include_extension=bool boolean (true/false) parameter enabling you to specify whether you want the returned labels to include your custom label extensions. If you do not provide an include_extension query then Shipments will return label extensions by default.

Example get contents label calls

  • GET https://api.sorted.com/pro/labels/sp_00668400124857422605561635799040/contents/sc_00668412927930827428118192193538/zpl/300 - Get all labels for contents sc_00668412927930827428118192193538 (located within shipment sp_00668400124857422605561635799040) in ZPL format at 300 DPI resolution.
  • GET https://api.sorted.com/pro/labels/sp_00668400124857422605561635799040/contents/sc_00668412927930827428118192193538/pdf/300?include_extension=false - Get all labels for contents sc_00668412927930827428118192193538 (located within shipment sp_00668400124857422605561635799040) in PDF format at 300 DPI resolution, without label extensions.

The labels response

Both Labels API endpoints return document objects.

The document object has four properties:

  • file - A base64-encoded byte array representing the file content.
  • content_type - The document’s format (e.g. application/pdf).
  • document_type - The type of document (e.g. commercial_invoice).
  • dpi - The document’s resolution in DPI.

Labels always have a document_type of label.

Example label response

The example shows a sample label response in ZPL format.

Example label

  {
  "file": (Base64 file data),
  "content_type": "text/plain",
  "document_type": "label",
  "dpi": 203
}

How to use the label data

Once you have downloaded the file data, you will need to decode the file’s Base64 in order to view the label itself. If you are unsure how to do so, see the MDN docs for more information.

Next steps