Downloading a Label
You have two options for downloading labels you've created with ShipStation API:
- Download via URL: Make an HTTP request to download the label in your desired file type from the URLs provided in the
label_downloadobject from the create label response. - Inline labels: If you only intend to download the label in a single format and you know ahead of time which format that is, you can optimize your workflow by eliminating the extra HTTP request to download the label. Instead, you can use the
label_format,label_layout, andlabel_download_typefields to include the full label in the API response.
Option 1: Download via URL
By default, ShipStation API provides URLs to download labels in multiple formats. The URLs will remain valid for 90 days. If your workflow requires the ability to access these URLs after 90 days, we recommend storing the label images locally.
Public URLs
ShipStation API generates a unique authentication token for each label so it can be securely shared and downloaded by your users without exposing your private API key.
You can access the label on the command line using curl:
Label Rotation
You can rotate the label 90, 180, or 270 degrees by appending ?rotation=:value to the URL.
- Supported for ZPL and PDF formats.
- Valid
rotationvalue forzpllabels are0(default) and180. - Valid
rotationvalues forpdflabels are0(default),90,180, and270.
You can view the rotated image in your web browser using this URL or download it on the command line using curl:
Option 2: Inline Label
With this method, you'll use the label_format, label_layout, and label_download_type properties to include the full label in the API response.
About the Inline Label Properties
Label Format:
- PDF: The Adobe PDF format. This is the default if
label_formatis unspecified. - PNG: A PNG (portable network graphics) image file.
- ZPL: Zebra Programming Language format, which is useful for printing with a Zebra Printer.
Label Layout:
- 4x6 : 4 inch by 6 inch label. This is the default if
label_layoutis unspecified. - letter: US Letter size (8.5 inches by 11 inches).
Label Download Type:
url: You will receive URLs to download the label in separate HTTP requests. The URLs will remain valid for 90 days. This is the default iflabel_download_typeis unspecified.inline: You will receive a single, Base64-encoded label as part of the response. No need for a second request to download the label.
Example Inline Request & Response
This example demonstrates how to use label_format, label_layout, and label_download_type to request a 4x6 PNG label to be included in the API response.
Response
The label_download.href field in the response will be a Data URI, which is a special kind of URL that includes the data inline.
The Data URI has four parts: scheme, media type, encoding type, data
| Name | Examples | Description |
|---|---|---|
| Scheme | Always data: | This just identifies the URL as a Data URI as opposed to other schemes like http: or ftp:. |
| Media Type | application/pdf image/png application/zpl | This is the label's MIME Type, which corresponds to the label_format that you specified when creating the label. |
| Encoding Type | Always base64 | ShipStation API always encodes inline labels in Base64 format. |
| Data | A very long Base64 string | This is the actual Base64-encoded label data. Most programming languages include a Base64 decoder as part of their standard library. If your language doesn't, then you may need to use a third-party Base64 decoder. |