Create a Label

Learn how to create a shipping label in a single call to ShipEngine®.

ShipEngine allows users to manage almost every facet possible for shipping; however, in this example, we'll show you how easy it is to generate a label.

At a minimum, you need four pieces of information to create a shipping label.

  1. A carrier service code (e.g. usps_priority_mail).
  2. Any address that you're shipping from (e.g. our offices at ShipEngine).
  3. Any address that you're shipping to (e.g. Mickey Mouse).
  4. The weight of the package you're sending (e.g. 1oz).

Step 1: Get Your Request Ready

For our example, we're going to request a label using USPS with the builtin Stamps.com provider that's included in your account (for free).

Test Labels

Test labels are only temporary resources and will not be persisted. Therefore, you cannot use ShipEngine to retrieve an old test label.

Note: Not all carriers support test labels. We will return an error message if you try to generate a test label for a carrier that does not support it

USPS Test Mode

Generating USPS labels is like printing cash and generated labels are billed immediately. It's important to include "test_label": true in your request if you don't plan to use the label for shipping.

Above we listed four items that are required to get a package. We've designed ShipEngine to reuse as many objects as possible, some of these are nested inside other objects.

/v1/labels

Open up a terminal window and use cURL and get a label to send a small package to Mickey and Minnie Mouse.

curl $apiUrl$/v1/labels -X POST \
  -H "Content-type: application/json" \
  -H $apiAuth$ \
  -d ' 
{
  "shipment": {
    "service_code": "usps_priority_mail",
    "ship_to": {
      "name": "Mickey and Minnie Mouse",
      "phone": "+1 (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",
      "address_residential_indicator": "No"
    },
    "ship_from": {
      "name": "Shippy",
      "phone": "512-485-4282",
      "company_name": "ShipEngine",
      "address_line1": "3800 N. Lamar Blvd.",
      "address_line2": "Suite 220",
      "city_locality": "Austin",
      "state_province": "TX",
      "postal_code": "78756",
      "country_code": "US",
      "address_residential_indicator": "No"
    },
    "packages": [
      {
        "weight": {
          "value": 1.0,
          "unit": "ounce"
        }
      }
    ]
  },
  "test_label": true,
  "is_return_label": false
}' 

You'll be greeted with a JSON payload with all sorts of data about your label, including the cost, tracking number, and a link to download the label.

Need a return label?

Return labels can be easily created by setting is_return_label to true. See this page for more details.

{
  "label_id": "se-202887313",
  "status": "completed",
  "shipment_id": "se-202887313",
  "ship_date": "$shipDate$",
  "created_at": "$date$",
  "shipment_cost": {
    "currency": "USD",
    "amount": 6.86
  },
  "insurance_cost": {
    "currency": "USD",
    "amount": 0.0
  },
  "tracking_number": "9405511899560441854156",
  "is_return_label": false,
  "is_international": false,
  "batch_id": "",
  "carrier_id": "$stampsId$",
  "service_code": "usps_priority_mail",
  "package_code": "package",
  "voided": false,
  "label_format": "pdf",
  "label_layout": "4x6",
  "trackable": false,
  "carrier_code": "stamps_com",
  "tracking_status": "unknown",
  "label_download": {
    "pdf": "$apiUrl$/v1/downloads/aFbxNUVCZ0SDHHp-BmcKjA/testlabel-202887313.pdf",
    "png": "$apiUrl$/v1/downloads/aFbxNUVCZ0SDHHp-BmcKjA/testlabel-202887313.png",
    "zpl": "$apiUrl$/v1/downloads/aFbxNUVCZ0SDHHp-BmcKjA/testlabel-202887313.zpl",
    "href": "$apiUrl$/v1/downloads/aFbxNUVCZ0SDHHp-BmcKjA/testlabel-202887313.pdf"
  },
  "form_download": null,
  "insurance_claim": null,
  "packages": [
    {
      "package_code": "package",
      "weight": {
        "value": 1.00,
        "unit": "ounce"
      },
      "dimensions": {
        "unit": "inch",
        "length": 0.0,
        "width": 0.0,
        "height": 0.0
      },
      "insured_value": {
        "currency": "usd",
        "amount": 0.00
      },
      "tracking_number": null,
      "label_messages": {
        "reference1": null,
        "reference2": null,
        "reference3": null
      }
    }
  ]
}

Step 2: Download it!

The label_download object in the response contains URLs to download the label in various formats. See Label Formats & Sizes for more details. For now, we'll just download the label in PDF format, like this:

curl -O $apiUrl$/v1/downloads/aFbxNUVCZ0SDHHp-BmcKjA/testlabel-202887313.pdf -X GET

Label Retention Period

Labels are available to download for 90 days. So no rush if your intended use of the API requires that labels be downloaded a couple days after the origination date.

Want to make fewer requests?

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


What's Next

You've learned how easy it is to generate a shipping label with very little information, and using a default carrier account in your account.

Size & Weight
Use a Carrier Service
Ship Date
Track Using a Label ID

Create a Label


Learn how to create a shipping label in a single call to ShipEngine®.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.