{"templateId":"markdown","versions":[{"version":"shipstation-v2","label":"ShipStation V2 API","link":"/apis/shipstation-v2/docs/labels/messages","default":true,"active":false,"folderId":"58c9a61d"},{"version":"shipengine","label":"ShipStation API (formerly ShipEngine)","link":"/apis/shipengine/docs/labels/messages","default":false,"active":true,"folderId":"58c9a61d"},{"version":"shipstation-v1","label":"ShipStation V1 API","link":"/apis/shipstation-v1/docs/labels/messages","default":false,"active":false,"folderId":"58c9a61d"}],"sharedDataIds":{"sidebar":"sidebar-apis/@shipengine/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Custom Label Messages","keywords":"shipping, labels, shipstation, documentation, api","siteUrl":"https://docs.shipstation.com","lang":"en-US","llmstxt":{"hide":false,"title":"ShipStation API LLM Docs","description":"Find links and references to all markdown documentation for use with LLMs","excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"custom-label-messages","__idx":0},"children":["Custom Label Messages"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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!"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can use these label messages for things like product names, SKUs, PO numbers, and other info you want displayed on the label."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ShipStation API allows you to add up to three custom label messages denoted by keys ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference1"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference2"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference3"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"requirements","__idx":1},"children":["Requirements"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label_messages"]}," object to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["packages"]}," object for a shipment. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label_messages"]}," object can include the following three properties: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference1"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference2"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference3"]},". The default value for each property is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Carriers that do support label messages may have additional requirements, like maximum character counts."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples-with-supported-carriers","__idx":2},"children":["Examples with Supported Carriers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label_messages"]}," object to your shipments."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"usps-request--response","__idx":3},"children":["USPS Request & Response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["USPS allows up to 60 characters per label message."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /v1/labels HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __YOUR_API_KEY_HERE__\nContent-Type: application/json\n\n{\n  \"shipment\": {\n    \"service_code\": \"usps_priority_mail\",\n    \"ship_to\": {\n      \"name\": \"Amanda Miller\",\n      \"phone\": \"555-555-5555\",\n      \"email\": \"recipient@example.com\",\n      \"address_line1\": \"525 S Winchester Blvd\",\n      \"city_locality\": \"San Jose\",\n      \"state_province\": \"CA\",\n      \"postal_code\": \"95128\",\n      \"country_code\": \"US\",\n      \"address_residential_indicator\": \"yes\"\n    },\n    \"ship_from\": {\n      \"company_name\": \"Example Corp.\",\n      \"name\": \"John Doe\",\n      \"phone\": \"111-111-1111\",\n      \"email\": \"sender@example.com\",\n      \"address_line1\": \"4009 Marathon Blvd\",\n      \"address_line2\": \"Suite 300\",\n      \"city_locality\": \"Austin\",\n      \"state_province\": \"TX\",\n      \"postal_code\": \"78756\",\n      \"country_code\": \"US\",\n      \"address_residential_indicator\": \"no\"\n    },\n    \"packages\": [\n      {\n        \"weight\": {\n          \"value\": 1,\n          \"unit\": \"ounce\"\n        },\n        \"label_messages\": {\n          \"reference1\": \"customer reference number 1\",\n          \"reference2\": \"invoice number 1\",\n          \"reference3\": \"purchase order number 1\"\n        }\n      }\n    ]\n  }\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Stamps.com Response"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"label_id\": \"se-test-176518042\",\n  \"status\": \"processing\",\n  \"shipment_id\": \"se-176518042\",\n  \"ship_date\": \"2017-12-04T00:00:00Z\",\n  \"created_at\": \"2017-12-04T17:46:36.9243135Z\",\n  \"shipment_cost\": {\n    \"currency\": \"usd\",\n    \"amount\": 0\n  },\n  \"insurance_cost\": {\n    \"currency\": \"usd\",\n    \"amount\": 0\n  },\n  \"tracking_number\": \"9999999999999\",\n  \"is_return_label\": false,\n  \"is_international\": false,\n  \"batch_id\": \"\",\n  \"carrier_id\": \"se-143975\",\n  \"service_code\": \"usps_priority_mail\",\n  \"package_code\": \"package\",\n  \"voided\": false,\n  \"voided_at\": null,\n  \"label_format\": \"pdf\",\n  \"label_layout\": \"4x6\",\n  \"trackable\": true,\n  \"carrier_code\": \"stamps_com\",\n  \"tracking_status\": \"unknown\",\n  \"label_download\": {\n    \"pdf\": \"https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.pdf\",\n    \"png\": \"https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.png\",\n    \"zpl\": \"https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.zpl\",\n    \"href\": \"https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.pdf\"\n  },\n  \"form_download\": null,\n  \"insurance_claim\": null,\n  \"packages\": [\n    {\n      \"package_code\": \"package\",\n      \"weight\": {\n        \"value\": 1,\n        \"unit\": \"ounce\"\n      },\n      \"dimensions\": {\n        \"unit\": \"inch\",\n        \"length\": 0,\n        \"width\": 0,\n        \"height\": 0\n      },\n      \"insured_value\": {\n        \"currency\": \"usd\",\n        \"amount\": 0\n      },\n      \"tracking_number\": null,\n      \"label_messages\": {\n        \"reference1\": \"customer reference number 1\",\n        \"reference2\": \"invoice number 1\",\n        \"reference3\": \"purchase order number 1\"\n      }\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The label messages for USPS labels will display at the bottom of the label, beneath the barcode section."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/stamps-custom-label.bf1c40f7965cbf536c4b3cd3f8b13448a677674414e115ecae496c7bb38abb78.65e0c1c5.png","alt":"Stamps Custom Label"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"fedex-request--response","__idx":4},"children":["FedEx Request & Response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["FedEx custom label messages have the following mappings:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Key"},"children":["Key"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"FedEx Label Field"},"children":["FedEx Label Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Character Limit"},"children":["Character Limit"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["reference 1"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Customer Reference"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["REF: reference1"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["35"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["reference 2"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invoice Number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["INV: reference2"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["30"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["reference 3"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Purchase Order Number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PO: reference3"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["30"]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /v1/labels HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __YOUR_API_KEY_HERE__\nContent-Type: application/json\n\n{\n  \"shipment\": {\n    \"service_code\": \"fedex_ground\",\n    \"ship_to\": {\n      \"name\": \"Amanda Miller\",\n      \"phone\": \"555-555-5555\",\n      \"email\": \"recipient@example.com\",\n      \"address_line1\": \"525 S Winchester Blvd\",\n      \"city_locality\": \"San Jose\",\n      \"state_province\": \"CA\",\n      \"postal_code\": \"95128\",\n      \"country_code\": \"US\",\n      \"address_residential_indicator\": \"yes\"\n    },\n    \"ship_from\": {\n      \"company_name\": \"Example Corp.\",\n      \"name\": \"John Doe\",\n      \"phone\": \"111-111-1111\",\n      \"email\": \"sender@example.com\",\n      \"address_line1\": \"4009 Marathon Blvd\",\n      \"address_line2\": \"Suite 300\",\n      \"city_locality\": \"Austin\",\n      \"state_province\": \"TX\",\n      \"postal_code\": \"78756\",\n      \"country_code\": \"US\",\n      \"address_residential_indicator\": \"no\"\n    },\n    \"packages\": [\n      {\n        \"weight\": {\n          \"value\": 1,\n          \"unit\": \"ounce\"\n        },\n        \"label_messages\": {\n          \"reference1\": \"customer reference number 1\",\n          \"reference2\": \"invoice number 1\",\n          \"reference3\": \"purchase order number 1\"\n        }\n      },\n      {\n        \"weight\": {\n          \"value\": 1,\n          \"unit\": \"ounce\"\n        },\n        \"label_messages\": {\n          \"reference1\": \"customer reference number 2\",\n          \"reference2\": \"invoice number 2\",\n          \"reference3\": \"purchase order number 2\"\n        }\n      }\n    ]\n  }\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["FedEx Response"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"label_id\": \"se-1095\",\n  \"status\": \"completed\",\n  \"shipment_id\": \"se-1001759\",\n  \"ship_date\": \"2019-07-25T05:00:00.000Z\",\n  \"created_at\": \"2019-07-25T15:24:46.657Z\",\n  \"shipment_cost\": {\n    \"currency\": \"usd\",\n    \"amount\": 18.3\n  },\n  \"insurance_cost\": {\n    \"currency\": \"usd\",\n    \"amount\": 0\n  },\n  \"tracking_number\": \"794630698100\",\n  \"is_return_label\": false,\n  \"is_international\": false,\n  \"batch_id\": \"\",\n  \"carrier_id\": \"$fedExId$\",\n  \"service_code\": \"fedex_ground\",\n  \"package_code\": \"package\",\n  \"voided\": false,\n  \"voided_at\": null,\n  \"label_format\": \"pdf\",\n  \"label_layout\": \"4x6\",\n  \"trackable\": true,\n  \"carrier_code\": \"fedex\",\n  \"tracking_status\": \"in_transit\",\n  \"label_download\": {\n    \"pdf\": \"https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.pdf\",\n    \"png\": \"https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.png\",\n    \"zpl\": \"https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.zpl\",\n    \"href\": \"https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.pdf\"\n  },\n  \"form_download\": null,\n  \"insurance_claim\": null,\n  \"packages\": [\n    {\n      \"package_code\": \"package\",\n      \"weight\": {\n        \"value\": 1,\n        \"unit\": \"ounce\"\n      },\n      \"dimensions\": {\n        \"unit\": \"inch\",\n        \"length\": 0,\n        \"width\": 0,\n        \"height\": 0\n      },\n      \"insured_value\": {\n        \"currency\": \"usd\",\n        \"amount\": 0\n      },\n      \"tracking_number\": \"794630698100\",\n      \"label_messages\": {\n        \"reference1\": \"customer reference number 1\",\n        \"reference2\": \"invoice number 1\",\n        \"reference3\": \"purchase order number 1\"\n      }\n    },\n    {\n      \"package_code\": \"package\",\n      \"weight\": {\n        \"value\": 1,\n        \"unit\": \"ounce\"\n      },\n      \"dimensions\": {\n        \"unit\": \"inch\",\n        \"length\": 0,\n        \"width\": 0,\n        \"height\": 0\n      },\n      \"insured_value\": {\n        \"currency\": \"usd\",\n        \"amount\": 0\n      },\n      \"tracking_number\": \"794630698177\",\n      \"label_messages\": {\n        \"reference1\": \"customer reference number 2\",\n        \"reference2\": \"invoice number 2\",\n        \"reference3\": \"purchase order number 2\"\n      }\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The label messages are marked in the example label below."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/fedex-custom-label.aa0e7d23e169683daac26ed6e20296d800188516abe37e1e3e4fcb7d1c2e7386.65e0c1c5.png","alt":"Fedex Custom Label"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"ups-request--response","__idx":5},"children":["UPS Request & Response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["UPS custom label messages have the following mappings:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Key"},"children":["Key"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"UPS Label Field"},"children":["UPS Label Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Character Limit"},"children":["Character Limit"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["reference 1"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Customer Reference"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["REF: reference1"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["35"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["reference 2"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invoice Number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["INV: reference2"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["35"]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /v1/labels HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __YOUR_API_KEY_HERE__\nContent-Type: application/json\n\n{\n  \"shipment\": {\n    \"service_code\": \"ups_ground\",\n    \"ship_to\": {\n      \"name\": \"Amanda Miller\",\n      \"phone\": \"555-555-5555\",\n      \"email\": \"recipient@example.com\",\n      \"address_line1\": \"525 S Winchester Blvd\",\n      \"city_locality\": \"San Jose\",\n      \"state_province\": \"CA\",\n      \"postal_code\": \"95128\",\n      \"country_code\": \"US\",\n      \"address_residential_indicator\": \"yes\"\n    },\n    \"ship_from\": {\n      \"company_name\": \"Example Corp.\",\n      \"name\": \"John Doe\",\n      \"phone\": \"111-111-1111\",\n      \"email\": \"sender@example.com\",\n      \"address_line1\": \"4009 Marathon Blvd\",\n      \"address_line2\": \"Suite 300\",\n      \"city_locality\": \"Austin\",\n      \"state_province\": \"TX\",\n      \"postal_code\": \"78756\",\n      \"country_code\": \"US\",\n      \"address_residential_indicator\": \"no\"\n    },\n    \"packages\": [\n      {\n        \"weight\": {\n          \"value\": 1,\n          \"unit\": \"ounce\"\n        },\n        \"label_messages\": {\n          \"reference1\": \"first reference\",\n          \"reference2\": \"second reference\"\n        }\n      },\n      {\n        \"weight\": {\n          \"value\": 1,\n          \"unit\": \"ounce\"\n        },\n        \"label_messages\": {\n          \"reference1\": \"first reference\",\n          \"reference2\": \"second reference\"\n        }\n      }\n    ]\n  }\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["UPS Response"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"label_id\": \"se-1097\",\n  \"status\": \"completed\",\n  \"shipment_id\": \"se-1001762\",\n  \"ship_date\": \"2019-07-25T05:00:00.000Z\",\n  \"created_at\": \"2019-07-25T15:24:46.657Z\",\n  \"shipment_cost\": {\n    \"currency\": \"usd\",\n    \"amount\": 18.82\n  },\n  \"insurance_cost\": {\n    \"currency\": \"usd\",\n    \"amount\": 0\n  },\n  \"tracking_number\": \"1Z28A1R90321487219\",\n  \"is_return_label\": false,\n  \"is_international\": false,\n  \"batch_id\": \"\",\n  \"carrier_id\": \"se-123890\",\n  \"service_code\": \"ups_ground\",\n  \"package_code\": \"package\",\n  \"voided\": false,\n  \"voided_at\": null,\n  \"label_format\": \"pdf\",\n  \"label_layout\": \"4x6\",\n  \"trackable\": true,\n  \"carrier_code\": \"ups\",\n  \"tracking_status\": \"in_transit\",\n  \"label_download\": {\n    \"pdf\": \"https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.pdf\",\n    \"png\": \"https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.png\",\n    \"zpl\": \"https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.zpl\",\n    \"href\": \"https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.pdf\"\n  },\n  \"form_download\": null,\n  \"insurance_claim\": null,\n  \"packages\": [\n    {\n      \"package_code\": \"package\",\n      \"weight\": {\n        \"value\": 1,\n        \"unit\": \"ounce\"\n      },\n      \"dimensions\": {\n        \"unit\": \"inch\",\n        \"length\": 0,\n        \"width\": 0,\n        \"height\": 0\n      },\n      \"insured_value\": {\n        \"currency\": \"usd\",\n        \"amount\": 0\n      },\n      \"tracking_number\": \"1Z28A1R90321487219\",\n      \"label_messages\": {\n        \"reference1\": \"first reference\",\n        \"reference2\": \"second reference\",\n        \"reference3\": null\n      }\n    },\n    {\n      \"package_code\": \"package\",\n      \"weight\": {\n        \"value\": 1,\n        \"unit\": \"ounce\"\n      },\n      \"dimensions\": {\n        \"unit\": \"inch\",\n        \"length\": 0,\n        \"width\": 0,\n        \"height\": 0\n      },\n      \"insured_value\": {\n        \"currency\": \"usd\",\n        \"amount\": 0\n      },\n      \"tracking_number\": \"1Z28A1R90331302827\",\n      \"label_messages\": {\n        \"reference1\": \"first reference\",\n        \"reference2\": \"second reference\",\n        \"reference3\": null\n      }\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The label messages are marked in the example label below."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/ups-custom-label.f6e98f8808f520d02e72cc1e6ef8264847262faa543eac1d61c1eb5b337e885d.65e0c1c5.png","alt":"UPS Custom Label"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"ontrac-request--response","__idx":6},"children":["OnTrac Request & Response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /v1/labels HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __YOUR_API_KEY_HERE__\nContent-Type: application/json\n\n{\n  \"shipment\": {\n    \"service_code\": \"sunrise_service\",\n    \"ship_from\": {\n      \"company_name\": \"Example Corp.\",\n      \"name\": \"John Doe\",\n      \"phone\": \"111-111-1111\",\n      \"email\": \"recipient@example.com\",\n      \"address_line1\": \"4009 Marathon Blvd\",\n      \"address_line2\": \"Suite 300\",\n      \"city_locality\": \"Austin\",\n      \"state_province\": \"TX\",\n      \"postal_code\": \"78756\",\n      \"country_code\": \"US\",\n      \"address_residential_indicator\": \"no\"\n    },\n    \"ship_to\": {\n      \"name\": \"Return Example Corp.\",\n      \"company_name\": null,\n      \"phone\": \"512-485-4567\",\n      \"email\": \"sender@example.com\"\n      \"address_line1\": \"10591 N De Anza Blvd\",\n      \"address_line2\": null,\n      \"address_line3\": null,\n      \"city_locality\": \"Cupertino\",\n      \"state_province\": \"CA\",\n      \"postal_code\": \"95014\",\n      \"country_code\": \"US\"\n    },\n    \"confirmation\": \"None\",\n    \"packages\": [\n      {\n        \"package_code\": \"package\",\n        \"weight\": {\n          \"value\": 1,\n          \"unit\": \"ounce\"\n        },\n        \"label_messages\": {\n          \"reference1\": \"Always be closing\",\n          \"reference2\": \"Winter is here\"\n        }\n      }\n    ]\n  },\n  \"label_layout\": \"letter\"\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OnTrac Response"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"label_id\": \"se-80286067\",\n  \"status\": \"completed\",\n  \"shipment_id\": \"se-184301297\",\n  \"ship_date\": \"2017-12-19T00:00:00Z\",\n  \"created_at\": \"2017-12-19T20:12:52.527Z\",\n  \"shipment_cost\": {\n    \"currency\": \"usd\",\n    \"amount\": 25.58\n  },\n  \"insurance_cost\": {\n    \"currency\": \"usd\",\n    \"amount\": 0\n  },\n  \"tracking_number\": \"D10011210951580\",\n  \"is_return_label\": false,\n  \"is_international\": false,\n  \"batch_id\": \"\",\n  \"carrier_id\": \"se-186282\",\n  \"service_code\": \"sunrise_service\",\n  \"package_code\": \"package\",\n  \"voided\": false,\n  \"voided_at\": null,\n  \"label_format\": \"pdf\",\n  \"label_layout\": \"letter\",\n  \"trackable\": false,\n  \"carrier_code\": \"ontrac\",\n  \"tracking_status\": \"unknown\",\n  \"label_download\": {\n    \"pdf\": \"https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.pdf\",\n    \"png\": \"https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.png\",\n    \"zpl\": \"https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.zpl\",\n    \"href\": \"https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.pdf\"\n  },\n  \"form_download\": null,\n  \"insurance_claim\": null,\n  \"packages\": [\n    {\n      \"package_code\": \"package\",\n      \"weight\": {\n        \"value\": 1,\n        \"unit\": \"ounce\"\n      },\n      \"dimensions\": {\n        \"unit\": \"inch\",\n        \"length\": 0,\n        \"width\": 0,\n        \"height\": 0\n      },\n      \"insured_value\": {\n        \"currency\": \"usd\",\n        \"amount\": 0\n      },\n      \"tracking_number\": null,\n      \"label_messages\": {\n        \"reference1\": \"Always be closing\",\n        \"reference2\": \"Winter is here\",\n        \"reference3\": null\n      }\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The label messages for OnTrac labels will appear on the right side of the label, beneath the barcode and just above the shipping codes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/ontrac-custom-label.0a569a4df190f56fa1a55c9fdb2a82d9c7ccc29861ced7b36475e7b36f481c26.65e0c1c5.png","alt":"OnTrac Custom Label"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"dhl-express-request--response","__idx":7},"children":["DHL Express Request & Response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["DHL Express custom label messages have the following mappings:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Key"},"children":["Key"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"UPS Label Field"},"children":["UPS Label Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Character Limit"},"children":["Character Limit"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["reference 1"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Customer Reference"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["REF: reference1"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["35"]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /v1/labels HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __YOUR_API_KEY_HERE__\nContent-Type: application/json\n\n{\n  \"shipment\": {\n    \"confirmation\": \"none\",\n    \"insurance_provider\": \"none\",\n    \"service_code\": \"express_worldwide\",\n    \"carrier_id\": \"se-105304\",\n    \"ship_to\": {\n      \"name\": \"ShipStation AU\",\n      \"phone\": \"512-555-5555\",\n      \"email\": \"recipient@example.com\",\n      \"company_name\": \"ShipStation AU\",\n      \"address_line1\": \"600 George St\",\n      \"city_locality\": \"Sydney\",\n      \"state_province\": \"NSW\",\n      \"postal_code\": \"2000\",\n      \"country_code\": \"AU\"\n    },\n    \"warehouse_id\": \"se-107273\",\n    \"customs\": {\n      \"contents\": \"documents\",\n      \"customs_items\": [\n        {\n          \"description\": \"letter\",\n          \"quantity\": 1,\n          \"value\": 1,\n          \"harmonized_tariff_code\": \"4817.20\",\n          \"country_of_origin\": \"US\"\n        }\n      ],\n      \"non_delivery\": \"treat_as_abandoned\"\n    },\n    \"packages\": [\n      {\n        \"label_messages\": {\n          \"reference1\": \"Reference kq23YH2\"\n        },\n        \"package_code\": \"package\",\n        \"weight\": {\n          \"value\": 2,\n          \"unit\": \"pound\"\n        },\n        \"dimensions\": {\n          \"unit\": \"inch\",\n          \"length\": 0,\n          \"width\": 0,\n          \"height\": 0\n        }\n      }\n    ]\n  }\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["DHL Express Response"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"label_id\": \"se-1051719\",\n  \"status\": \"completed\",\n  \"shipment_id\": \"se-6478097\",\n  \"ship_date\": \"2020-11-11T00:00:00Z\",\n  \"created_at\": \"2020-11-11T21:36:19.9939671Z\",\n  \"shipment_cost\": {\n    \"currency\": \"usd\",\n    \"amount\": 142.35\n  },\n  \"insurance_cost\": {\n    \"currency\": \"usd\",\n    \"amount\": 0\n  },\n  \"tracking_number\": \"3734944032\",\n  \"is_return_label\": false,\n  \"rma_number\": null,\n  \"is_international\": true,\n  \"batch_id\": \"\",\n  \"carrier_id\": \"se-105304\",\n  \"service_code\": \"express_worldwide\",\n  \"package_code\": \"package\",\n  \"voided\": false,\n  \"voided_at\": null,\n  \"label_format\": \"pdf\",\n  \"display_scheme\": \"label\",\n  \"label_layout\": \"4x6\",\n  \"trackable\": true,\n  \"label_image_id\": null,\n  \"carrier_code\": \"dhl_express\",\n  \"tracking_status\": \"in_transit\",\n  \"label_download\": {\n    \"pdf\": \"https://api.shipengine.com/v1/downloads/0/aVfUNYNxqEmGLYSWQBfkDw/label-1051719.pdf\",\n    \"png\": \"https://api.shipengine.com/v1/downloads/0/aVfUNYNxqEmGLYSWQBfkDw/label-1051719.png\",\n    \"zpl\": \"https://api.shipengine.com/v1/downloads/0/aVfUNYNxqEmGLYSWQBfkDw/label-1051719.zpl\",\n    \"href\": \"https://api.shipengine.com/v1/downloads/0/aVfUNYNxqEmGLYSWQBfkDw/label-1051719.pdf\"\n  },\n  \"form_download\": {\n    \"href\": \"https://api.shipengine.com/v1/downloads/0/1ghTF5EaxkyrawJXoee_Kw/form-1051719.pdf\"\n  },\n  \"insurance_claim\": null,\n  \"packages\": [\n    {\n      \"package_code\": \"package\",\n      \"weight\": {\n        \"value\": 2,\n        \"unit\": \"pound\"\n      },\n      \"dimensions\": {\n        \"unit\": \"inch\",\n        \"length\": 0,\n        \"width\": 0,\n        \"height\": 0\n      },\n      \"insured_value\": {\n        \"currency\": \"usd\",\n        \"amount\": 0\n      },\n      \"tracking_number\": \"3734944032\",\n      \"label_messages\": {\n        \"reference1\": \"Reference kq23YH2\",\n        \"reference2\": null,\n        \"reference3\": null\n      },\n      \"external_package_id\": null\n    }\n  ],\n  \"charge_event\": \"carrier_default\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The label message for DHL Express will appear above the waybill barcode."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/dhl-express-custom-label.509b1fdab1d18033d3fbbd53c49a9a77630b99adbdec97839c5ca1e26e70e4bd.65e0c1c5.png","alt":"DHL Express Custom Label"},"children":[]}]}]},"headings":[{"value":"Custom Label Messages","id":"custom-label-messages","depth":1},{"value":"Requirements","id":"requirements","depth":2},{"value":"Examples with Supported Carriers","id":"examples-with-supported-carriers","depth":2},{"value":"USPS Request & Response","id":"usps-request--response","depth":3},{"value":"FedEx Request & Response","id":"fedex-request--response","depth":3},{"value":"UPS Request & Response","id":"ups-request--response","depth":3},{"value":"OnTrac Request & Response","id":"ontrac-request--response","depth":3},{"value":"DHL Express Request & Response","id":"dhl-express-request--response","depth":3}],"frontmatter":{"seo":{"title":"Custom Label Messages"}},"lastModified":"2026-04-08T10:47:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/shipengine/docs/labels/messages","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}