Custom Label Messages

Label messages can be used for a number of reasons; but, primarily are used for reference numbers or internal tracking messages. You can add separate label messages to each package in a shipment.

Three custom label messages are supported, denoted by keys reference1, reference2, and reference3

info Not all carriers support label messages. ShipEngine currently supports label messages for Stamps.com, FedEx, UPS, OnTrac, Access Worldwide, APC, Globegistics, IMEX, and RR Donnelley.

Stamps.com (USPS)

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

info

60 character limit

Stamps.com custom messages are limited to 60 characters per label message

Your label messages can be seen in the regions marked in red in the below image

Stamps Custom Label

Example Request

curl -iX POST https://api.shipengine.com/v1/labels \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-H 'Content-Type: application/json' \
-d '{
  "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"
        }
      }
    ]
  }
}'
  • curl

Example 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

Your label messages can be seen in the regions marked in red in the below image

Fedex Custom Label

Example Request

curl -iX POST https://api.shipengine.com/v1/labels \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '
{
  "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"
        }
      }
    ]
  }
}'
  • curl

Example Resposne

{
  "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 30
reference 3 Purchase Order Number PO: reference3 30

Your label messages can be seen in the region marked in red in the below image

UPS Custom Label

Example Request

curl -iX POST https://api.shipengine.com/v1/labels \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '
{
  "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"
        }
      }
    ]
  }
}'
  • curl

Example 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 be shown on the right side of the label, beneath the barcode, and just above the shipping codes.

Info

OnTrac Label message limitations

OnTrac Labels will only display messages in reference 1 and reference 2. Reference 3 can be submitted, but the will be ignored by the carrier. Any messages longer than 25 characters may appear cut off by the label margins.

Your label messages can be seen in the region marked in red in the below image

OnTrac Custom Label

Example Request

curl -iX POST https://api.shipengine.com/v1/labels \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '{
    "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"
}'
  • curl

Example 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 It!

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
  • curl