RocketShipIt

Reference Numbers on a Shipping Label, and How to Add Them

A reference number on a shipping label is a value you choose and attach to the shipment: a purchase order number, an order ID, an invoice number, an RMA. The carrier prints it on the label, stores it against the shipment, and gives it back to you on tracking. It is how a package gets matched to the order it belongs to.

It is not the tracking number. The carrier assigns the tracking number; you assign the reference. A label can carry both, and usually should.

Typical uses:

Reference Who reads it
Purchase order number The receiving dock at a retailer, matching the delivery to the PO on the routing guide
Order or invoice number Your own warehouse and support team, matching a package to an order
RMA / return authorization Returns processing, routing the box to the right queue
Customer or department number Internal cost allocation

You can also print it as a barcode, so the receiving warehouse scans it instead of typing it.

Adding a reference#

Reference values are set per package, as a code-and-value pair. The code says what kind of reference it is; the value is the reference itself:

{
  "carrier": "UPS-REST",
  "action": "submitshipment",
  "params": {
    "key": "your-key-from-authenticate-request",
    "packages": [
      {
        "weight": 4,
        "reference_code": "PO",
        "reference_value": "12382871",
        "reference_barcode": true,
        "reference_code2": "IN",
        "reference_value2": "10000"
      }
    ]
  }
}

UPS Label with Reference Value

reference_code PO is UPS's code for a purchase order number and IN for an invoice number. The full list for each carrier is in Parameters: reference_code and reference_value.

What each carrier allows#

UPS FedEx
References per package 2 4
Value length 35 characters 30 characters
Codes Two-letter codes (PO, IN, RZ, …) Named types (P_O_NUMBER, INVOICE_NUMBER, …)
Print as barcode reference_barcode, reference_barcode2 Not sent

FedEx takes reference_code3 / reference_value3 and reference_code4 / reference_value4 as well; UPS stops at two.

The UPS international trap#

UPS only accepts package-level references on domestic shipments — US to US, or PR to PR. On anything else UPS requires the reference at shipment level, so RocketShipIt sends the first package's reference there and drops the rest. On an international UPS shipment that means:

  • only one reference survives, from the first package
  • reference_code2 / reference_value2 are not sent
  • reference_barcode has no effect

If an international shipment needs a per-package identifier, put it in the package description or use FedEx, which has no such restriction.

There is also a shipment-level reference_code / reference_value pair. On a domestic UPS shipment it is copied onto the first package when that package has no reference of its own — a convenience for single-package shipments, not a way to set one reference across many packages.

Tracking by reference#

Both carriers can look a shipment up by the reference instead of the tracking number, which is what makes references worth setting even when nothing prints them.

UPS takes reference_number in place of tracking_number:

{
  "carrier": "UPS-REST",
  "action": "track",
  "params": {
    "key": "your-key-from-authenticate-request",
    "reference_number": "12382871"
  }
}

UPS searches the last 14 days of pickups by default. For anything older, pass ship_date_begin and ship_date_end to widen the window — otherwise a reference that exists returns nothing and looks like a lost package.

FedEx needs the reference in tracking_number plus a tracking_id_type saying what kind of reference it is, and either your account number or the destination postal code and country:

{
  "carrier": "FedEx-REST",
  "action": "track",
  "params": {
    "key": "your-key-from-authenticate-request",
    "tracking_number": "318511",
    "tracking_id_type": "PURCHASE_ORDER",
    "carrier_code": "FDXE",
    "to_country": "US",
    "to_code": "01835",
    "ship_date_begin": "2026-05-01",
    "ship_date_end": "2026-05-24"
  }
}

A tracking response returns whatever references the carrier holds for the package in reference_numbers, so a reference set at label time comes back on every scan.

Examples#

Related: Tracking, Shipping Labels, and FedEx Ground Collect, where a PO number on the label is usually mandatory.