Site Logo

Custom Label Messages

Label messages can serve more than their primary use for reference numbers or internal tracking messages. You can add separate, customized label messages to each package in a shipment, too! You can use these label messages for product names, SKUs, PO numbers, and other info you want displayed on the label.

ShipEngine allows you to add up to three custom label messages denoted by keys reference1, reference2, and reference3 (with supporting carriers).

Stamps.com (USPS)

The Label Messages for Stamps.com USPS labels will display at the bottom of the label, beneath the barcode section.

An example label message appears in the region boxed in red in the image below.

Stamps Custom Label

Example JSON Request

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
POST /v1/labels HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
"shipment": {
"service_code": "usps_priority_mail",
"ship_to": {
"name": "Amanda Miller",
"phone": "555-555-5555",
"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": {
"company_name": "Example Corp.",
"name": "John Doe",
"phone": "111-111-1111",
"address_line1": "4009 Marathon Blvd",
"address_line2": "Suite 300",
"city_locality": "Austin",
"state_province": "TX",
"postal_code": "78756",
"country_code": "US",
"address_residential_indicator": "no"
},
"packages": [
{
"weight": {
"value": 1,
"unit": "ounce"
},
"label_messages": {
"reference1": "customer reference number 1",
"reference2": "invoice number 1",
"reference3": "purchase order number 1"
}
}
]
}
}

Example JSON 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
49
50
51
52
53
54
55
56
57
58
59
60
61
62
{
"label_id": "se-test-176518042",
"status": "processing",
"shipment_id": "se-176518042",
"ship_date": "2017-12-04T00:00:00Z",
"created_at": "2017-12-04T17:46:36.9243135Z",
"shipment_cost": {
"currency": "usd",
"amount": 0
},
"insurance_cost": {
"currency": "usd",
"amount": 0
},
"tracking_number": "9999999999999",
"is_return_label": false,
"is_international": false,
"batch_id": "",
"carrier_id": "se-143975",
"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": null,
"packages": [
{
"package_code": "package",
"weight": {
"value": 1,
"unit": "ounce"
},
"dimensions": {
"unit": "inch",
"length": 0,
"width": 0,
"height": 0
},
"insured_value": {
"currency": "usd",
"amount": 0
},
"tracking_number": null,
"label_messages": {
"reference1": "customer reference number 1",
"reference2": "invoice number 1",
"reference3": "purchase order number 1"
}
}
]
}

FedEx

FedEx custom label messages have the following mappings:

KeyFedEx Label FieldExampleCharacter Limit
reference 1Customer ReferenceREF: reference135
reference 2Invoice NumberINV: reference230
reference 3Purchase Order NumberPO: reference330

Example label messages appear in the regions boxed in red in the image below.

Fedex Custom Label

Example JSON Request

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
POST /v1/labels HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
"shipment": {
"service_code": "fedex_ground",
"ship_to": {
"name": "Amanda Miller",
"phone": "555-555-5555",
"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": {
"company_name": "Example Corp.",
"name": "John Doe",
"phone": "111-111-1111",
"address_line1": "4009 Marathon Blvd",
"address_line2": "Suite 300",
"city_locality": "Austin",
"state_province": "TX",
"postal_code": "78756",
"country_code": "US",
"address_residential_indicator": "no"
},
"packages": [
{
"weight": {
"value": 1,
"unit": "ounce"
},
"label_messages": {
"reference1": "customer reference number 1",
"reference2": "invoice number 1",
"reference3": "purchase order number 1"
}
},
{
"weight": {
"value": 1,
"unit": "ounce"
},
"label_messages": {
"reference1": "customer reference number 2",
"reference2": "invoice number 2",
"reference3": "purchase order number 2"
}
}
]
}
}

Example JSON 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
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
82
83
84
85
{
"label_id": "se-1095",
"status": "completed",
"shipment_id": "se-1001759",
"ship_date": "2019-07-25T05:00:00.000Z",
"created_at": "2019-07-25T15:24:46.657Z",
"shipment_cost": {
"currency": "usd",
"amount": 18.3
},
"insurance_cost": {
"currency": "usd",
"amount": 0
},
"tracking_number": "794630698100",
"is_return_label": false,
"is_international": false,
"batch_id": "",
"carrier_id": "$fedExId$",
"service_code": "fedex_ground",
"package_code": "package",
"voided": false,
"voided_at": null,
"label_format": "pdf",
"label_layout": "4x6",
"trackable": true,
"carrier_code": "fedex",
"tracking_status": "in_transit",
"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": null,
"packages": [
{
"package_code": "package",
"weight": {
"value": 1,
"unit": "ounce"
},
"dimensions": {
"unit": "inch",
"length": 0,
"width": 0,
"height": 0
},
"insured_value": {
"currency": "usd",
"amount": 0
},
"tracking_number": "794630698100",
"label_messages": {
"reference1": "customer reference number 1",
"reference2": "invoice number 1",
"reference3": "purchase order number 1"
}
},
{
"package_code": "package",
"weight": {
"value": 1,
"unit": "ounce"
},
"dimensions": {
"unit": "inch",
"length": 0,
"width": 0,
"height": 0
},
"insured_value": {
"currency": "usd",
"amount": 0
},
"tracking_number": "794630698177",
"label_messages": {
"reference1": "customer reference number 2",
"reference2": "invoice number 2",
"reference3": "purchase order number 2"
}
}
]
}

