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": "Mickey and Minnie Mouse",
      "phone": "+1 (714) 781-4565",
      "company_name": "The Walt Disney Company",
      "address_line1": "500 South Buena Vista Street",
      "city_locality": "Burbank",
      "state_province": "CA",
      "postal_code": "91521",
      "country_code": "US",
      "address_residential_indicator": "No"
    },
    "ship_from": {
      "name": "Dade Murphy",
      "phone": "512-485-4282",
      "company_name": "Zero Cool",
      "address_line1": "345 Chambers Street",
      "address_line2": "Suite 100",
      "city_locality": "New York City",
      "state_province": "NY",
      "postal_code": "10282",
      "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 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": "Mickey and Minnie Mouse",
      "phone": "+1 (714) 781-4565",
      "company_name": "The Walt Disney Company",
      "address_line1": "500 South Buena Vista Street",
      "city_locality": "Burbank",
      "state_province": "CA",
      "postal_code": "91521",
      "country_code": "US",
      "address_residential_indicator": "No"
    },
    "ship_from": {
      "name": "Dade Murphy",
      "phone": "512-485-4282",
      "company_name": "Zero Cool",
      "address_line1": "345 Chambers Street",
      "address_line2": "Suite 100",
      "city_locality": "New York City",
      "state_province": "NY",
      "postal_code": "10282",
      "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 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": "Mickey and Minnie Mouse",
      "phone": "714-781-4565",
      "company_name": "The Walt Disney Company",
      "address_line1": "500 South Buena Vista Street",
      "city_locality": "Burbank",
      "state_province": "CA",
      "postal_code": "91521",
      "country_code": "US",
      "address_residential_indicator": "No"
    },
    "ship_from": {
      "name": "Dade Murphy",
      "phone": "512-485-4282",
      "company_name": "Zero Cool",
      "address_line1": "345 Chambers Street",
      "address_line2": "Suite 100",
      "city_locality": "New York City",
      "state_province": "NY",
      "postal_code": "10282",
      "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 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": {
          "name": "Dade Murphy",
          "company_name": "Zero Cool",
          "phone": "212-555-5555",
          "address_line1": "345 Chambers Street",
          "address_line2": null,
          "address_line3": null,
          "city_locality": "New York City",
          "state_province": "NY",
          "postal_code": "10282",
          "country_code": "US"
        },
        "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 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