Skip to main content
Now that you have created a shipment, it’s time to generate and download the shipping labels for the parcels in that shipment. You can obtain labels in three main ways:
  1. Use the Retrieve a parcel document or Retrieve multiple parcel documents endpoints and pass the parcel IDs of the parcels you want labels for, with type=label as the document type parameter.
  2. Use any announcement endpoint of Shipments API v3. In their responses you receive a parcels.documents array containing links to the Retrieve a parcel document endpoint; select the document where type is "label" to download the label.
  3. Use the Create and announce a shipment synchronously or Create a shipment with rules and/or defaults and announce it synchronously endpoints for single-parcel shipments (single collo). In this case, the label file is immediately available in the response in parcels.label_file.
Besides using the API, you can also download labels directly from the Sendcloud platform under the Created labels tab. In the platform, each parcel is marked with a status: Printed if the label has already been downloaded, or Not printed if it has not yet been downloaded.
Note: When using the Create and announce a shipment synchronously or Create a shipment with rules and/or defaults and announce it synchronously endpoints for single-parcel shipments (single collo) announcement, the shipping labels are immediately marked as “Printed” because a label file is instantly returned in the API response.

​
Label formats and sizes

By default, labels are returned as PDF in the original carrier label size, which for most carriers is A6. You can change both the file format and, when retrieving documents, the paper size. Supported formats:
  • PDF (default for all carriers).
  • ZPL (native or converted, see below).
  • PNG (converted from PDF).
Supported paper sizes when retrieving labels:
  • A4
  • A5
  • A6 (original label size for most carriers)

​
Change label size

To change the size of a label, set the paper_size parameter (for example paper_size=A4) on the Retrieve a parcel document or Retrieve multiple parcel documents endpoints. It is not possible to set the label size during shipment creation; label size is only adjustable at retrieval time.

​
ZPL labels

Sendcloud supports two ways of generating ZPL labels:
  • Native carrier ZPL: For carriers that support native ZPL, you can request a native ZPL label by setting "label_details.mime_type": "application/zpl" during shipment creation. When you request a native ZPL label from a carrier, the resulting label format is fixed. Later calls to Retrieve a parcel document or Retrieve multiple parcel documents endpoints for that label will always return ZPL and cannot be converted to another file type.
  • Converted ZPL from PDF: For carriers that do not support native ZPL, Sendcloud converts PDF labels to ZPL using a carrier-approved internal conversion process. You can obtain a converted ZPL label either by setting "label_details.mime_type": "application/zpl" on shipment creation for carriers that do not support native ZPL labels or by setting the Accept header to application/zpl when calling the Retrieve a parcel document endpoint. Most carriers use a resolution of 203 DPI for ZPL labels. Make sure your Zebra or other thermal printer is configured to print at the same DPI as the label to avoid scaling and readability issues.

​
PNG labels

PNG labels are always generated by converting a PDF label to a PNG image inside Sendcloud. You can obtain PNG labels in two ways:
  • Set "label_details.mime_type": "image/png" during shipment creation.
  • Set the Accept header to image/png when calling the Retrieve a parcel document endpoint.
For PNG labels you can control the image resolution with the dpi parameter, typically set to 150 or 300 DPI, depending on your printer capabilities and desired quality. Congrats! You’ve just created your first shipment and downloaded the shipping label via the API.