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.
- Add the
label_messagesobject to thepackagesobject for a shipment. Thelabel_messagesobject can include the following three properties:reference1,reference2, andreference3. The default value for each property isnull. - 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.
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 allows up to 60 characters per label message.
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": "recipient@example.com",
"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": "sender@example.com",
"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
{
"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 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 |
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": "recipient@example.com",
"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": "sender@example.com",
"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
{
"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 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 |
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": "recipient@example.com",
"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": "sender@example.com",
"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
{
"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 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.
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": "recipient@example.com",
"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": "sender@example.com"
"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
{
"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 custom label messages have the following mappings:
| Key | UPS Label Field | Example | Character Limit |
|---|---|---|---|
| reference 1 | Customer Reference | REF: reference1 | 35 |
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": "recipient@example.com",
"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
{
"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.