UPS

UPS custom label messages have the following mappings:

KeyUPS Label FieldExampleCharacter Limit
reference 1Customer ReferenceREF: reference135
reference 2Invoice NumberINV: reference235

Example label messages appear in the region boxed in red in the image below.

UPS Custom Label

Example JSON Request

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
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": "Amanda Miller",
"phone": "555-555-5555",
"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": {
"company_name": "Example Corp.",
"name": "John Doe",
"phone": "111-111-1111",
"address_line1": "4009 Marathon Blvd",
"address_line2": "Suite 300",
"city_locality": "Austin",
"state_province": "TX",
"postal_code": "78756",
"country_code": "US",
"address_residential_indicator": "no"
},
"packages": [
{
"weight": {
"value": 1,
"unit": "ounce"
},
"label_messages": {
"reference1": "first reference",
"reference2": "second reference"
}
},
{
"weight": {
"value": 1,
"unit": "ounce"
},
"label_messages": {
"reference1": "first reference",
"reference2": "second reference"
}
}
]
}
}

Example JSON 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
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
82
83
84
85
{
"label_id": "se-1097",
"status": "completed",
"shipment_id": "se-1001762",
"ship_date": "2019-07-25T05:00:00.000Z",
"created_at": "2019-07-25T15:24:46.657Z",
"shipment_cost": {
"currency": "usd",
"amount": 18.82
},
"insurance_cost": {
"currency": "usd",
"amount": 0
},
"tracking_number": "1Z28A1R90321487219",
"is_return_label": false,
"is_international": false,
"batch_id": "",
"carrier_id": "se-123890",
"service_code": "ups_ground",
"package_code": "package",
"voided": false,
"voided_at": null,
"label_format": "pdf",
"label_layout": "4x6",
"trackable": true,
"carrier_code": "ups",
"tracking_status": "in_transit",
"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": null,
"packages": [
{
"package_code": "package",
"weight": {
"value": 1,
"unit": "ounce"
},
"dimensions": {
"unit": "inch",
"length": 0,
"width": 0,
"height": 0
},
"insured_value": {
"currency": "usd",
"amount": 0
},
"tracking_number": "1Z28A1R90321487219",
"label_messages": {
"reference1": "first reference",
"reference2": "second reference",
"reference3": null
}
},
{
"package_code": "package",
"weight": {
"value": 1,
"unit": "ounce"
},
"dimensions": {
"unit": "inch",
"length": 0,
"width": 0,
"height": 0
},
"insured_value": {
"currency": "usd",
"amount": 0
},
"tracking_number": "1Z28A1R90331302827",
"label_messages": {
"reference1": "first reference",
"reference2": "second reference",
"reference3": null
}
}
]
}

OnTrac

The Label Messages for OnTrac Shipping Labels will appear on the right side of the label, beneath the barcode, and just above the shipping codes.

Example label messages appear in the region boxed in red in the image below.

OnTrac Custom Label

Example JSON Request

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
POST /v1/labels HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
"shipment": {
"service_code": "sunrise_service",
"ship_from": {
"company_name": "Example Corp.",
"name": "John Doe",
"phone": "111-111-1111",
"address_line1": "4009 Marathon Blvd",
"address_line2": "Suite 300",
"city_locality": "Austin",
"state_province": "TX",
"postal_code": "78756",
"country_code": "US",
"address_residential_indicator": "no"
},
"ship_to": {
"name": "Return of ShipEngine",
"company_name": null,
"phone": "512-485-4567",
"address_line1": "10591 N De Anza Blvd",
"address_line2": null,
"address_line3": null,
"city_locality": "Cupertino",
"state_province": "CA",
"postal_code": "95014",
"country_code": "US"
},
"confirmation": "None",
"packages": [
{
"package_code": "package",
"weight": {
"value": 1,
"unit": "ounce"
},
"label_messages": {
"reference1": "Always be closing",
"reference2": "Winter is here"
}
}
]
},
"label_layout": "letter"
}

