Custom Reference Numbers and Shipment Fields

This article explains how the Tai TMS lets you define your own named reference fields on shipments, so you can capture internal identifiers and tracking data that do not have a dedicated built-in field, how the reference fields a shipment shows can follow the organizations on that shipment, and what the shipment booking screen's standard fields are.

Overview

The Tai TMS ships with a large set of built-in reference numbers for freight (pickup number, PRO number, customer PO number, shipper reference, trailer number, and many more). When your business tracks something the system does not have a built-in field for, such as an internal file code, a project name, a customer-specific identifier, or a link to an outside record, you can create your own custom reference number. A custom reference number is a named field you define once (you choose the label, the kind of data it holds, where it applies, and who sees it) and then fill in on individual shipments. Because you name the field yourself, a custom reference can be called almost anything, which means a label you see on a shipment (for example an unusual word like "Skittles") is simply whatever your organization decided to call that custom field. Its meaning is defined by your company, not by the TMS.

Where your organization has it enabled, the same settings can also control the built-in reference numbers, such as the customer PO number and the shipper reference. The reference fields that a shipment shows, in both the back office and the customer portal, can then follow the organizations that are on that shipment rather than a single customer-level list.

How it works

Setting up a custom reference number happens in two parts. First, an administrator defines the field on the Shipment Reference Numbers page (in the back-office LSP menu, available to users with the site administration or LSP add/edit permission): you give it a display name, pick the type of data it holds, choose which parts of a shipment it applies to, and decide who can see it. After that, staff (and, if you allow it, your customers) simply enter a value into that field on a shipment, the same way they would fill in any other reference number.

When you define the field you choose:

An owner. Your own company, or a specific customer or sub-organization under you. This is how you can make a field apply to (and be visible to) one particular customer rather than everyone.
A display name. Up to 100 characters, using letters, numbers, and spaces only. The name cannot match the name of a built-in reference field, and it cannot duplicate another field owned by the same organization.
A data type. Text, Number, Decimal, Currency, Date, Date & Time, Email, Phone, or Link. The data type controls how the value is entered and validated (for example, a Date field shows a date picker, and a Link field holds a web address). A Date & Time value keeps the date and time exactly as typed and is not shifted for time zones.
Where it applies. You can attach the field to the shipment as a whole, to individual stops, and/or to individual commodities. For each of those levels you set it to Off, Optional, or Required. At least one level must be turned on. The Required choice is offered only where required reference numbers are enabled for your organization; otherwise the choices are Optional or Off.
Which shipment types it applies to. Where this is enabled, a setting can apply to all shipment types or to just one domestic shipment type, so the same field can be required on one kind of shipment and optional on another.
Allowed values. For a Text field you can either allow free-form typing (the default for a new field is that free-form is not allowed) or provide a list of predefined values so users choose from a set list. Each predefined value can have optional display text, and one value can be marked as the default. If free-form is not allowed, at least one predefined value is required. Other data types are always entered as free-form but are validated to their type.
Who sees it. You choose whether the field appears for your back-office staff and whether it also appears to customers in the customer portal. Customer visibility requires the shipment-level use to be turned on, and a field shown to customers is always shown to staff as well.

Once values are entered, custom reference numbers are stored on the shipment alongside the built-in references and can be used as search criteria when you look shipments up. When a required field has a predefined default value, that default is filled in automatically when a new shipment is created (where required reference numbers are enabled).

Which fields a shipment shows. The Tai TMS can decide which reference fields a shipment offers in two ways, depending on how your organization is set up:

Customer-based. The fields come from the customer's own settings.
Following the organizations on the shipment. Where this is enabled, the fields come from the settings of the organizations that appear on the shipment (for example the customer and its parent offices). For each reference field, the setting from the closest organization applies, and a broker-wide setting applies when no organization has defined one. A setting that is switched off at the shipment level gives way to a setting that is switched on elsewhere in the chain. A built-in field such as the PO number or the shipper reference is shown only if a setting applies to it or the shipment already holds a value for it. Custom fields that are hidden from the back office are not offered to staff.

On a back-office shipment, empty optional reference fields are tucked behind a Show more control. If a field has a configured default value, the default is shown as a hint, but it is not saved on the shipment until someone selects it.

In the customer portal. Customers see the reference fields that the broker has made visible to customers. The customer PO number and the shipper reference are always listed first. A customer can fill in a visible field that is still blank on an existing shipment, but cannot overwrite a value that has already been entered. A required field must be filled in before the customer can save. Values are displayed to match their data type (for example currency, dates, phone numbers, and clickable links), and when a customer duplicates a shipment they can choose which of the reference numbers they can see should be copied to the new shipments. The reference columns that a customer can add to the shipment search follow the same visibility.

