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": "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.

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

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.

Copy

Copied

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