Label Formats and Sizes

ShipEngine provides labels in three formats:

Label Format Description
pdf Adobe PDF Format
png A PNG (portable network graphics) image file
zpl Zebra Programming Language format, which is useful for printing with a Zebra Printer

By default, all labels are 4x6 (4 inches x 6 inches). You can optionally specify label_layout: "letter" to create labels in US Letter size (8.5 inches x 11 inches).

Example

The following example demonstrates setting the label_layout when creating a label.

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

Info

Want to make fewer requests?

In this example, two API requests were necessary: one to create the label, and another to download the file. You can accomplish both steps in a single request by setting label_download_type: "inline". See Download a Label for more details.

Example Request

curl -iX POST https://api.shipengine.com/v1/labels \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '
{
  "label_format": "png",
  "label_layout": "4x6",
  "test_label": true,
  "shipment": {
    "service_code": "usps_priority_mail",
    "ship_to": {
      "name": "Mickey and Minnie Mouse",
      "phone": "714-781-4565",
      "company_name": "The Walt Disney Company",
      "address_line1": "500 South Buena Vista Street",
      "city_locality": "Burbank",
      "state_province": "CA",
      "postal_code": "91521",
      "country_code": "US"
    },
    "ship_from": {
      "name": "Dade Murphy",
      "phone": "512-485-4282",
      "company_name": "Zero Cool",
      "address_line1": "345 Chambers Street",
      "address_line2": "Suite 100",
      "city_locality": "New York City",
      "state_province": "NY",
      "postal_code": "10282",
      "country_code": "US",
    },
    "confirmation": "none",
    "insurance_provider": "none",
    "packages": [
      {
        "weight": {
          "value": 1.0,
          "unit": "ounce"
        }
      }
    ]
  }
}'
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": "Mickey and Minnie Mouse",
      "phone": "714-781-4565",
      "company_name": "The Walt Disney Company",
      "address_line1": "500 South Buena Vista Street",
      "city_locality": "Burbank",
      "state_province": "CA",
      "postal_code": "91521",
      "country_code": "US"
    },
    "ship_from": {
      "name": "Dade Murphy",
      "phone": "512-485-4282",
      "company_name": "Zero Cool",
      "address_line1": "345 Chambers Street",
      "address_line2": "Suite 100",
      "city_locality": "New York City",
      "state_province": "NY",
      "postal_code": "10282",
      "country_code": "US",
    },
    "confirmation": "none",
    "insurance_provider": "none",
    "packages": [
      {
        "weight": {
          "value": 1.0,
          "unit": "ounce"
        }
      }
    ]
  }
}

Example Response

{
  "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"
  }
}