Getting Shipment Labels

  • Ship
  • api
  • labels

Ship can generate its own despatch labels, enabling Ship 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.

The Labels Request

Getting labels is a key part of all Ship workflows, as an unlabelled shipment cannot be despatched. When a shipment is allocated, Ship generates delivery labels for all of that shipment's contents properties.

Labels are usually retrieved before a shipment has been manifested.

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

Caution

You can only retrieve labels for shipments that have been allocated to a carrier. If you attempt to return labels for an unallocated shipment, Ship returns an error.

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.

Note

Formats are available on an invididual carrier basis. Please check with your technical account manager for the file formats that each carrier supports.

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 Ship 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 Ship 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.

Note

The contents object's unique reference begins with sc and is located in the shipment's contents.reference property. It is not to be confused with the shipment's own reference, which begins with sp and is a unique identifier for the entire shipment.

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 Ship returns label extensions by default.

Note

For full reference information on the Get Contents Label endpoint, see the Ship API reference

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.

Note

Ship's Get Documents endpoint also retrieves documents. However, it cannot return documents with a document_type of label. Ship returns an error if you attempt to retrieve a label through Get Documents. Get Labels and Get Contents Label are the only Ship endpoints that can return labels.

Example Label Response

The example shows a sample label response in ZPL format.

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

Using 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