Custom Label Messages

Label messages can serve more than their primary use for reference numbers or internal tracking messages. You can add separate, custom label messages to each package in a shipment, too!

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.

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:

Key	FedEx Label Field	Example	Character Limit
reference 1	Customer Reference	REF: reference1	35
reference 2	Invoice Number	INV: reference2	30
reference 3	Purchase Order Number	PO: reference3	30

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

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:

Key	UPS Label Field	Example	Character Limit
reference 1	Customer Reference	REF: reference1	35
reference 2	Invoice Number	INV: reference2	35

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

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.

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:

Key	UPS Label Field	Example	Character Limit
reference 1	Customer Reference	REF: reference1	35

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

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

Address Validation

E-Commerce Platforms

Third Party Logistics

Brands

Getting Started

Developer Guides

Full API Reference

ShipEngine Connect

Postman Collections

Libraries and SDKs

OpenAPI 3.0 Definition

API Status

Intro to ShipEngine

Help Center

Solutions Partners

User Group Meet Up

About Us

Contact

Blog

Case Studies

Custom Label Messages

Stamps.com (USPS)

Example JSON Request

Example JSON Response

FedEx

Example JSON Request

Example JSON Response

UPS

Example JSON Request

Example JSON Response

OnTrac

Example JSON Request

Example JSON Response

DHL Express

Example JSON Request

Example JSON Response

Download Your Label!