Reference Numbers

Updated 2 weeks ago by Cory M.

ShipStream support both normalized reference codes that are commonly supported by most carriers and also custom codes for specific carriers. These reference numbers will sometimes be printed on the label and sometimes just transmitted to the carrier's system for future purposes such as billing or tracking.

ShipStream generates a default Reference Number using the Order Ref # if present, otherwise the Order # and if there are multiple shipments and/or multiple packages may include for example "S1/2" and "P1/2" to indicate "shipment 1 of 2" or "package 1 of 2" respectively. This may be shortened depending on the length and the carrier's maximum length. This format is subject to change so if you need it to follow a specific format you can override it by specifying a default reference number.

Normalized Reference Numbers

The normalized reference numbers listed below are automatically translated to carrier-specific reference number codes for you if supported by the carrier. For example, the invoice reference number will be submitted as CustomerReferenceType=INVOICE_NUMBER for FedEx and ReferenceNumber->Code=IK for UPS.

The supported normalized reference number types are:

  • default
  • invoice
  • purchase_order
  • rma

Other carrier-specific reference number codes are also supported. See Carrier-specific Reference Numbers below.

Other Shipping Options

You may specify custom reference numbers using the Other Shipping Options field. This field may be specified on the order page:

or via the API and Import using the "other_shipping_options" key in the options parameter or in a Script by assigning an object in a Before Create Order Script to order.options.other_shipping_options.

Example: Purchase Order Number

To assign a reference number with the type "Purchase Order" and value "XZY-123" to an order you would specify the following value for the Other Shipping Options field.

{"reference_numbers":{"purchase_order":"XYZ-123"}}

Reference Number Limits

UPS is limited to two reference numbers
FedEx is limited to three reference numbers

Some carriers may not support as many reference numbers as others. For example, in order for UPS to use two additional references you may need to disable the default reference number by setting default to null.

{
"reference_numbers": {
"default": null,
"invoice": "I-430001",
"purchase_order": "PO-98851"
}
}

Carrier-specific Reference Numbers

In the examples below, the UPS reference code AT and FedEx reference code DEPARTMENT_NUMBER were taken from their respective lists of available codes (see the Appendix at the end for a full list) to include these numbers on the shipping labels along with a purchase_order number.

Example using UPS as the carrier:

{
"reference_numbers": {
"default": null,
"purchase_order": "XYZ-123",
"ups": {
"AT": "5555"
}
}
}

Example using FedEx as the carrier:

 {
"reference_numbers": {
"default": null,
"purchase_order": "XYZ-123",
"fedex": {
"DEPARTMENT_NUMBER": "Acme Receiving"
}
}
}

In the example JSON code above, the "purchase_order" values would be replaced with the user's predefined value and the desired Reference Code and value would be supplied to the carrier.

Assigning Reference Numbers with Scripts

Often the best way to assign reference numbers is to extract the reference number from another piece of order information and assign it to a reference number code using a Before Create Order Script.

Example script using UPS as the carrier:

let matches;
if (order.options.order_ref
&& (matches = order.options.order_ref.match(/PO#(\w+)/))
) {
order.options.other_shipping_options = {
"reference_numbers": {
"default": null,
"purchase_order": matches[1],
"ups": {
"AT": "5555"
},
"fedex": {
"DEPARTMENT_NUMBER": "Acme Receiving"
}
}
}
}

Explanation: In the example JavaScript code above, the "purchase_order" value is extracted from the order_ref field and stored at the array index matches[1] from the assignment, (matches = order.options.order_ref.match(/PO#(\w+)/)) . The other reference numbers would likely be dictated by a supplier or vendor.

Shipping Label Examples

Below are examples of how the shipping labels would look using the example code from above:

FedEx

UPS

FedEx Reference Number Codes

See FedEx WebServices Developer Guide 2020

UPS Reference Number Codes

See UPS Shipping Package Developer Guide 2019


How did we do?