Skip to content
English
Customer portal
Go to Tai Software
  • There are no suggestions because the search field is empty.

Custom Shipment Reference Numbers

Create and configure reference numbers for shipments, stops and commodities, set them Off, Optional or Required, and control the values users can enter.

What this does

Shipment Reference Numbers let you define the reference fields your team and your customers need, choose whether each one is Off, Optional or Required for shipments, stops and commodities, and control exactly which values users can enter. One page manages both the standard Master reference numbers that come with Tai, such as PO Number, and the custom ones you create yourself.

  • Make a reference mandatory. Set any reference number, including standard ones like PO Number, to Required at the shipment, stop or commodity level.
  • Give users a pick list. Add Predefined Values with friendly Display Text, and turn off free-form entry so only approved codes are saved.
  • Fill it in automatically. Mark one value as the Default so it is pre-selected for users.
  • Tailor it per customer. Copy a setting to a customer or sub-organization so they get their own rules and values.
  • Use the values everywhere else. Reference values flow into documents, custom reports, Universal Search and the Public API.

On this page

Back to top

User Guide

Before you start: what you need first

  • Access to Back Office → LSP → Shipment Reference Numbers. You need the LSP Add/Edit permission, or Site Admin.
  • For a reference with a pick list, the list of values (and, for EDI, the exact codes your trading partner expects).

How to find your reference numbers

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

  • The page lists every reference number available to your organization: your own, and the standard Master reference numbers such as PO Number.
  • Use the search fields and click Search. Choose Master in the Organization search to see only the standard reference numbers.
  • Each row shows Owner Name, Display Name, Data Type, the Shipment / Stop / Commodity setting (Off, Optional or Required), and Display In.
  • Row actions: Edit Reference Number, Copy Reference Setting and Delete Reference Number.
  • You can search, create and edit reference numbers at your own organization level and at any organization beneath you in the hierarchy, including customers. You cannot manage references for organizations outside your hierarchy.

How to create a reference number

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

  • Owner Name: the organization the reference number belongs to.
  • Display Name: what users see on the shipment. Names can be up to 100 characters, must be unique across your accounting organization, cannot contain special characters, and cannot match the name of a built-in Tai reference number.
  • Data Type: the kind of value the field accepts. See "Data types" below.
  • Reference Type: for each of Shipment, Stop and Commodity, choose:
    • Off: not available at this level.
    • Optional: users can add it when they need it.
    • Required: users must fill it in before they can save. See "What Off, Optional and Required do" below.
    At least one level must be Optional or Required.
  • Shipment Type: leave as All Shipment Types, or pick one shipment type the setting applies to. A reference can only be added to shipments of a matching type.
  • Display In:Front Office, Back Office, or both. See "How Display in Back Office and Front Office work" below.
  • Free-Form Allowed:Yes lets users type any value, up to 254 characters. No limits them to your Predefined Values.
  • Predefined Values: the values users pick from. Each row has:
    • Value: what is saved on the shipment and sent to your integrations.
    • Display Text (Optional): the friendly label users see in the dropdown. If blank, users see the Value.
    • Default: check one row to pre-select it. Only one value can be the Default.
    When Free-Form Allowed is No, you need at least one value before you can save.

            Click Save.

Data types

  • Currency
  • Date
  • Date Time
  • Decimal
  • Email: must include "@" and a full address before it saves.
  • Number: numbers only; letters are not accepted.
  • Phone
  • String: letters and numbers, no set format. Use String for code lists like reason codes.
  • Link: stores a URL. It shows as a clickable link on Shipment Details and in the Front Office, and as editable text on Shipment Edit, where it must be a valid URL. The link text is the URL itself.

How to use a standard reference number like PO Number

Where to go: Back Office → LSP → Shipment Reference Numbers → search with Organization = Master.

  • Master reference numbers cannot be edited or deleted directly. Their name and type are fixed.
  • To set one up your way, click Copy Reference Setting on its row and choose your organization (or a customer). You can then set it Off, Optional or Required at each level, add Predefined Values and set a Default, just like your own reference numbers.

How to create a reference number for one customer or sub-organization

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

  1. Create the reference number under the parent organization. Uncheck both Front Office and Back Office so it does not appear for everyone.
  2. On its row, click Copy Reference Setting.
  3. In the modal, choose the customer or sub-organization as the Owner, set the levels, display and values, and click Save.

The copied setting applies only to that customer or sub-organization.

Which setting applies when there is more than one

A reference number has two parts: the type (its name and data type) and the setting (where it applies and how it behaves). A single type can have several settings, for example one for each customer that uses it.

  • 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 own setting makes it Required, it is Required on that customer's shipments.

How Display in Back Office and Front Office work

  • Display in Front Office — when on, customers can see and fill in the reference in the Customer Portal. It is only available when Shipment is Optional or Required, because the Front Office shows shipment-level reference numbers only. Checking Front Office also checks Back Office.
  • Display in Back Office — when off, Tai treats the reference as if it does not exist for that organization. It does not appear anywhere.
  • You can only turn off Display in Back Office if Display in Front Office is also off.

What Off, Optional and Required do

