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": {
    "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!

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

That's it, your label is available for download using the label_download.href URL provided in the response. We currently retain labels created within the ShipEngine platform 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.

Rumor has it, you can actually send mail to Mickey and Minnie Mouse at the address in Burbank, CA and receive a reply.


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