Reference Codes

Updated by Tony Runyan

In some cases, a carrier may supply a Reference Code from their own list of accepted codes. These are specific to each carrier, so the correct codes should be used for each carrier. These reference codes can be included on the shipping label for use with the specified carrier. There are two ways to accomplish this, using JSON in the Create/Edit Order page, or by specifying a new Order Script in Shipping > Order Scripts.

Normalized Reference Codes 

FedEx and UPS use different Reference Codes, however they have several that are the same. These similar codes have been normalized so the carrier specific key does not need to be looked up.

  • invoice = "Invoice Number"
  • purchase_order = "Purchase Order Number"
  • rma = "RMA Number"

Reference Codes with JSON

A user may wish to add JSON code to their new order using the "Other Shipping Options" field:

Add Purchase Order Number

To simply add a purchase_order number that will appear on the label then copy this code and change the value of the purchase_order.


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

Reference Code Limits

-UPS is limited to two reference numbers

-FedEx is limited to three reference numbers

In order for UPS to the use two specified references or for FedEx to use three specified references; the default System generated reference will need to be disabled by setting default to null. e.g.: "default": null,

Add Carrier specific Reference Codes

In the examples below, the UPS reference code AT and FedEx reference code DEPARTMENT_NUMBER were taken from their respective lists of available codes 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 by the carrier.

Reference Codes with Javascript

Users can have reference codes applied on every new order created by creating a Javascript code snippet in Shipping > Order Scripts.

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 = JSON.stringify( {
"reference_numbers": {
 "default": null,
"purchase_order": matches[1],
    "ups": {
        "AT": "5555"
        }
    }
})
}

Example script using FedEx as the carrier:

let matches;
if (order.options.order_ref
 && (matches = order.options.order_ref.match(/PO#(\w+)/))
) {
  order.options.other_shipping_options = JSON.stringify( {

 "reference_numbers": {
  "default": null,
  "purchase_order": matches[1],
  "fedex": {
      "DEPARTMENT_NUMBER": "Acme Receiving"
            }
        }
    })
}

In the example Javascript code above, the "purchase_order" value is stored at the array index matches[1] from the assignment, (matches = order.options.order_ref.match(/PO#(\w+)/)) . The desired Reference Code (such as "DEPARTMENT_NUMBER" or "AT") would be supplied by the carrier.

Reference Codes on the Shipping Labels

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

How did we do?