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

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 For domestic shipments, reference_1 must be provided when reference_2 is provided
DHL Germany ◉ ◉ 50
DHL express ◉ ◉ 50 label
Evri (formerly Hermes) ◉ ◉ 20 label
FedEx ◉ ◉ 50 label See note below for more details
GLS US ◉ ◉ 50
Lasership ◉ ◉ 50
OnTrac ◉ ◉ 50
Sendle ◉ ◉ 40 If reference_2 is not set, we automatically set to "Package for " + shipment.address_to.name as it is a mandatory field
Swyft ◉ ◉ 50
UDS ◉ ◎ 50
UPS ◉ ◉ 35 label
USPS ◉ ◉ 50 label
Veho ◉ ◎ 50 label

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.

note

For 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.

Copy
Copied
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.

Copy
Copied
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": "124 Masters Court",
      "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.

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 fields customer_reference, po_number, dept_number, invoice_number, and rma_number.

Follow this example.

Copy
Copied
"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.

Copy
Copied
"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": ""
 }
}