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.

ShipStation API 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
46
47
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",
      "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": {
      "company_name": "Example Corp.",
      "name": "John Doe",
      "phone": "111-111-1111",
      "email": "[email protected]",
      "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.

FedEx Request & Response

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

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
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",
      "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": {
      "company_name": "Example Corp.",
      "name": "John Doe",
      "phone": "111-111-1111",
      "email": "[email protected]",
      "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.

UPS Request & Response

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

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": "ups_ground",
    "ship_to": {
      "name": "Amanda Miller",
      "phone": "555-555-5555",
      "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": {
      "company_name": "Example Corp.",
      "name": "John Doe",
      "phone": "111-111-1111",
      "email": "[email protected]",
      "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.

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
50
51
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",
      "email": "[email protected]",
      "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 Example Corp.",
      "company_name": null,
      "phone": "512-485-4567",
      "email": "[email protected]"
      "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.

DHL Express Request & Response

DHL Express custom label messages have the following mappings:

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

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": {
    "confirmation": "none",
    "insurance_provider": "none",
    "service_code": "express_worldwide",
    "carrier_id": "se-105304",
    "ship_to": {
      "name": "ShipStation AU",
      "phone": "512-555-5555",
      "email": "[email protected]",
      "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.