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 thepackages
object for a shipment. Thelabel_messages
object 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.
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.
Stamps.com Response
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 |
FedEx Response
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 |
UPS Response
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.
OnTrac Response
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 |
DHL Express Response
The label message for DHL Express will appear above the waybill barcode.