Label Formats & Sizes

ShipStation API supports labels in three formats: pdf, png, and zpl.

By default, all ShipStation API labels are 4 inches x 6 inches (correlates to 100mm x 150mm for our metric users). You can optionally specify label_layout: "letter" to print 4x6 labels on US Letter size (8.5 inches x 11 inches) sheets when you create a label using the PDF or PNG formats. The letter layout will accommodate two 4x6 labels on a single sheet.

Label format and size reference:

Label Format	Default Size	Description
`pdf`	4" x 6"	Adobe PDF format. Also supports printing the 4" x 6" label to an 8.5" x 11" (US Letter) sheet.
`png`	4" x 6"	A PNG (portable network graphics) image file. Also supports printing the 4" x 6" label to an 8.5" x 11" (US Letter) sheet.
`zpl`	4" x 6"	Zebra Programming Language (ZPL) format, which is useful for printing with a Zebra Printer. ZPL does not support printing to 8.5" x 11" sheets.

Label Download Options

When you purchase a label, the create label response will return label URLs in the label_download object so you can download the labels in each of the available formats, unless you specify which label format you want in the request body (which you can do when choosing the inline label download type).

The inline label download type will instead provide a single Base64 encoded label of the format specified in your request body. See our Downloading a Label page to learn more about label download options.

Example Label Request & Response

The following example demonstrates setting the label_layout property to indicate a 4x6 label should be returned in the response.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
POST /v1/labels HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
Content-Length: 1054
{
  "label_layout": "4x6",
  "shipment": {
    "service_code": "usps_priority_mail",
    "ship_to": {
      "name": "Amanda Miller",
      "phone": "555-555-5555",
      "email": "[email protected]",
      "address_line1": "525 S Winchester Blvd",
      "city_locality": "San Jose",
      "state_province": "CA",
      "postal_code": "95128",
      "country_code": "US",
      "address_residential_indicator": "yes"
    },
    "ship_from": {
      "company_name": "Example Corp.",
      "name": "John Doe",
      "phone": "111-111-1111",
      "email": "[email protected]",
      "address_line1": "4009 Marathon Blvd",
      "address_line2": "Suite 300",
      "city_locality": "Austin",
      "state_province": "TX",
      "postal_code": "78756",
      "country_code": "US",
      "address_residential_indicator": "no"
    },
    "confirmation": "none",
    "insurance_provider": "none",
    "packages": [
      {
        "weight": {
          "value": 1.0,
          "unit": "ounce"
        }
      }
    ]
  }
}

Response

Notice that the label_download object in the response includes links to download the label as pdf, png, and zpl. There is also an href field, which exists for backward compatibility purposes. We recommend that you use the other fields instead.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
  "label_id": "se-test-41817394",
  "status": "processing",
  "shipment_id": "se-41817394",
  "ship_date": "2017-04-03T00:00:00Z",
  "created_at": "2017-04-03T17:30:19.9541821Z",
  "shipment_cost": {
    "currency": "usd",
    "amount": 0.0
  },
  "insurance_cost": {
    "currency": "usd",
    "amount": 0.0
  },
  "tracking_number": "9999999999999",
  "is_return_label": false,
  "is_international": false,
  "batch_id": "",
  "carrier_id": "se-0",
  "service_code": "usps_priority_mail",
  "package_code": "package",
  "voided": false,
  "voided_at": null,
  "label_format": "pdf",
  "label_layout": "4x6",
  "trackable": true,
  "carrier_code": "stamps_com",
  "tracking_status": "unknown",
  "label_download": {
    "pdf": "https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.pdf",
    "png": "https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.png",
    "zpl": "https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.zpl",
    "href": "https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.pdf"
  },
  "form_download": null,
  "insurance_claim": {
    "href": "https://www.dsiins.com/extclaims/Default.asp?cid=shipengine&psid=0&shipmentid=0"
  }
}