shipengine-logo

Create a Shipping Label

ShipEngine is a REST API that allows you to manage almost every facet possible for shipping. This tutorial will show you how to create a label.

Before you begin:

Creating a shipping label requires the following steps:

  1. Prepare Your Request
  2. Send the Request
  3. Download the Label

In the example below, you'll request a label using the UPS account that's included with your ShipEngine account. The general steps are the same. regardless of which carrier you use.

Step 1: Prepare Your Request

API Endpoint

To create a label, you'll need to send an HTTP POST request to https://api.shipengine.com/v1/labels. From now on we'll refer to this as the /v1/labels API endpoint to keep things short.

Headers

There are two HTTP headers that you need to set in your request:

HTTP HeaderDesription
Content-TypeThe Content-Type header specifies the media type of your API request.

ShipEngine requires all requests to be in JSON format, so this header should always be set to application/json. | API-Key | For this header you'll need to pass your ShipEngine API key. This is how ShipEngine knows who you are. If you don't have an API key yet, then read our Getting Started guide to learn how to create one.

Request Body

The body of your HTTP request is where you'll specify all the information about the shipping label that you want to create,such as the "from" and "to" addresses, the package weight and dimensions, etc.

For this tutorial, we'll create a label with the following criteria:

FieldValue
Delivery ServiceUPS Ground
Ship from addressJohn Doe
4009 Marathon Blvd
Austin, TX 78756
555-555-5555
Ship to addressJane Doe
525 S Winchester Blvd
San Jose, CA 95128
Package weight20 ounces
Package dimensions12 x 24 x 6 inches