Example JSON 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
49
50
51
52
53
54
55
56
57
58
59
60
61
62
{
"label_id": "se-80286067",
"status": "completed",
"shipment_id": "se-184301297",
"ship_date": "2017-12-19T00:00:00Z",
"created_at": "2017-12-19T20:12:52.527Z",
"shipment_cost": {
"currency": "usd",
"amount": 25.58
},
"insurance_cost": {
"currency": "usd",
"amount": 0
},
"tracking_number": "D10011210951580",
"is_return_label": false,
"is_international": false,
"batch_id": "",
"carrier_id": "se-186282",
"service_code": "sunrise_service",
"package_code": "package",
"voided": false,
"voided_at": null,
"label_format": "pdf",
"label_layout": "letter",
"trackable": false,
"carrier_code": "ontrac",
"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": null,
"packages": [
{
"package_code": "package",
"weight": {
"value": 1,
"unit": "ounce"
},
"dimensions": {
"unit": "inch",
"length": 0,
"width": 0,
"height": 0
},
"insured_value": {
"currency": "usd",
"amount": 0
},
"tracking_number": null,
"label_messages": {
"reference1": "Always be closing",
"reference2": "Winter is here",
"reference3": null
}
}
]
}

DHL Express

DHL Express custom label messages have the following mappings:

KeyUPS Label FieldExampleCharacter Limit
reference 1Customer ReferenceREF: reference135

Example label messages appear in the region boxed in red in the image below.

DHL Express Custom Label

Example JSON Request

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
POST /v1/labels HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
"shipment": {
"confirmation": "none",
"insurance_provider": "none",
"service_code": "express_worldwide",
"carrier_id": "se-105304",
"ship_to": {
"name": "ShipStation AU",
"phone": "512-555-5555",
"company_name": "ShipStation AU",
"address_line1": "600 George St",
"city_locality": "Sydney",
"state_province": "NSW",
"postal_code": "2000",
"country_code": "AU"
},
"warehouse_id": "se-107273",
"customs": {
"contents": "documents",
"customs_items": [
{
"description": "letter",
"quantity": 1,
"value": 1,
"harmonized_tariff_code": "4817.20",
"country_of_origin": "US"
}
],
"non_delivery": "treat_as_abandoned"
},
"packages": [
{
"label_messages": {
"reference1": "Reference kq23YH2"
},
"package_code": "package",
"weight": {
"value": 2,
"unit": "pound"
},
"dimensions": {
"unit": "inch",
"length": 0,
"width": 0,
"height": 0
}
}
]
}
}

Example JSON 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
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
{
"label_id": "se-1051719",
"status": "completed",
"shipment_id": "se-6478097",
"ship_date": "2020-11-11T00:00:00Z",
"created_at": "2020-11-11T21:36:19.9939671Z",
"shipment_cost": {
"currency": "usd",
"amount": 142.35
},
"insurance_cost": {
"currency": "usd",
"amount": 0
},
"tracking_number": "3734944032",
"is_return_label": false,
"rma_number": null,
"is_international": true,
"batch_id": "",
"carrier_id": "se-105304",
"service_code": "express_worldwide",
"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": "dhl_express",
"tracking_status": "in_transit",
"label_download": {
"pdf": "https://api.shipengine.com/v1/downloads/0/aVfUNYNxqEmGLYSWQBfkDw/label-1051719.pdf",
"png": "https://api.shipengine.com/v1/downloads/0/aVfUNYNxqEmGLYSWQBfkDw/label-1051719.png",
"zpl": "https://api.shipengine.com/v1/downloads/0/aVfUNYNxqEmGLYSWQBfkDw/label-1051719.zpl",
"href": "https://api.shipengine.com/v1/downloads/0/aVfUNYNxqEmGLYSWQBfkDw/label-1051719.pdf"
},
"form_download": {
"href": "https://api.shipengine.com/v1/downloads/0/1ghTF5EaxkyrawJXoee_Kw/form-1051719.pdf"
},
"insurance_claim": null,
"packages": [
{
"package_code": "package",
"weight": {
"value": 2,
"unit": "pound"
},
"dimensions": {
"unit": "inch",
"length": 0,
"width": 0,
"height": 0
},
"insured_value": {
"currency": "usd",
"amount": 0
},
"tracking_number": "3734944032",
"label_messages": {
"reference1": "Reference kq23YH2",
"reference2": null,
"reference3": null
},
"external_package_id": null
}
],
"charge_event": "carrier_default"
}

Download Your Label!

That's it! Your label is available for download using the label_download.href URL provided in the response. You should see your label messages on the labels in their respective places for each carrier.

1
curl -O https://api.shipengine.com/v1/downloads/YTQAAdchJkCIcWNwFUErtA/label-1097.pdf -X GET