Table of Contents
Reference Numbers
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
● 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
Example Address:
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
Max Length for all UPS options is 35 character string.