Stop and commodity reference numbers in the customer portal. Where reference fields follow the organizations on the shipment, customers can also enter reference numbers on stops and on commodities (line items), not just on the shipment as a whole. A stop or commodity field is offered when it is visible to customers and switched on (Optional or Required) at that level. Every commodity also offers Shipper Reference Number, Customer PO Number, and Temperature unless the customer's settings hide them. When booking a new shipment, customers fill these in under Origin Reference Numbers, Destination Reference Numbers, and on each commodity, and a required one must be completed before they can continue. On an existing shipment, each stop and line item shows its reference numbers with an edit control. As with shipment-level fields, a customer can fill in a blank field but cannot change a value already entered, and they cannot edit them once the shipment is complete or canceled. When a customer duplicates a shipment, the duplicate window offers Stop Reference Numbers and Commodity Reference Numbers choices (selected by default) whenever the original holds such values, and only the fields the customer can see are copied.

Built-in reference numbers and the same settings. To let one set of settings control both built-in and custom references, the Tai TMS is gradually moving built-in shipment-level reference values into the same storage as custom ones. During this transition the system keeps both copies in step, and a scheduled background check adds or corrects any missing or out-of-date copies, so the values you see on a shipment do not change and nothing needs to be done on your side. Reference values on stops and commodities are not part of this move yet.

The shipment booking screen (where a new shipment is created or quoted) has its own set of standard entry fields: origin and destination addresses, pickup ready and close dates and times, equipment type and length, commodity and freight details, declared value, an insurance option, and two standard reference fields, Shipper Reference Number and Customer PO Number. Other reference values (built-in or custom) are captured on the shipment's reference-numbers area rather than as fixed fields on that initial booking form.

Business rules & limits

You name custom fields yourself. A custom reference label can be almost any word or phrase (letters, numbers, and spaces, up to 100 characters). What a given custom field means is decided by the organization that created it; the TMS does not assign meaning to the label. The label just cannot reuse the name of a standard built-in reference field.
Data type is enforced. Each custom field has a data type (Text, Number, Decimal, Currency, Date, Date & Time, Email, Phone, or Link) and entries are validated against it. A stored value can be up to 200 characters.
A field can apply to shipments, stops, and/or commodities. For each level you choose Off, Optional, or Required, and at least one level must be enabled. "Required" means the value must be provided where that field applies, and it is available only where required reference numbers are enabled.
Predefined values only apply to Text fields. Number, date, currency, and other typed fields are always free-form. For a Text field that is not free-form, at least one predefined value must be listed, and only one value can be the default.
Visibility is configurable, with one dependency. You control whether a custom field shows to back-office staff and/or to customers in the customer portal. Showing a field to customers requires that it also be shown to staff and that it be used at the shipment level. A field that is shown only to the back office is not shown to customers.
Custom fields are scoped to an organization. Each custom field is owned by a specific organization, so you can target a field to a single customer or sub-organization instead of applying it to all accounts.
The closest organization wins. Where reference settings follow the organizations on the shipment, a setting from a closer organization takes precedence over a setting from a more distant one, and a setting limited to one shipment type takes precedence over an all-types setting from the same organization. A setting that is off at the shipment level is overridden by an applicable setting that is on.
Customers can add but not overwrite. In the customer portal a reference field that already holds a value is read-only. Only blank, visible fields can be filled in. This applies to shipment, stop, and commodity reference numbers alike.
Customer-portal stop and commodity reference numbers need the organization-based settings. Customers can enter reference numbers on stops and commodities only where reference fields follow the organizations on the shipment, and only for fields that are visible to customers and switched on at that level. They cannot be edited once the shipment is complete or canceled.
Trailer and VIN are not fields on the booking screen. The new-shipment booking form's standard reference fields are Shipper Reference Number and Customer PO Number. Trailer and VIN are not part of that fixed booking-form field set.
Trailer Number already exists as a built-in reference; VIN does not. "Trailer Number" (along with Truck Number, Driver Name, Seal Number, Container Number, and others) is a built-in reference type you can capture on a shipment even though it is not on the booking form. VIN has no built-in field anywhere in the system, so to track a VIN you create a custom reference field for it (or ask Tai about adding a dedicated field).
Custom references travel with your shipment data, but not into every message. Custom reference numbers are included in the shipment details that the public API returns and in the shipment details sent by outbound webhooks that use the newer payload (such as the webhook action in workflow automation). When the recipient is a customer, only the fields that are visible to customers are included. They are not automatically added to carrier dispatch or EDI messages, although a particular load-board connection may forward them. Custom report builder reports can include them as their own columns.
Integrations can manage custom reference types. Where you have public API access, an integration can list, create, update, and delete the custom reference types for an organization it can reach. Renaming a type updates the name on the values already saved. Deleting a type does not delete the values already saved on shipments; they stay on those shipments but are no longer tied to the deleted field.
Other pick-lists can read these settings. Where customer reference settings are enabled, choices such as the on-hold reason and the reference choices shown in the cancel-shipment window read the values configured for the customer.

