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
123456789101112131415161718192021222324252627282930313233343536373839404142434445
POST /v1/labels HTTP/1.1Host: api.shipengine.comAPI-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
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162
{"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
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556
POST /v1/labels HTTP/1.1Host: api.shipengine.comAPI-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
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485
{"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
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354
POST /v1/labels HTTP/1.1Host: api.shipengine.comAPI-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
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485
{"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
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849
POST /v1/labels HTTP/1.1Host: api.shipengine.comAPI-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
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162
{"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
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455
POST /v1/labels HTTP/1.1Host: api.shipengine.comAPI-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
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869
{"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