Where it happens: the Back Office shipment screens.

  • Shipment level: a Required reference shows in Shipment References with the required indicator.
  • Stop level: every stop needs a value. The Edit Stop modal will not save until it is filled.
  • Commodity level: every commodity line needs a value.
  • Required applies to the shipment types the setting covers. With All Shipment Types, that is every shipment.
  • Once a Required reference has a value, that value can be replaced but not emptied. To clear it entirely, change the setting to Optional or Off first.

How Default values behave on a shipment

  • On a Required reference, the Default is saved to the shipment. New shipments get a Required shipment-level Default automatically, so users can save without choosing.
  • On an Optional reference, the Default is shown but not saved until a user saves the reference number themselves.
  • Leave Default unchecked whenever you want users to make a deliberate choice.

How to add or edit reference numbers on a shipment

Where to go: Back Office → open a shipment.

  • Shipment: Shipment References on Create/Edit and on Shipment Details.
  • Stop: the stop on Create/Edit and on Shipment Details.
  • Commodity: Items to Ship on Create/Edit and on Shipment Details.
  • You can view, edit and delete any reference number on any shipment you have access to.
  • You can add any reference number 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.
  • Dropdowns show each value's Display Text, including in the shipment cancellation dialog. The Value is what is saved.

What customers can do in the Customer Portal

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 set up for any organization involved in the shipment, as long as it has Display in Front Office on and does not already have a value.
  • Customers cannot change or delete a reference number that already has a value. Only your staff can.

What happens when you delete a 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 becomes read-only. If it is removed from a shipment, it cannot be added back.
  • Custom reports: reports that use the reference keep running. To edit the report again, first remove the deleted reference from it.

Using reference numbers in Content Templates

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

  • Each reference number with Shipment set to Optional or Required gets its own system tag, in the format [CUSTOM_SHIPMENT_REFERENCES.NAME].
  • When you type a system tag, suggestions include every custom reference number owned by your accounting organization. You can also type a tag manually for any reference name, even if it is not suggested.
  • When the template is generated, every 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).

Using 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 both on the report and has a value on the shipment. Otherwise the cell is blank.

How reference numbers work in the Public API

What an API key can do depends on whose key it is. All 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.
  • POST / PUT / DELETE Custom Shipment Reference Number Types create, update and delete types whose setting is in the key owner's hierarchy. A delete removes the setting, and removes the type only if no other settings remain.
  • ShipmentReferenceNumbers on a shipment follows the same rules as Shipment Details: 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 only types with Display in Front Office turned on.
  • ShipmentReferenceNumbers on a shipment follows the same rules as the Customer Portal: view references with Display in Front Office on, and add them only where no value exists.
  • Customer keys cannot create, update or delete reference types, and cannot change or delete existing values.

Using reference numbers in Universal Search

Type a reference number's value into Universal Search. Matching shipments are returned with the reference number in bold, the same as PRO, BOL or Invoice numbers.

Tips & best practices

  • Use Required only when every shipment, stop or commodity line truly needs the value. To require a value only in certain situations, such as late arrivals, use Validation Rules with the reference number set to Optional or Off.
  • For EDI codes, set Free-Form Allowed to No and enter the partner's code as the Value. Put the friendly label in Display Text.
  • Leave Default unchecked when you want users to make a deliberate choice.
  • Remember that Stop = Required applies to every stop, including the first pickup and final delivery.
  • Set a reference up at your accounting organization if every customer uses it. Add a customer-level setting only when that customer needs different behavior, because it will override the accounting-level one.
  • 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.

Back to top

Frequently asked questions

Can I make PO Number required?

Yes. Search with Organization = Master to find PO Number, click Copy Reference Setting, choose your organization, and set Shipment to Required.

Why can't I edit or delete a Master reference number?

Master reference numbers are standard across Tai. Copy the setting to your organization to change how it works for you.

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 is Required has its own setting that overrides the accounting-level one.

Why is the Front Office checkbox greyed out?

Front Office only shows shipment-level reference numbers. Set Shipment to Optional or Required and the checkbox unlocks.

Why can't I save my reference number?

Check that at least one of Shipment, Stop or Commodity is not Off, that the Display Name is unique and has no special characters, and that you have added a value if Free-Form Allowed is No.

Why does every stop ask for this reference number?

Stop is set to Required, and Required applies to every stop. To ask only in certain situations, set it to Optional and use a Validation Rule.

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 can't my customer see a reference number in the Customer Portal?

The closest setting to that customer does not 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 your 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 are read-only and cannot 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.

Which value is sent to my EDI partner, the Value or the Display Text?

The Value. Display Text is only a label for your users.

Back to top

If something doesn't work

  • A reference number doesn't appear on a shipment: check that its level (Shipment, Stop or Commodity) is not Off, that Display In includes Back Office (or Front Office), and that its Shipment Type matches the shipment.
  • "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 is not a built-in Tai reference type.
  • Users can type any value: set Free-Form Allowed to No.
  • The required field is already filled in: the reference number has a Default. Uncheck it if users should choose.
  • A required reference number isn't enforced: Required is enforced on the Back Office shipment screens. Shipments created through the API, imports or the Front Office are not blocked.
  • 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 reference number's Display Name and a shipment number.

To learn more, see Validation Rules.