Skip to main content
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

​
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.
CarrierSupports reference_1Supports reference_2Limits (characters per field)SampleNotes
APG◉◉50
Asendia◉◉50
Australia Post◉◉50
Canada Post◉◉35
Couriers Please◉◉50reference_1 and reference_2 strings are joined
DHL eCommerce◉◉30labelFor domestic shipments, reference_1 must be provided when reference_2 is provided
DHL Germany◉◉50
DHL express◉◉50label
Evri (formerly Hermes)◉◉20label
FedEx◉◉50labelSee note below for more details
GLS US◉◉50
Lasership◉◉50
OnTrac◉◉50
Swyft◉◉50
UDS◉◎50
UPS◉◉35label
USPS◉◉30label
Veho◉◎50label

​
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 object.
noteFor versions 2014-02-11 and 2016-10-25, reference_1 and reference_2 are in the Shipments object.
Follow this example showing how to set reference fields.
cURL
curl https://api.goshippo.com/shipments/ \
  -H "Authorization: ShippoToken <API_TOKEN>" \
  -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 object. This can be useful for multi-piece shipments 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
curl https://api.goshippo.com/shipments/ \
-H 'Authorization: ShippoToken <API_TOKEN>' \
-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

​
Add additional details to a FedEx label

For FedEx, Shippo supports more fields where you can add more information. In the Shipments Extras object, you can use the following fields.
  • customer_reference
  • po_number
  • dept_number
  • invoice_number
  • rma_number
Follow this example.
cURL
"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.
cURL
"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 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. 
"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.