How to Map Cargo Tracking Events to ERP and TMS Shipment Records

How to Map Cargo Tracking Events to ERP and TMS Shipment Records

To map tracking events to ERP and integrate them with TMS, give every shipment one internal reference, link the carrier's reference to it, translate each carrier event into a short list of internal milestones, and store the events before changing any status. Providers such as Qubictron's container tracking API supply the events, but the rules that turn them into reliable records are yours to define. Status then becomes a value derived from event history, which is what makes duplicates and late updates harmless.

This guide is for logistics teams connecting tracking data to their own systems. It walks through the mapping in five steps, shows ocean and air examples based on Qubictron's documented response fields, and covers the cases that break naive integrations: duplicates, gaps, and out-of-order events.

What Is Cargo Tracking Event Mapping?

Cargo tracking event mapping is the set of rules that translate what a carrier reports into what your systems store. Freight tracking data arrives in the carrier's shape, with the carrier's codes and the carrier's reference numbers. Your ERP and TMS expect their own statuses, their own identifiers, and one record per shipment.

The mapping process answers three separate questions, and keeping them apart makes the design easier:

  • Identity: which of our records does this event belong to?

  • Vocabulary: what does this event mean in our terms?

  • State: what, if anything, should change because of it?

Why ERP and TMS Systems Need Standardized Tracking Events

Carriers describe the same milestone in different words, and a provider can return dozens of event types. An ERP or TMS cannot offer users dozens of statuses per carrier. It needs a short, stable list that reports, alerts, and workflows can rely on.

A reliable ERP and TMS integration therefore starts with a decision about signals, not fields. Sync the few events that change a decision, and keep the rest in an event history where people can find them. The two systems also want different things. ERP shipment tracking integration usually serves finance and inventory: confirmed dates for invoicing and goods receipt. TMS shipment tracking integration serves execution: current status, forecast arrival, and exceptions that need action.

How to Map Cargo Tracking Events to Shipment Records: Step by Step

Step 1. Identify Internal Shipment Records and Tracking References

Start from your own record, not the carrier's. Every shipment in your system has an internal reference, and every tracking reference should point back to it. Shipment ID mapping is a table that links one internal shipment to one or more external references, so that an incoming update always finds its record.

Know what each reference identifies. A carrier reference can be a container number, a Bill of Lading, a booking, or an air waybill. A Bill of Lading can cover several containers, so keep a separate table linking each container to its parent shipment. If your forwarder issued a house reference, store the carrier's master reference beside it, because carriers return data under their own numbers.

Step 2. Collect Cargo Tracking Events from Supported Carriers

Before you register anything, check which carriers and reference types your provider supports. Qubictron's ocean tracking reference accepts a Bill of Lading, container, or booking number, with an optional carrier code, and a separate carriers endpoint lists support by reference type for each carrier.

In a cargo tracking API integration, collection is a loop: request, compare with what you already hold, and process only what is new. Respect the documented rate limit.

Step 3. Normalize Carrier Event Codes and Milestones

Define a short internal milestone list first, then map provider events onto it. The names below are illustrative; use the ones your systems already have.

Provider event (ocean)

Condition

Internal milestone

GTIN

Full container, first port of loading

Gated in at origin

LOAD

Any port

Loaded on vessel

DEPA

Any port

Vessel departed

ARRI

Final port of discharge

Arrived at destination port

DISC

Final port of discharge

Discharged

GTOT

Final port of discharge

Gated out

GTIN

Empty container, depot

Empty returned

Notice that GTIN appears twice. In Qubictron's example response the same code marks the gate-in at origin and the empty container return, and the empty indicator and location type are what tell them apart. Map on the combination of code, empty indicator, and location type, never on the code alone. Always store the raw code and description next to your milestone, and send unknown codes to a review queue instead of guessing.

Step 4. Match Events to Internal Shipment Records

Matching uses the shipment ID mapping table from Step 1. Take the reference from the response, find the internal shipment through the mapping, then attach each event to the right container or air waybill. Shipment reference matching should be exact. A near match that attaches an event to the wrong shipment is worse than an event waiting in an unmatched queue.

Never drop events that cannot be matched. Keep them with the raw payload, alert someone, fix the mapping, then replay them.

Step 5. Update Shipment Statuses and Preserve Event History

Write events to an append-only event table first. Then derive the shipment status from that table: the latest confirmed milestone by event time, not by the order in which updates arrived. Overwriting a status field on every update loses history and makes duplicates dangerous. An event table lets you rebuild a timeline, audit a dispute, and change your rules later.

Cargo Tracking Event Mapping Examples for Ocean and Air Freight

Mapping Container Tracking Events to TMS Records

Consider a Bill of Lading with two containers. The response carries shipment-level fields and a list of containers, each with its own events. A workable mapping looks like this:

Provider field

Internal field

shipment reference number

Carrier reference on the shipment

container number

One container line under the shipment

event code and empty indicator

Internal milestone

