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 up to three custom label messages denoted by keys reference1, reference2, and reference3 (with supporting carriers).

IMPORTANT Not all carriers support label messages. The following carriers currently support label messages via ShipEngine:

  • Stamps.com
  • FedEx
  • UPS
  • DHL Express
  • OnTrac
  • Access Worldwide
  • APC
  • Globegistics
  • IMEX
  • RR Donnelley
  • Australia Post
  • FirstMile

Stamps.com (USPS)

The Label Messages for Stamps.com USPS labels will display at the bottom of the label, beneath the barcode section.

INFO

60-character limit

Stamps.com custom messages allow up to 60 characters per label message.

An example label message appears in the region boxed in red in the image below.

Stamps Custom Label

Example JSON Request

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.0,
          "unit": "ounce"
        },
        "label_messages": {
            "reference1":"customer reference number 1",
            "reference2":"invoice number 1",
            "reference3":"purchase order number 1"
        }
      }
    ]
  }
}

Example JSON 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"
      }
    }
  ]
}

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

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

Fedex Custom Label

Example JSON Request

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.0,
          "unit": "ounce"
        },
        "label_messages": {
            "reference1":"customer reference number 1",
            "reference2":"invoice number 1",
            "reference3":"purchase order number 1"
        }
      },
      {
        "weight": {
          "value": 1.0,
          "unit": "ounce"
        },
        "label_messages": {
            "reference1":"customer reference number 2",
            "reference2":"invoice number 2",
            "reference3":"purchase order number 2"
        }
      }
    ]
  }
}

Example JSON 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"
      }
    }
  ]
}

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.

UPS Custom Label

Example JSON Request

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.0,
          "unit": "ounce"
        },
        "label_messages": {
            "reference1":"first reference",
            "reference2":"second reference"
        }
      },
      {
        "weight": {
          "value": 1.0,
          "unit": "ounce"
        },
        "label_messages": {
            "reference1":"first reference",
            "reference2":"second reference"
        }
      }
    ]
  }
}

Example JSON 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
      }
    }
  ]
}

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.

INFO

Message limitations for OnTrac labels

OnTrac labels will only display messages in reference 1 and reference 2. 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.

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

OnTrac Custom Label

Example JSON Request

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

{
  "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
      }
    }
  ]
}

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.

curl -O https://api.shipengine.com/v1/downloads/YTQAAdchJkCIcWNwFUErtA/label-1097.pdf -X GET