Site Logo

Create a Shipping Label

This guide will walk you through how to create your first shipping label in ShipEngine as well as provide the details and context you need to understand how this process works.

Before you begin:

When you create a shipping label in ShipEngine, you'll generally follow these basic steps (described in detail below):

In this tutorial, you'll request a label using the UPS services that are included with your ShipEngine account. However, the general steps are the same no matter which carrier you use.

Step 1: Prepare Your Request

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

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-KeyFor this header you'll need to pass your ShipEngine API key. This is how ShipEngine knows who you are.

Request Body

The body of your request is where you'll specify all the information about the shipping label 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 details:

FieldValue
Delivery ServiceUPS Ground
Ship from addressJohn Doe
4301 Bull Creek Rd
Austin, TX 78731
+1 555-555-5555
Ship to addressJane Doe
525 S Winchester Blvd
San Jose, CA 95128
+1 444-444-4444
Package weight20 ounces
Package dimensions12 x 24 x 6 inches

Here's what our label request body will look like using the above shipment details. There are additional optional fields that are left out of this request, but it does include the minimum fields recommended for shipping a package.

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
{
"shipment": {
"carrier_id": "se-123456",
"service_code": "ups_ground",
"ship_to": {
"name": "Jane Doe",
"phone": "+1 444-444-4444",
"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": "+1 555-555-5555",
"address_line1": "4301 Bull Creek Rd",
"city_locality": "Austin",
"state_province": "TX",
"postal_code": "78731",
"country_code": "US",
"address_residential_indicator": "no"
},
"packages": [
{
"weight": {
"value": 20,
"unit": "ounce"
},
"dimensions": {
"height": 6,
"width": 12,
"length": 24,
"unit": "inch"
}
}
]
}
}

Step 2: Send the Request

Now, we'll take the request body from Step 1 for the POST /v1/labels call and put it all together using curl. When you use POST /v1/labels to create labels with your production API key, you are purchasing the label from the selected carrier. For ShipEngine Carriers, the label cost will be deducated from your account balance. For your own carriers you've connected to ShipEngine, you'll be invoiced according to that carrier's usual method.

Example Request & 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
47
48
POST /v1/labels HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
"shipment": {
"carrier_id": "se-123456",
"service_code": "ups_ground",
"ship_to": {
"name": "Jane Doe",
"phone": "+1 444-444-4444",
"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": {
"name": "John Doe",
"company_name": "Example Corp",
"phone": "+1 555-555-5555",
"email": "[email protected]",
"address_line1": "4301 Bull Creek Rd",
"city_locality": "Austin",
"state_province": "TX",
"postal_code": "78731",
"country_code": "US",
"address_residential_indicator": "no"
},
"packages": [
{
"weight": {
"value": 20,
"unit": "ounce"
},
"dimensions": {
"height": 6,
"width": 12,
"length": 24,
"unit": "inch"
}
}
]
}
}

Response

If your request was successful, you'll receive an HTTP 200 response. The response payload includes all the details you need about the label, including (but not limited to):

  • Status: completed
  • Label and shipment IDs
  • Label cost
  • Link to download the label in different formats (PNG, PDF, ZPL)
  • Service type
  • Package type
  • Label size
  • Tracking number
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
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
{
"label_id": "se-396884371",
"status": "completed",
"shipment_id": "se-1080108982",
"ship_date": "2024-01-03T08:00:00Z",
"created_at": "2024-01-03T17:37:21.6482315Z",
"shipment_cost": {
"currency": "usd",
"amount": 17.58
},
"insurance_cost": {
"currency": "usd",
"amount": 0.0
},
"requested_comparison_amount": null,
"rate_details": [],
"tracking_number": "1ZYF85760394283643",
"is_return_label": false,
"rma_number": null,
"is_international": false,
"batch_id": "",
"carrier_id": "se-123456",
"service_code": "ups_ground",
"package_code": "package",
"voided": false,
"voided_at": null,
"label_format": "pdf",
"display_scheme": "label",
"label_layout": "4x6",
"trackable": true,
"label_image_id": null,
"carrier_code": "ups",
"tracking_status": "in_transit",
"label_download": {
"pdf": "https://api.shipengine.com/v1/downloads/10/N7a1AuQIwk2PjYM2H2KVrA/label-396884371.pdf",
"png": "https://api.shipengine.com/v1/downloads/10/N7a1AuQIwk2PjYM2H2KVrA/label-396884371.png",
"zpl": "https://api.shipengine.com/v1/downloads/10/N7a1AuQIwk2PjYM2H2KVrA/label-396884371.zpl",
"href": "https://api.shipengine.com/v1/downloads/10/N7a1AuQIwk2PjYM2H2KVrA/label-396884371.pdf"
},
"form_download": null,
"qr_code_download": null,
"insurance_claim": null,
"packages": [
{
"package_id": 415397454,
"package_code": "package",
"weight": {
"value": 20.00,
"unit": "ounce"
},
"dimensions": {
"unit": "inch",
"length": 24.00,
"width": 12.00,
"height": 6.00
},
"insured_value": {
"currency": "usd",
"amount": 0.00
},
"tracking_number": "1ZYF85760394283643",
"label_download": {
"pdf": "https://api.shipengine.com/v1/downloads/10/HKNTqQS9yEq7rWuATnCSqQ/labelpackage-415397454.pdf",
"png": "https://api.shipengine.com/v1/downloads/10/HKNTqQS9yEq7rWuATnCSqQ/labelpackage-415397454.png",
"zpl": "https://api.shipengine.com/v1/downloads/10/HKNTqQS9yEq7rWuATnCSqQ/labelpackage-415397454.zpl"
},
"qr_code_download": null,
"label_messages": {
"reference1": null,
"reference2": null,
"reference3": null
},
"external_package_id": null,
"content_description": null,
"sequence": 1,
"alternative_identifiers": []
}
],
"charge_event": "carrier_default",
"alternative_identifiers": []
}

Step 3: Download the Label

In your response, the label_download object includes the URLs you can use 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. However, please note that not all carriers support the ZPL format.

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 downloaded your first label!

Cancel a Label

If you need to cancel a label due to a mistake or because something about the package changed after you created the label, you can do so! Check out our guide on voiding a label to learn more.

What's Next?

There is more than one way to create a label in ShipEngine. Explore the options below for ways to improve your label flow.

Finally, explore the following options to customize or make your workflow more efficient:

  • Request and download in one call: In the example above, two 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 a return label with an 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 so they print with your brand's logo or other images and see which carriers support this feature on the Create Custom Shipping Labels page.
  • Add messages to labels: Show your customers an additional level of care and detail by adding a personal or customized message. See the Custom Label Messages page for details.