event datetime and actual flag

Actual date or estimated date

location reference, resolved to its UN/LOCODE

Port code

vessel and voyage

Transport leg

shipment updated time

Last synced

Each event points to a location by an identifier, and the locations list resolves that identifier to a port and its UN/LOCODE. Resolve it before storing, so your records hold a port code rather than a provider-internal ID. Containers under one Bill of Lading can sit at different stages, so update each container line separately and derive the shipment status from all of them.

Mapping Air Cargo Tracking Events Using AWB Numbers

An air shipment is identified by its air waybill. Qubictron's air tracking API takes the number in the form of a three-digit airline prefix and eight digits, and tolerates spaces or a missing hyphen. Store the normalized form once, so lookups and joins never depend on how a user typed it.

The response gives shipment-level departure and arrival with estimated and actual times, route segments with the flight number, and events with codes such as BKD for booked, DEP for departure, and DLV for delivery. Map those codes onto the same internal milestones you use for ocean where the meaning matches, and keep air-specific ones separate where it does not. The response also carries piece count and weight. Compare them with your own record, because a difference can mean a partial shipment.

How to Handle Duplicate, Missing and Out-of-Order Events

Preventing Duplicate Shipment Updates

Polling returns the history again each time, so most "new" events are ones you already hold. Build a deduplication key from stable fields: the reference, the container or AWB, the event code, the event time, the location, and the empty indicator where it exists. Insert only events whose key you have not seen. A sequence number helps order events inside one response, but do not assume it stays the same between responses.

Handling Delayed and Out-of-Order Tracking Events

An event can arrive hours after it happened, and two events can arrive in the wrong order. Store both the event time and the time you received it, and compute status from event time. Provider timestamps carry offsets, so convert them to one reference time and keep the original offset. Guard against regressions: a late "departed" must not undo an "arrived" that you already hold.

Some outcomes are not events at all. Qubictron's documentation describes carrier-side outcomes, such as no response from the carrier, returned with an HTTP 200 and "success: false" and an empty data section. Treat that as a failed sync, not as "no events", and never overwrite stored history with an empty result.

Keeping Estimated and Actual Milestones Separate

Ocean events carry an actual flag, and air events carry separate estimated and actual times. Store both, and never let an estimate replace an actual. Planning screens in the TMS can use estimates, labelled as such, while the ERP should receive confirmed dates. Keep a history of estimate changes, because a date that keeps moving is itself a signal.

ERP vs TMS: Which Shipment Data Should Be Updated?

Before you map tracking events to ERP, decide what ERP should actually see. Both systems need the shipment reference, but little else overlaps.

Data

TMS

ERP

Full milestone history

Yes

Keep in event store, link from record

Key confirmed milestones

Yes

Yes

Estimated arrival

Yes, labelled

Avoid, or label clearly

Exceptions and delays

Yes

Only if finance acts on them

Container numbers and references

Yes

Yes

Actual arrival and delivery dates

Yes

Yes, for invoicing and receipt

In practice, ERP shipment tracking integration should carry confirmed milestones only, while TMS shipment tracking integration can also carry forecasts and exceptions. Pushing every raw update into ERP shipment records creates noise and false precision. A good test is to name an owner and an action for each synced signal. If nobody acts on it, leave it in the event history.

Best Practices for Reliable Shipment Event Synchronization

  • Normalize once. One layer translates carrier events, then distributes them to each system in its own shape.

  • Keep the milestone list short. Treat shipment event mapping as a decision about which events matter, not a copy of the provider's list.

  • Store raw payloads. You will need them to explain a status and to replay events after fixing a rule.

  • Version the mapping table. Changes should be dated and reviewable.

  • Watch the failure queues. Unmatched events, unknown codes, and failed syncs show where the mapping is weak.

  • Show freshness. Display when each record was last synced.

Frequently Asked Questions

What Is Shipment Event Mapping in Logistics?

It is the translation of carrier tracking events into your own milestones, identifiers, and statuses, so the ERP and TMS can use them consistently.

How Do You Match Cargo Tracking Events to Internal Shipment IDs?

Keep a mapping table that links each internal shipment to its external references, then look up every incoming event through it. Match exactly, and queue anything that does not match.

Can One Tracking API Update Both ERP and TMS Records?

Yes. Collect and normalize the events once, then pass each system the subset and the shape it needs.

How Should ERP and TMS Systems Handle Duplicate Events?

Use a deduplication key built from stable event fields, and make writes idempotent, so processing the same event twice changes nothing.

What Happens When Carrier Tracking Events Arrive Out of Order?

Store them with both event time and received time, and derive status from event time. Guard against status regressions.

Building Reliable Cargo Tracking Data Across Business Systems

Reliable data across ERP and TMS comes from a few unglamorous decisions: one internal reference per shipment, a short milestone list, an append-only event history, and a clear line between estimated and actual. Make those decisions once, test them against real shipments, and the carriers behind them can change without breaking your records.