As we mentioned above, ShipEngine requires all requests to be in JSON format. Here's what our label request body will look like. Notice that it contains all of the information listed above:

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
{
  "shipment": {
    "service_code": "ups_ground",
    "ship_to": {
      "name": "Jane Doe",
      "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": {
      "name": "John Doe",
      "company_name": "Example Corp",
      "phone": "555-555-5555",
      "address_line1": "4009 Marathon Blvd",
      "city_locality": "Austin",
      "state_province": "TX",
      "postal_code": "78756",
      "country_code": "US",
      "address_residential_indicator": "no"
    },
    "packages": [
      {
        "weight": {
          "value": 20,
          "unit": "ounce"
        },
        "dimensions": {
          "height": 6,
          "width": 12,
          "length": 24,
          "unit": "inch"
        }
      }
    ]
  }
}

Step 2: Sending the Request

Now we'll take everything we talked about in Step 1 and put it all together using curl. Notice the example below uses everything we talked about in Step 1:

  • Makes a POST call to https://api.shipengine.com/v1/labels
  • Sets the content type header to application/json
  • Sets the API Key to your ShipEngine API Key
  • Uses the Request Body of the sample json code from above

Paste the following curl example into your Terminal (if you are not familiar with using curl, please review our page on how to use curl):

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
POST /v1/labels HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "shipment": {
    "service_code": "ups_ground",
    "ship_to": {
      "name": "Jane Doe",
      "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": {
      "name": "John Doe",
      "company_name": "Example Corp",
      "phone": "555-555-5555",
      "address_line1": "4009 Marathon Blvd",
      "city_locality": "Austin",
      "state_province": "TX",
      "postal_code": "78756",
      "country_code": "US",
      "address_residential_indicator": "no"
    },
    "packages": [
      {
        "weight": {
          "value": 20,
          "unit": "ounce"
        },
        "dimensions": {
          "height": 6,
          "width": 12,
          "length": 24,
          "unit": "inch"
        }
      }
    ]
  }
}

If your request was successful, you'll receive an HTTP 200 response that looks similar to this:

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
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
{
  "label_id": "se-7764944",
  "status": "completed",
  "shipment_id": "se-21748537",
  "ship_date": "2020-04-17T00:00:00Z",
  "created_at": "2020-04-17T16:22:20.9879673Z",
  "shipment_cost": {
    "currency": "usd",
    "amount": 10.1900
  },
  "insurance_cost": {
    "currency": "usd",
    "amount": 0.0
  },
  "charge_event": "carrier_default",
  "tracking_number": "9405511899564088683810",
  "is_return_label": false,
  "rma_number": null,
  "is_international": false,
  "batch_id": "",
  "carrier_id": "se-169349",
  "service_code": "usps_priority_mail",
  "package_code": "package",
  "voided": false,
  "voided_at": null,
  "label_format": "pdf",
  "label_layout": "4x6",
  "trackable": true,
  "label_image_id": null,
  "carrier_code": "stamps_com",
  "tracking_status": "in_transit",
  "label_download": {
    "pdf": "https://api.shipengine.com/v1/downloads/10/XNGDhq7uZ0CAEt5LOnCxIg/label-7764944.pdf",
    "png": "https://api.shipengine.com/v1/downloads/10/XNGDhq7uZ0CAEt5LOnCxIg/label-7764944.png",
    "zpl": "https://api.shipengine.com/v1/downloads/10/XNGDhq7uZ0CAEt5LOnCxIg/label-7764944.zpl",
    "href": "https://api.shipengine.com/v1/downloads/10/XNGDhq7uZ0CAEt5LOnCxIg/label-7764944.pdf"
  },
  "form_download": null,
  "insurance_claim": null,
  "packages": [
    {
      "package_code": "package",
      "weight": {
        "value": 20.00,
        "unit": "ounce"
      },
      "dimensions": {
        "unit": "inch",
        "length": 0.0,
        "width": 0.0,
        "height": 0.0
      },
      "insured_value": {
        "currency": "usd",
        "amount": 0.00
      },
      "tracking_number": "9405511899564088683810",
      "label_messages": {
        "reference1": null,
        "reference2": null,
        "reference3": null
      },
      "external_package_id": null
    }
  ]
}

Notice that this response includes the following:

  • Status: completed
  • Label cost
  • A link to download the label
  • Service type
  • Package type
  • Label size, and
  • Tracking number

Step 3: Download the Label

At the end of Step 2, you received an HTTP response that included the label details. Among those details are some URLs to download the label in various formats:

1
2
3
4
5
6
7
8
{
  "label_download": {
    "pdf": "https://api.shipengine.com/v1/downloads/10/XNGDhq7uZ0CAEt5LOnCxIg/label-7764944.pdf",
    "png": "https://api.shipengine.com/v1/downloads/10/XNGDhq7uZ0CAEt5LOnCxIg/label-7764944.png",
    "zpl": "https://api.shipengine.com/v1/downloads/10/XNGDhq7uZ0CAEt5LOnCxIg/label-7764944.zpl",
    "href": "https://api.shipengine.com/v1/downloads/10/XNGDhq7uZ0CAEt5LOnCxIg/label-7764944.pdf"
  }
}

The label download formats include:

FormatDescriptionUses
pdfAdobe PDF fileA common format that's supported by most printers. Also a good format for email attachments when sending shipping labels to customers.
pngPNG image filePNG images are great for embedding in emails, web pages, or mobile apps.
zplZebra Printer fileIf you print labels using a Zebra Printer, then ZPL is probably the best file format to use.

These URLs are just like any other URLs, in that you can paste them into a browser to download the file. You can also download the label using curl.

Copy the curl request below and replace the __YOUR_LABEL_URL_HERE__ placeholder with the URL of the label format you wish to download:

1
curl -iOX GET __YOUR_LABEL_URL_HERE__

Congratulations! You've now downloaded a label!

Advanced Options

Review the options below for ways to improve your label flow.

Ship Engine has three other ways to download labels

  1. Use a Rate to Download a Label
  2. Use a Shipment to Download a Label
  3. Bulk Label Downloading

Request and Download In One Call

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.

Create Return Label with Outgoing Label

You can create return labels by setting is_return_label to true. See our Return Shipping Labels page for more details.

Create Branded Labels

Learn how to customize your labels to print with your brand's logo or other images and see which carriers support this feature in our Create Custom Shipping Labels article.

Add Messages to the Labels

Show your customers an additional level of care and detail by adding a personal or customized message. Custom Label Messages article.