Airfreight Track&Trace Explained

0. What This Guide Is (and Why It Exists)

Airfreight tracking data is one of the most misunderstood datasets in logistics.

Most confusion stems from one incorrect assumption:

That tracking data should behave like a clean, linear, immutable timeline.

In reality, airfreight tracking is:

Distributed
Asynchronous
Multi-source
Continuously corrected
Airline-dependent

This guide exists to:

Set clear and realistic expectations
Explain why behaviors that seem “weird” are expected
Provide practical interpretation rules
Help customers build robust, airline-agnostic tracking experiences

If you understand this guide, you have a solid and realistic grasp of how airfreight tracking works in practice.

1. Understanding the Three Event Sets (AWB Subscription)

1.1 `events` - Raw Airline Events (Ordered Historical Feed)

Definition
events is the ordered list of all tracking events known to our system, including both current and historical events (historical events doesn't mean events from past bookings).

It includes:

Events still visible in airline systems
Events that were previously published and later updated, replaced, or removed by the airline

The goal is to preserve full historical continuity.

Critical clarification

events list is not a snapshot of the airline’s current state.

Airlines frequently:

Rebook shipments
Change flights
Reissue BKD, DEP, or other milestones
Remove previously published events from their systems

Our platform intentionally keeps historical events so that:

Customers who missed an update can still understand the shipment’s evolution
Timeline breaks are avoided
UI and business logic can remain flexible

What this means for you

Seeing multiple booking or departure events is expected
Earlier events are not “wrong”; they reflect previous operational intentions
You are free to decide how to present them (collapsed, filtered, or visually deprecated)

1.2 `oldEvents` - Events Already Delivered

Definition
oldEvents represents events that have already been pushed and processed by your system.

Purpose

Acts as a reconciliation reference
Enables incremental updates
Preserves history while avoiding unnecessary reprocessing

Important

An event disappearing from airline systems does not invalidate an oldEvent
Historical events remain valid representations of past states

1.3 `newEvents` - Incremental Updates

Definition
newEvents contains events that are newly received or materially updated compared to oldEvents.

Important nuance

“New” means new to your system, not necessarily new in real-world operations.

Common reasons an event appears in newEvents:

New milestone publication
Enrichment (flight, pieces, weight added)
Timestamp correction
Airline retry or confirmation resend

2. Airline Systems vs. Tracking Reality

2.1 Airline Tracking Is Not Standardized

There is no enforced global standard across airlines for:

Milestone definitions
Event naming
Event sequencing
Data completeness

Examples:

Some airlines never publish ARR
Some rely exclusively on RCF
Some merge multiple operational steps into a single milestone

2.2 Operational Reality vs. Tracking Reality

As a result, events may:

Arrive without full context
Be captured more than once
Be updated in near real time as information becomes available

This is not an anomaly, it is the expected behavior of airfreight tracking systems.

3. Duplicate Events: The Most Common Misunderstanding

3.1 Why Duplicate Events Exist (And Always Will)

In airfreight tracking, duplicated events are common and expected.

They usually occur because:

The same shipment is reported by multiple agents or subsystems
Reports may be emitted minutes apart
Many airfreight systems resend events to:
- Confirm delivery
- Retry transmission
- Ensure downstream systems received the message

Key point

Airlines often resend events instead of updating existing ones.

This is a systemic behavior across the industry.

3.2 Operationnal example of duplicated events

For example, if you receive two (or more) DEP events, this may indicate:

Partial uplift (split shipment)
Reconfirmed departure
Airline retry logic
Same departure reported by different subsystems
Publication triggered by automatic job set on scheduled (planned) departure
Other airline-specific operational behaviors

(above example is for DEP, but can apply to each events)

This does not mean:

The shipment departed twice
The data is incorrect
There is a platform malfunction

3.3 How Our Platform Handles Duplicates

We do not enforce a fixed deduplication window on airline events
We expose events transparently and allow customers to decide how to consume them

Historically:

Events were appended, not replaced

We are actively introducing replacement logic, which is complex due to:

Planned events
Sparse early data
Ambiguous matching criteria

Until replacement is fully deterministic:

Multiple similar events may coexist
This approach favors transparency and avoids accidental data loss

3.4 What Customers Can Do

✔ Treat similar events as confirmations or enrichments
✔ Prefer the most complete event for display
✔ Keep history available for audit and investigation
✔ Do not interpret duplicates as errors

4. Events With Missing Information

4.1 Why Events Are Sometimes Incomplete

Events may be emitted:

Before flight assignment
Before pieces or weight are finalized
From warehouse or handling scans
Without certain fields provided by the airline

This is especially common for:

Planned events
Early booking milestones

4.2 Critical Rule: Transparency Above All

We never infer or fabricate missing data.

This is a strict rule enforced by our system and API to ensure transparency and accuracy:

❌ No guessing
❌ No inferred quantities or routes

If data is missing, it is because the airline did not provide it.
This approach ensures that customers always receive what was actually reported, without risk of misinformation.

4.3 Customer Tips

✔ Display partial events
✔ Expect later enrichment
✔ Communicate “information pending” when relevant

4.4 Event Date

In airfreight, the event date represents the timestamp at which an operational milestone was recorded in an airline or handler system. It does not always represent the exact physical moment the shipment was handled.

What "Event Date" means in Practice

Operational timestamp, when the physical action happened (e.g., cargo loaded on aircraft).
System entry timestamp, when the event was entered into the airline’s or handler's operational system.

Please note that CargoAi will never build up event date, it's either provided by the airline or not provided at all

Why Event Date is sometimes missing

Some airlines treat timestamps as optional, or not relevant, for certain event types (e.g. Booked, BKD, events). If the information is not transmitted by the airline, it will not be returned in API updates.

Why Minutes Apart Event Date are sent for the same event

Seeing the same event code twice with slightly different timestamps is common. This can be explained by multiple reasons:

Manual Corrections, An operator edits the event (e.g., corrects flight number or weight), airline's or handler's System creates a new event instead of overwriting.
Multi-System Synchronization, Ground handler system sends/records event at 10:01, Airline core system republishes same event at 10:05
Partial vs Enriched Event, First event: basic milestone, Second event: same milestone with additional shipment details (pieces/weight)

In this case, if having a duplicated events where only difference stands in event date, we can suggest to use following filter logic

Take the most complete event (event with most fields provided)
If each duplicate have same level of details, you can take the latest one (based on event date)

❗️
This is just an advice, the decision to apply it and its associated risks, impacts, or unintended consequences remain under your sole responsibility

5. Split Shipments (Partial Movements)

5.1 What Is a Split Shipment?

A split shipment occurs when:

One AWB is transported on multiple flights
Cargo is uplifted in parts
Operational constraints require segmentation

This is normal airfreight behavior.

5.2 How Split Shipments Appear in Tracking Data

The most reliable indicator is:

Event-level pieces or weight do not match shipment (root) totals

Typical patterns:

Multiple events for the same milestone
Different flight numbers
Partial quantities per event

Planned events may not yet contain sufficient detail and should not be confused with split confirmation.

5.3 Split Shipment Example

First BKD Event (BCN-MAD):
- This event shares the same shipment details as the root response, indicating that the entire shipment was initially booked on a single flight from BCN (Barcelona) to MAD (Madrid).
  Flight Number: 00733
  Weight: 1000 kg
  Pieces: 34
Second and Third BKD Events (MAD-MEX):
- The next two BKD events show the shipment being split for the journey from MAD (Madrid) to MEX (Mexico City). Each event has different details:
  - Second BKD Event: Indicates part of the shipment (600 kg, 17 pieces) is booked on flight 00322.
  - Third BKD Event: Indicates the remaining part (400 kg, 17 pieces) is booked on flight 00373.

This split between flights 00322 and 00373 shows that the shipment will be transported on two separate flights for the route from Madrid to Mexico City. The differing weight and pieces in these events highlight the division of the shipment.

{
    "awb": "000-11223345",
    "weight": "1000.0",
    "pieces": "34",
    "origin": "BCN",
    "destination": "MEX",
    "events": [
        {
            "code": "BKD",
            "eventLocation": "BCN",
            "eventLocationCoord": "2.07845998,41.29710007",
            "flight": {
                "number": "00733",
                "origin": "BCN",
                "destination": "MAD",
                "originCoord": "2.07845998,41.29710007",
                "destinationCoord": "-3.56676000,40.49360000",
                "date": "2025-10-25T00:00:00+01:00",
                "scheduledDeparture": "2025-10-25T20:00:00+01:00",
                "scheduledArrival": "2025-10-25T14:00:00+01:00",
                "carbonEmission": "325.60 kg (est)",
                "distance": "482.74",
                "duration": "32m 10s"
            },
            "weight": "1000.0",
            "pieces": "34",
            "isPlanned": false,
            "distance": "482.74",
            "origin": "BCN",
            "destination": "MAD",
            "time": "32m 10s",
            "flightNumber": "00733",
            "scheduledDepartureDate": "2025-10-25T20:00:00+01:00",
            "carbonEmission": "325.60 kg (est)",
            "originCoord": "2.07845998,41.29710007",
            "destinationCoord": "-3.56676000,40.49360000"
        },
        {
            "code": "BKD",
            "eventLocation": "MAD",
            "eventLocationCoord": "-3.56676000,40.49360000",
            "flight": {
                "number": "00322",
                "origin": "MAD",
                "destination": "MEX",
                "originCoord": "-3.56676000,40.49360000",
                "destinationCoord": "-99.07209778,19.43630028",
                "date": "2025-10-25T00:00:00+01:00",
                "scheduledDeparture": "2025-10-25T23:15:00+01:00",
                "scheduledArrival": "2025-10-25T03:47:00-06:00",
                "carbonEmission": "955.03 kg",
                "distance": "9065.80",
                "duration": "10h 4m 23s"
            },
            "weight": "600.0",
            "pieces": "17",
            "isPlanned": false,
            "distance": "9065.80",
            "origin": "MAD",
            "destination": "MEX",
            "time": "10h 4m 23s",
            "flightNumber": "00322",
            "scheduledDepartureDate": "2025-10-25T23:15:00+01:00",
            "carbonEmission": "955.03 kg",
            "originCoord": "-3.56676000,40.49360000",
            "destinationCoord": "-99.07209778,19.43630028"
        },
        {
            "code": "BKD",
            "eventLocation": "MAD",
            "eventLocationCoord": "-3.56676000,40.49360000",
            "flight": {
                "number": "00373",
                "origin": "MAD",
                "destination": "MEX",
                "originCoord": "-3.56676000,40.49360000",
                "destinationCoord": "-99.07209778,19.43630028",
                "date": "2025-10-25T00:00:00+01:00",
                "scheduledDeparture": "2025-10-25T15:07:00+01:00",
                "scheduledArrival": "2025-10-25T19:38:00-06:00",
                "carbonEmission": "619.14 kg",
                "distance": "9065.80",
                "duration": "10h 4m 23s"
            },
            "weight": "400.0",
            "pieces": "17",
            "isPlanned": false,
            "distance": "9065.80",
            "origin": "MAD",
            "destination": "MEX",
            "time": "10h 4m 23s",
            "flightNumber": "00373",
            "scheduledDepartureDate": "2023-11-25T15:07:00+01:00",
            "carbonEmission": "619.14 kg",
            "originCoord": "-3.56676000,40.49360000",
            "destinationCoord": "-99.07209778,19.43630028"
        }
    ],
    "status": "PENDING_DELIVERY",
    "originCoord": "2.07845998,41.29710007",
    "destinationCoord": "-99.07209778,19.43630028",
    "carbonEmission": "1899.78 kg (est)",
    "distance": "9548.54",
    "time": "10h 36m 34s"
}

5.4 Customer Handling Guidelines

✔ Display one movement per flight
✔ Do not force linear timelines
✔ Aggregate only at shipment level
✔ Expect parallel or overlapping legs

6. Planned vs Actual Events

We formally distinguish:

Planned events
Actual events

This distinction is exposed via the isPlanned field.

Planned events represent anticipated operations based on schedules and forecasts.
They may change due to delays, cancellations, or operational adjustments.

Always validate planned information until the event becomes actual.

7. Rebooking

7.1 AWB:

Rebooking of AWB is part of Airfreight daily basis.

Whether coming from Freight Forwarders or Airlines, this can be tricky to handle if events are already captured.

Recommendations to handle rebooking cases:

The root origin and destination fields in each update correctly reflect the current first origin and final destination of the AWB (e.g. CDG → JNB initially, then CDG → NRT after rebooking).
These fields should be considered the source of truth for the active routing.
When a rebooking occurs, previously received booking events are moved to oldEvents, while the latest booking events appear in newEvents.
To handle such scenarios going forward, we recommend:
- Relying on the root Origin/Destination to identify the active routing.
- Building or updating the routing logic based on BKD events, using the newEvents list to detect changes and replace or deprecate previous events accordingly.

7.2 Flight:

When the original flight is delayed, replaced, or rebooked due to capacity or operational constraints, the airline may update part or all of the routing. In such cases, the correct approach is to rely on the events provided in newEvents to identify and apply the changes compared to the previous update.

Always use the root origin and destination fields as your primary reference:
- Root origin = first origin of the shipment
  - Root destination = final destination of the shipment
Use BKD events to build the active routing.
Use newEvents vs oldEvents to detect which parts of the routing have changed and should be updated.

7.2.1 partial flight change (same routing)

Expected routing:
SIN → AMS → MAD → JFK

Data representation:

Root origin: SIN
Root destination: JFK
BKD events:
- SIN → AMS (UX1234)
- AMS → MAD (UX1235)
- MAD → JFK (UX1223)

If the airline only modifies the AMS → MAD leg (e.g. new flight number, departure time, or even a different event location), you will receive a new BKD event in newEvents with a more recent event date.

Recommended handling:

Compare newEvents with oldEvents.
Identify the matching leg (AMS → MAD).
Replace or override the previous flight information for that leg only.
Keep the rest of the routing unchanged.

7.2.2 full routing change

If the airline changes the routing entirely and the shipment now follows:
SIN → CDG → BCN → JFK
In this case, you will receive new BKD events for:

SIN → CDG
CDG → BCN
BCN → JFK

Recommended handling:

Rebuild the routing from the BKD events in newEvents.
Compare it with the previous routing.
Replace the previous routing entirely, as it is no longer valid.
Continue to rely on the root origin (SIN) and root destination (JFK) to validate the first and last legs.

7.3 Summary of rebooking handling:

Use root Origin/Destination to determine the active shipment endpoints.
Use BKD events to construct the routing.
Use newEvents to detect changes and oldEvents as historical context.
Apply partial overrides when only one leg changes.
Perform a full routing rebuild when the airline provides a completely new set of BKD events.

This approach ensures your routing remains aligned with the most recent and authoritative airline data while preserving historical consistency.

7. Why Our API May Show More Events Than Airline Websites

7.1 Airline Websites Are Not a Source of Truth

Airline public websites are:

Designed for end users
Simplified by design
Often intentionally incomplete

They typically show:

A reduced milestone set
Aggregated shipment states
A filtered view of backend data

7.2 Our Data Sources Are Different

We do not rely on airline public websites as a primary data source.

Instead, we prioritize:

Official airline APIs
Backend operational integrations

These sources expose:

More milestones
Intermediate operational events
Higher-fidelity tracking data

When possible, we also leverage complementary sources to maintain continuity.

7.3 Why Differences Are Expected

As a result:

Our API may return more events
Timelines may appear richer than airline websites
Some milestones may never be visible publicly

This does not indicate a data quality issue, it reflects deeper operational visibility.

7.4 Important Takeaway

Airline websites are a reference, not a source of truth
Our data is often more complete and operationally accurate
Differences are expected and normal
Only case where differences are unexpected is when airline public tracking contains more information than our tool

If the goal is to exactly mirror an airline website, embedding airline iframes is the appropriate approach, with known trade-offs in normalization and scalability.

8. Coverage, Guarantees & Limitations

100% milestone coverage is not guaranteed
Coverage depends on airline systems
Some airlines never emit certain events

This is inherent to the industry.

9. Why We Provide a Standardized Model

We deliberately avoid customer-specific or airline-specific tracking logic.

Instead, we focus on:

One standardized tracking model
One integration
Broad airline coverage

This approach enables:

Scalability
Consistency
Predictable behavior across airlines

Customers remain free to apply additional logic on top of the standardized model if needed.
We are happy to support consultancy requests regarding the interpretation of specific use cases and can provide guidance whenever needed.

10. Final Principles to Remember

Tracking data reflects signals, not absolute truth
Missing does not mean wrong
Duplicates usually mean confirmation or enrichment
Partial data is still valuable
Airline websites are simplified views
Planned events are volatile
Standardization enables scale

0. What This Guide Is (and Why It Exists)

1. Understanding the Three Event Sets (AWB Subscription)

1.1 events - Raw Airline Events (Ordered Historical Feed)

1.2 oldEvents - Events Already Delivered

1.3 newEvents - Incremental Updates

2. Airline Systems vs. Tracking Reality

2.1 Airline Tracking Is Not Standardized

2.2 Operational Reality vs. Tracking Reality

3. Duplicate Events: The Most Common Misunderstanding

3.1 Why Duplicate Events Exist (And Always Will)

3.2 Operationnal example of duplicated events

3.3 How Our Platform Handles Duplicates

3.4 What Customers Can Do

4. Events With Missing Information

4.1 Why Events Are Sometimes Incomplete

4.2 Critical Rule: Transparency Above All

4.3 Customer Tips

4.4 Event Date

What "Event Date" means in Practice

Why Event Date is sometimes missing

Why Minutes Apart Event Date are sent for the same event

❗️This is just an advice, the decision to apply it and its associated risks, impacts, or unintended consequences remain under your sole responsibility

5. Split Shipments (Partial Movements)

5.1 What Is a Split Shipment?

5.2 How Split Shipments Appear in Tracking Data

5.3 Split Shipment Example

5.4 Customer Handling Guidelines

6. Planned vs Actual Events

7. Rebooking

7.1 AWB:

7.2 Flight:

7.2.1 partial flight change (same routing)

7.2.2 full routing change

7.3 Summary of rebooking handling:

7. Why Our API May Show More Events Than Airline Websites

7.1 Airline Websites Are Not a Source of Truth

7.2 Our Data Sources Are Different

7.3 Why Differences Are Expected

7.4 Important Takeaway

8. Coverage, Guarantees & Limitations

9. Why We Provide a Standardized Model

10. Final Principles to Remember

1.1 `events` - Raw Airline Events (Ordered Historical Feed)

1.2 `oldEvents` - Events Already Delivered

1.3 `newEvents` - Incremental Updates

❗️
This is just an advice, the decision to apply it and its associated risks, impacts, or unintended consequences remain under your sole responsibility