Custom Reference Numbers: Who Can See and Use Them

What this does

Custom Reference Numbers let you define your own reference fields (for example, a PO or Store Number) for a customer, a sub-organization, or your whole accounting organization. Where a reference is set up determines who can see it, who can add it to a shipment, and where it appears across the TMS.

Capture the references each customer actually needs, without cluttering every shipment.
Decide which references your customers can see and fill in from the Customer Portal.
Use your references in content templates, custom reports, and the Public API.

User Guide

Before you start — what you need first

To manage custom reference numbers, you need the LSP Add/Edit permission (or Site Admin).

How custom reference numbers are set up — types and settings

Every custom reference number has two parts:

Type — the reference itself: its name and data type (Currency, Date, Date Time, Decimal, Email, Number, Phone, String, or Link). Every type belongs to your accounting organization.
Setting — where the type applies and how it behaves. You can add a setting at the accounting organization, a sub-organization, or a customer. A single type can have several settings, for example one for each customer that uses it.

A setting controls:

Whether the reference is Off, Optional, or Required at the shipment, stop, and commodity level.
Whether it displays in the Back Office and in the Front Office (Customer Portal).
The shipment type it applies to. A reference can only be added to shipments of a matching shipment type.

Which setting applies when there's more than one

If a type has settings at more than one level, the setting closest to the customer always wins.
For example, if your accounting organization makes a reference Optional and a customer's setting makes it Required, it's Required on that customer's shipments.

How Display in Back Office and Display in Front Office work

Display in Front Office — when on, customers can see and fill in the reference in the Customer Portal.
Display in Back Office — when off, the TMS treats the reference as if it doesn't exist for that organization. It doesn't appear anywhere.
You can only turn off Display in Back Office if Display in Front Office is also off.

Naming rules for custom reference numbers

Each name must be unique within your accounting organization. You can't create two types with the same name, even if they're set up for different customers.
You can't use the name of a built-in TMS reference number type.
Names can be up to 100 characters.

How to create, edit, or search custom reference numbers

Where to go: Back Office → LSP → Shipment Reference Numbers.

You can search for, create, and edit custom reference numbers at your own organization level and at any organization beneath you in the hierarchy, including customers.
You can't manage references for organizations outside your hierarchy.

What happens when you delete a custom reference number

Where to go: Back Office → LSP → Shipment Reference Numbers.

Deleting removes the setting for that one organization.
If no other settings remain for that type, the type is deleted too. If other organizations still have a setting, the type stays and keeps working for them.
Shipments: the reference and its value stay on shipments that already have it, but it can't be edited. If it's removed from a shipment, it can't be added back.
Custom reports: reports that use the reference keep running. To edit the report again, first remove the deleted reference from it.

How to add or edit reference numbers on a shipment (Back Office)

Where to go: Back Office → open a shipment → Shipment Detail → reference numbers (in-line editing).

You can view, edit, and delete any reference number on any shipment you have access to.
You can add any reference number that is set up for any organization involved in the shipment — the customer, its sub-organizations, and the accounting organization — even if that organization is outside your own hierarchy.
Only references set up for the shipment's type are available to add.

What customers can do in the Customer Portal (Front Office)

Where to go: Customer Portal → open a shipment.

Customers see a reference number only if its setting has Display in Front Office turned on.
Customers can add a reference number that is set up for any organization involved in the shipment, as long as it has Display in Front Office turned on and doesn't already have a value.
Customers can't change or delete a reference number that already has a value.

How to use custom reference numbers in content templates

Where to go: Back Office → Content Templates → edit a template.

When you type a system tag, suggestions include every custom reference number owned by your accounting organization, using the format [CUSTOM_SHIPMENT_REFERENCES.NAME].
You can type a tag manually for any reference name, even if it isn't suggested.
When the template is generated for a shipment, every custom reference tag that has a value on that shipment is filled in, no matter which organization the reference was set up for.
If the shipment has no value for a tag, it resolves as blank (or false, for conditional checks).

How to use custom reference numbers in custom reports

Where to go: Reports → Custom Reports → create or edit a report.

You can add any custom reference number owned by your accounting organization as a report column.
When the report runs, a reference value appears only if the reference is on the report and has a value on the shipment. Otherwise the cell is blank.

How custom reference numbers work in the Public API

What an API key can do depends on whose key it is. All of the rules above (closest setting wins, Display in Back Office, shipment type) apply to the API too.

Broker staff API keys

GET Shipment Reference Number Types — returns every type with a setting on the key owner's organization or any organization above it, up to the accounting organization.
GET Custom Shipment Reference Number Types — returns every type with a setting on the customer you pass in, or any organization above it, up to the accounting organization.
POST Create Custom Shipment Reference Number Types — creates a type for the customer you pass in, as long as that customer is in the key owner's hierarchy.
PUT Update Custom Shipment Reference Number Types — updates a type whose setting is in the key owner's hierarchy.
DELETE Delete Custom Shipment Reference Number Types — deletes the setting if it's in the key owner's hierarchy, and deletes the type only if no other settings remain.
ShipmentReferenceNumbers on a shipment — same rules as Shipment Detail: view, edit, and delete any reference on shipments the key can access, and add any reference set up for any organization on the shipment.

Customer staff API keys

GET Shipment Reference Number Types — returns every type with a setting on the customer's organization or above it, up to the accounting organization, that has Display in Front Office turned on.
ShipmentReferenceNumbers on a shipment — same rules as the Customer Portal: view references with Display in Front Office on, and add them only when they don't already have a value.
Customer keys can't create, update, or delete reference types, and can't change or delete existing values.

Tips & best practices

Set up a reference at the accounting organization if every customer uses it. Add a customer-level setting only when that customer needs different behavior — it will override the accounting-level setting.
To hide a reference from one customer entirely, turn off both Display in Front Office and Display in Back Office on that customer's setting.
Before deleting a reference, check whether other customers use the same type, and whether any custom reports include it.

Frequently asked questions

Why can't I create a reference number with a name that already exists?

Names must be unique across your accounting organization. If another customer already has a reference with that name, add a setting to the existing type for your customer instead of creating a new one.

Why is a reference Required for one customer but Optional for another?

The setting closest to the customer wins. The customer where it's Required has its own setting that overrides the accounting-level one.

Why can I add a reference on a shipment that I can't edit on the configuration page?

On a shipment, you can add references from every organization involved in that shipment, even outside your hierarchy. The configuration page only shows organizations at or below your level.

Why don't I see a reference number on a shipment?

Either the shipment's type doesn't match the reference's shipment type, Display in Back Office is off for the closest setting, or the reference is Off at that level (shipment, stop, or commodity).

Why can't my customer see a reference number in the Customer Portal?

The closest setting to that customer doesn't have Display in Front Office turned on. Turn it on and the customer will see it.

Why can't my customer change a reference number they entered?

Customers can only fill in references that are empty. Once a reference has a value, only broker staff can change or delete it.

Why can't I edit a reference number on an older shipment?

The reference was deleted. Deleted references stay visible on shipments that already have them, but they're read-only and can't be re-added once removed.

Why can't I save changes to my custom report?

The report includes a reference number that was deleted. Remove that column, then save.

If something doesn't work

"Reference Type with name "…" already exists." — pick a different name, or add a setting to the existing type.
"Reference Type name "…" is reserved and matches a built-in reference number type." — pick a name that isn't a built-in reference type.
Can't find a reference on the configuration page? Confirm the organization is at or below your level in the hierarchy.
Still stuck? Contact Tai Support with the shipment number and the reference name.

Applies to: TMS Back Office, Customer Portal, Public API · Last updated: 2026-09-29