# Carrier reference fields Some carriers enable you to add reference information to your label. Depending on your application, you could use this to add information like customer order numbers or other reference details to a shipping label. For example, USPS print reference fields at the bottom of the their label. ![USPS sample label with the location of ref1 and ref2 highlighted](/assets/label-ref-usps.f8e96a89f01e6186e1e88a92a0b7eb82cf80fe1adf99f505699c2ae79b7ba682.594db778.png) ## Supported carriers Not every carrier supports this and different carriers enable this in different ways. Refer to this table for details on Shippo supported carriers that have enabled this feature. | Carrier | Supports `reference_1` | Supports `reference_2` | Limits (characters per field) | Sample | Notes | | --- | --- | --- | --- | --- | --- | | APG | ◉ | ◉ | 50 | | | | Asendia | ◉ | ◉ | 50 | | | | Australia Post | ◉ | ◉ | 50 | | | | Canada Post | ◉ | ◉ | 35 | | | | Couriers Please | ◉ | ◉ | 50 | | `reference_1` and `reference_2` strings are joined | | DHL eCommerce | ◉ | ◉ | 30 | [label](/assets/label-ref-dhl-ecomm.10b44657ec27b9eb77a3cc9d65a62dd94ef6792a0a58076814596a97bfd55feb.594db778.png) | For domestic shipments, `reference_1` must be provided when `reference_2` is provided | | DHL Germany | ◉ | ◉ | 50 | | | | DHL express | ◉ | ◉ | 50 | [label](/assets/label-ref-dhl.1c383825e118eead77fc54992ad1b7f509e57b1181636f9e5993e12ee14c5684.594db778.png) | | | Evri (formerly Hermes) | ◉ | ◉ | 20 | [label](/assets/label-ref-evri.516f84f4c1a5cdc365256efe35772b173119b483e3fada869f3bd057efebea84.594db778.png) | | | FedEx | ◉ | ◉ | 50 | [label](/assets/label-ref-fedex.2f36d7bfaeddd9c64b7cb320b8a1b1a558855cc73238b4976c3e0fc8516ef508.594db778.png) | See [note](#add-additional-details-to-a-fedex-label) below for more details | | GLS US | ◉ | ◉ | 50 | | | | Lasership | ◉ | ◉ | 50 | | | | OnTrac | ◉ | ◉ | 50 | | | | Swyft | ◉ | ◉ | 50 | | | | UDS | ◉ | ◎ | 50 | | | | UPS | ◉ | ◉ | 35 | [label](/assets/label-ref-ups.ab26975bca02368605bc71a5064176562f30f9f740764c3bfc277628a2765442.594db778.png) | | | USPS | ◉ | ◉ | 50 | [label](/assets/label-ref-usps.f8e96a89f01e6186e1e88a92a0b7eb82cf80fe1adf99f505699c2ae79b7ba682.594db778.png) | | | Veho | ◉ | ◎ | 50 | [label](/assets/label-ref-veho.b5e42d0351f4123cfb26c3d8edf0d9f7f09a4352b6c77f0b402fc15192a2a64a.594db778.png) | | ## Add reference details to a Shipment To add reference details to a label for a supported carrier, use the fields `reference_1` and `reference_2` in the [Shipments Extras](/shippoapi/public-api/shipments/shipmentextra) object. note For versions `2014-02-11` and `2016-10-25`, `reference_1` and `reference_2` are in the [Shipments](/docs/api_concepts/apichangelog/#shipments) object. Follow this example showing how to set reference fields. ``` curl https://api.goshippo.com/shipments/ \ -H "Authorization: ShippoToken " \ -H "Content-Type: application/json" \ -d $'{ "address_to": { "name": "Mr Hippo", "street1": "965 Mission St #572", "city": "San Francisco", "state": "CA", "zip": "94103", "country": "US", "phone": "4151234567", "email": "mrhippo@shippo.com" }, "address_from": { "name": "Mrs Hippo", "street1": "1092 Indian Summer Ct", "city": "San Jose", "state": "CA", "zip": "95122", "country": "US", "phone": "4159876543", "email": "mrshippo@shippo.com" }, "parcels": [{ "length": "10", "width": "15", "height": "10", "distance_unit": "in", "weight": "1", "mass_unit": "lb" }], "extra": { "reference_1": "x999000", "reference_2": "Box no 5" }, "async": false }' ``` ## Add reference details to a Parcel You can also define reference details in your parcel. To add reference details to a label for a supported carrier, use the fields `reference_1` and `reference_2` in the [Parcels Extras](/shippoapi/public-api/parcels/parcelextra) object. This can be useful for [multi-piece shipments](/docs/shipments/multipieceshipment) where you may choose to add a different reference to each label. If you define both a parcel reference and a shipment reference, the parcel reference will be printed on your label (if your carrier supports it). Follow this example showing how to set different references for each label in a multi-piece shipment. ``` curl https://api.goshippo.com/shipments/ \ -H 'Authorization: ShippoToken ' \ -H 'Content-Type: application/json' \ -d $'{ "address_from": { "name": "Mr Hippo", "street1": "965 Mission Street", "street2": "Suite 480", "city": "San Francisco", "state": "CA", "zip": "94103", "country": "US", "phone": "4151234567", "email": "mrhippo@goshippo.com" }, "address_to": { "name": "Mr Hippo", "street1": "2967 Filbert Dr", "street2": "APT 3", "city": "Walnut Creek", "state": "CA", "zip": "94598", "country": "US", "phone": "4151234567", "email": "mrhippo@goshippo.com" }, "parcels": [{ "weight": "8", "length": "9", "width": "3", "height": "8", "distance_unit": "in", "mass_unit": "lb", "extra": { "reference_1": "Parcel1 ref 1" }}, {"weight": "8", "length": "9", "width": "3", "height": "8", "distance_unit": "in", "mass_unit": "lb", "extra": { "reference_2": "Parcel2 ref 2" } }], "extra": { "signature_required": "DIRECT", "reference_1": "Text shipment ref 1", "reference_2": "Text shipment ref 2" }, "async": false }' ``` The following are the resulting labels. ![sample multipiece label](/assets/multipiecelabel.6225999b2ef8b2171a6014587c691cea599fbbb414ff1cb16c7232b4f312ed42.594db778.png) ## Add additional details to a FedEx label For FedEx, Shippo supports more fields where you can add more information. In the [Shipments Extras](/shippoapi/public-api/shipments/shipmentextra) object, you can use the following fields. * `customer_reference` * `po_number` * `dept_number` * `invoice_number` * `rma_number` Follow this example. ```shell "extra": { "customer_reference": { "prefix": "REF#", "value": "my ref is 12234" }, "po_number": { "prefix": "PO#", "value": "my number is 12234" }, "dept_number": { "prefix": "DEPT#", "value": "dept number is 555" }, "invoice_number": { "prefix": "INV#", "value": "my number is 5555" }, "rma_number": { "prefix": "RMA#", "value": "rma number is 555" } } ``` Note, these fields are available only on ZPL labels and support up to 11 characters for the prefix and up to 40 characters for the value. * If `customer_reference` is used, reference_1 will be ignored. * If `po_number` is used, reference_2 will be ignored. * If `invoice_number` is used, for international shipments, `shipment.customs_declaration.invoice` will be ignored. ### Omnichannel shipping with FedEx You can also customize FedEx’s label prefixes to meet those requirements for omnichannel shipping and label specific SOPs. Note, this applies to ZPL labels only. The following example uses the ARN which is a unique shipment number assigned by Amazon to track the shipments and the LOAD number is a reference number for the shipment. ```shell "extra": { "customer_reference": { "prefix": "ARN#", "value": "23256" }, "po_number": { "prefix": "LOAD#", "value": "12234" }, "dept_number": { "prefix": "DP", "value": "555" }, "invoice_number": { "prefix": "invoice #", "value": "2999905" }, "rma_number": { "prefix": "RMA#", "value": "" } } ``` ## Add additional details to a UPS label You can add additional reference fields to UPS ZPL II labels. UPS allows a maximum of five reference fields for a single label. In the [Shipments Extras](/shippoapi/public-api/shipments/shipmentextra) object, you can use the following fields. * `accounts_receivable_customer_account` * `appropriation_number` * `bill_of_lading_number` * `cod_number` * `customer_reference` * `dealer_order_number` * `dept_number` * `fda_product_code` * `invoice_number` * `manifest_number` * `model_number` * `part_number` * `po_number` * `production_code` * `purchase_request_number` * `rma_number` * `salesperson_number` * `serial_number` * `store_number` * `transaction_reference_number` Follow this example. ```shell "extra": { "accounts_receivable_customer_account": { "prefix": "Accounts Rec:", "value": "", "ref_sort": 1 }, "appropriation_number": { "prefix": "Approp No.:", "value": "", "ref_sort": 2 }, "bill_of_lading_number": { "prefix": "Bill Lading:", "value": "", "ref_sort": 4 }, "cod_number": { "prefix": "COD:", "value": "", "ref_sort": 3 }, "customer_reference": { "prefix": "REF#", "value": "my ref is 12234", "ref_sort": 5 } ``` Use `ref_sort` to define the order your references are printed on your label. If you choose to use `ref_sort`, you cannot use the same number more than once. If you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references.