Site Logo

Custom Label Messages

You can include additional information on your labels by leveraging the carriers label reference fields with your own custom label messages. Carriers often use these fields for reference numbers or internal tracking messages. If your carrier supports it, you can add your own separate, customized label messages to each package in a shipment, too!

You can use these label messages for things like 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.

Requirements

  • Add the label_messages object to the packages object for a shipment. The label_messages object can include the following three properties: reference1, reference2, and reference3. The default value for each property is null.
  • You must use a carrier that supports labels messages. Not all carriers and services support label messages and some carriers support some but not all three label message fields. Check the carrier guide for your specific carrier if you are unsure of the carrier's support for label messages.
  • Carriers that do support label messages may have additional requirements, like maximum character counts.

Examples with Supported Carriers

Carriers that support label messages include (but are not limited to) USPS, FedEx, UPS, OnTrac, and DHL Express. We've incldued example requests below to demonstrate adding the label_messages object to your shipments.

USPS Request & Response

USPS allows up to 60 characters per label message.

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"
}
}
]
}
}

Stamps.com 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"
}
}
]
}

The label messages for USPS labels will display at the bottom of the label, beneath the barcode section.

Stamps Custom Label

FedEx Request & Response

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
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"
}
}
]
}
}

FedEx 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"
}
}
]
}

The label messages are marked in the example label below.

Fedex Custom Label

UPS Request & Response

UPS custom label messages have the following mappings:

KeyUPS Label FieldExampleCharacter Limit
reference 1Customer ReferenceREF: reference135
reference 2Invoice NumberINV: reference235
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"
}
}
]
}
}

UPS 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
}
}
]
}

The label messages are marked in the example label below.

UPS Custom Label

OnTrac Request & Response

OnTrac labels will only display messages in the reference 1 and reference 2 fields. Reference 3 can be submitted, but will be ignored by the carrier. Any messages longer than 25 characters may appear to be cut off by the label margins.

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"
}

OnTrac 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
}
}
]
}

The label messages for OnTrac labels will appear on the right side of the label, beneath the barcode and just above the shipping codes.

OnTrac Custom Label

DHL Express Request & Response

DHL Express custom label messages have the following mappings:

KeyUPS Label FieldExampleCharacter Limit
reference 1Customer ReferenceREF: reference135
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
}
}
]
}
}

DHL Express 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"
}

The label message for DHL Express will appear above the waybill barcode.

DHL Express Custom Label