Frequently asked questions

We see a reference field on our shipments with an unusual name (for example "Skittles"). What is it?

That is almost certainly a custom reference number your organization set up in the Tai TMS. Custom reference fields are named by the customer who creates them, so the label can be any word your team chose. The TMS does not assign meaning to that label; it is whatever your company decided to track in that field. To find out exactly what it represents, check with whoever administers your Tai account or look at how the field is defined on the Shipment Reference Numbers page.

Can we add Trailer and VIN as fields on the booking screen?

The Tai TMS booking (new-shipment) screen has a fixed set of standard fields, and Trailer and VIN are not among them. Its standard reference fields are Shipper Reference Number and Customer PO Number. However, you can still capture both. "Trailer Number" is a built-in reference type you can record on the shipment's reference numbers. VIN has no built-in field, so the recommended way to track it is to create a custom reference field named "VIN" (choose Text as the data type) and enable it at the shipment level. If you would rather have a dedicated field added to a screen, contact Tai to request it.

How do we capture our own internal tracking data when there is no built-in field for it?

Use a custom reference number. In the Tai TMS an administrator defines a custom field (its name, its data type, which levels of the shipment it applies to, such as shipment, stop, and/or commodity, and who can see it), and then that field becomes available for staff (and optionally customers) to fill in on shipments. This lets you record internal identifiers, project codes, links, dates, or any other value the standard fields do not cover.

Who can create custom reference fields, and where?

Custom reference fields are set up on the Shipment Reference Numbers page in the Tai TMS back office, by a user with the site administration or LSP add/edit permission, not on the shipment itself. That page is where you define the field's name, data type, the shipment levels it applies to, its visibility, and which organization it belongs to. Regular users then simply enter values into fields that have already been defined.

Can a custom reference field be shown only to a specific customer?

Yes. Each custom reference field is owned by an organization, and you can assign it to a specific customer or sub-organization rather than to your whole account. You separately control whether the field appears to your back-office staff and whether it appears to customers in the customer portal, so you can scope both the ownership and the visibility of the field.

What kinds of data can a custom reference field hold?

A custom reference field can be configured as Text, Number, Decimal, Currency, Date, Date & Time, Email, Phone, or a Link (web address). The data type controls how the value is entered and validated. For Text fields you can also choose to offer a list of predefined values instead of free-form typing, so users select from a defined set, and you can mark one of them as the default.

Are custom reference numbers searchable?

Yes. Once a custom reference field is defined and values are entered on shipments, those custom reference numbers are available as search criteria in shipment search, alongside the built-in reference numbers. This lets you find shipments by the internal identifiers your business actually uses.

Can a custom reference field be required?

Yes, where required reference numbers are enabled for your organization. When you define the field you can set it to Required at any of the levels it applies to (shipment, stop, or commodity). A required custom field must be filled in where it applies. You can also leave it Optional, or turn it Off for levels where it should not appear, as long as it is enabled for at least one level. Where it is not enabled, fields can be Optional or Off only.

Why does a reference field show on one customer's shipments but not on another's?

In the Tai TMS, the reference fields a shipment offers can follow the organizations that are on that shipment. Each reference field uses the setting from the closest organization that has one, so two customers can see different fields, different required rules, or different predefined values for the same shipment type. A field also appears for a particular kind of shipment only if its setting applies to that shipment type.

Can our customers fill in reference numbers themselves in the customer portal?

Yes, for the fields the broker has made visible to customers. In the customer portal the customer PO number and shipper reference are always listed first. A customer can fill in a blank visible field on an existing shipment but cannot change a value that is already there, and a field marked as required must be completed before the customer can save.

Can customers enter reference numbers on individual stops or line items in the customer portal?

Yes, where the Tai TMS is set up so reference fields follow the organizations on the shipment. Customers then see stop and commodity reference fields that are visible to customers and switched on at that level. They fill them in under Origin Reference Numbers, Destination Reference Numbers, and on each commodity when booking, and on an existing shipment they can fill in blank ones from each stop or line item until the shipment is complete or canceled. Required ones must be completed before booking can continue, and a value already entered cannot be changed by the customer. When a customer duplicates a shipment, they can choose whether to copy the stop and commodity reference numbers they can see.

Will our integrations see our custom reference numbers?

Yes. In the Tai TMS, custom reference numbers are included in the shipment details returned by the public API and in the shipment details sent by outbound webhooks that use the newer payload, such as the webhook action in workflow automation. When the recipient is a customer, only the fields that are visible to customers are included. They are not automatically added to carrier dispatch or EDI messages.

Did my built-in reference numbers change when reference settings were extended to them?

No. In the Tai TMS, built-in shipment-level reference values are being moved gradually into the same storage as custom reference numbers so that one set of settings can control both. During the move the system keeps both copies in step and a background check repairs differences, so the values you see on a shipment stay the same and no action is needed.