Skip to content 
A freight tracking API is a connection that lets your ERP, TMS or customer portal pull shipment location, status events and estimated arrival from a carrier or forwarder.
The people asking “where is my freight?” are usually your own sales team, your customer service desk and your customers. A tracking API answers them from your own systems instead of from a forwarder’s portal or an inbox. The term shipment tracking API is often used for the same thing, though it usually implies parcel. This guide covers how tracking APIs work, which identifier to use for each mode, the two ways updates reach you, and how to normalize milestones, with notes on what the ExFreight freight API covers.
Key takeaways
- The identifier you track by depends on the mode: PRO number for LTL, container or bill of lading number for ocean, air waybill number for air.
- Updates reach your system by polling (you ask) or push notifications (the provider sends). The choice affects freshness and load on both sides.
- Map provider statuses to one internal milestone model so air, ocean and trucking shipments read the same on your dashboards.
How freight tracking APIs work
Freight tracking data comes from several sources, and a tracking API is the layer that combines them. The sources differ by mode:
- Carrier systems. LTL and truckload carriers record pickup, terminal arrivals and departures, out-for-delivery and delivery scans against a PRO number.
- Ocean carriers and terminals. Container events such as gate in, loaded on vessel, discharged and gate out, published against container and bill of lading numbers.
- Airlines and handlers. Acceptance, departure, arrival and ready-for-pickup events against the air waybill.
- Manual updates. Operations staff add events that no automated feed catches: a customs hold, an appointment set with the receiver, a delivery exception.
The tracking service collects those events, ties them to your shipment reference and returns them in one response. ExFreight tracking for API users covers location-based digital tracking and manual updates. On the platform, ocean and air shipments show on a map throughout transit, and automated email status alerts run alongside tracking. The tracking information page shows how a shipment is looked up today.
What a tracking response contains
Whatever the provider, a usable tracking response gives your system enough to update an order without a human reading it. Conceptually, expect:
- Shipment references. The booking reference plus mode-specific numbers (PRO, container, house bill of lading, air waybill) as they become available.
- Current status. The latest milestone, with the date, time and time zone it occurred.
- Location. City, terminal, port or airport for the latest event, which is what a location-based tracking feed adds over a plain status code.
- Event history. The full list of prior events, not only the latest, so you can rebuild the timeline after an outage on your side.
- Estimated arrival. The current estimate for delivery or arrival at the destination port or airport.
- Exception detail. A reason when something has gone wrong: customs hold, refused delivery, damage, missed appointment.
Watch the time zones. A pickup in Chicago, a departure from a U.S. port and an arrival in Rotterdam are three different local times. Store events in UTC and convert for display, or your transit-time reports will be off by hours.
Tracking identifiers by mode
The fastest way to break a tracking integration is to send the wrong identifier. Most freight has several references attached to it, and each source only knows some of them. Store all of them on the shipment record, and track by the booking reference where the provider supports it, since it links the other numbers.
| Mode | Primary identifier | Typical events |
|---|---|---|
| Small parcel | Tracking number | Label created, picked up, in transit, out for delivery, delivered |
| LTL | PRO number (plus BOL number) | Picked up, at origin terminal, departed, at destination terminal, out for delivery, delivered |
| FTL | Load or booking number | Dispatched, at pickup, loaded, in transit (location), at delivery, delivered |
| Ocean FCL / LCL | Container number, bill of lading number | Received at CFS or gated in, loaded, vessel departed, arrived, discharged, released, gated out |
| Air | Air waybill number | Accepted, departed, arrived, customs released, ready for pickup, delivered |
Worked example: two shipments, one dashboard
A Chicago distributor has 2 pallets moving LTL from Chicago (60607) to Dallas (75247), and 4 pallets moving LCL from Chicago to Rotterdam. The LTL shipment is identified by its PRO number from pickup onward. The LCL shipment runs through three references in sequence: the booking reference at pickup, the house bill of lading at the consolidation warehouse, and the container number once the pallets are loaded into a 40-ft container with other shippers’ freight. If the integration only knows the container number, it shows nothing for the first several days of the move. Tracking by a reference that exists from pickup, such as the booking reference, avoids that gap.
For LCL, note the difference between the house bill of lading the forwarder issues to you and the master bill of lading the ocean carrier issues for the whole container. Carrier tracking runs on the master; your customer only ever sees the house. See LCL vs FCL for how consolidation works.
Webhooks vs polling
There are two ways tracking updates reach your system. With polling, your system calls the tracking endpoint on a schedule and asks for the latest status. With webhooks, the provider sends an event to an endpoint you host whenever something changes. Neither is better in all cases.
| Polling | Webhooks (push) | |
|---|---|---|
| Who starts the call | Your system, on a schedule | The provider, when an event occurs |
| Freshness | Only as current as your polling interval | Events arrive shortly after they are recorded |
| Infrastructure on your side | A scheduled job; no public endpoint | A secure, always-on endpoint that accepts inbound calls |
| Wasted calls | Many, since most polls return no change | Few |
| Failure mode | Rate limits if the interval is too short | Missed events if your endpoint is down and retries run out |
| Fit | Freight with few events per day (ocean, LTL) | High-volume parcel and customer-facing alerts |
Freight moves slower than parcel. An ocean container may record two or three events in a week. Polling ocean shipments at 5-minute intervals burns API calls for no new information; a 4- to 6-hour interval is enough for most planning. LTL deliveries justify a tighter interval on the day of delivery. How tracking updates reach your system through the ExFreight API is confirmed during onboarding, alongside the test environment.
If you run EDI today, the equivalent of a tracking API is the X12 214 shipment status message. The X12 transaction set list documents it, and our guide on API vs EDI for freight compares the two.
Normalized milestones across modes
Each carrier names its events differently. One LTL carrier says “Departed origin service center,” another says “In transit.” Ocean events use a separate vocabulary again. If those raw strings go straight into your dashboard, nobody can compare an air shipment to an ocean one, and late-shipment reports break whenever a provider renames a status.
The fix is a small internal milestone model, mapped once per provider:
- Booked. Booking confirmed, not yet picked up.
- Picked up. Freight is in the carrier’s or forwarder’s custody.
- Departed origin. Left the origin terminal, port or airport.
- Arrived destination. At the destination terminal, port or airport.
- Released. Customs released or available for delivery (international).
- Out for delivery. On the final-mile vehicle.
- Delivered. Signed for, with proof of delivery.
- Exception. Any hold, damage, refusal or delay, with a reason code and a text note.
Keep the raw provider event alongside your mapped milestone. When a customer disputes a delivery date, the raw event and its timestamp are the evidence. Ocean carriers are standardizing this vocabulary themselves: the DCSA Track & Trace standard defines shipment, transport and equipment events in one shared model.
Operator tips for estimated arrival data:
- Store each estimate with its timestamp. An ETA that moved three times is a signal; only the latest value hides it.
- Do not promise customers the carrier ETA. Transit times are estimates. Add a buffer for customs and final-mile appointments on international freight.
- Alert on silence, not only on exceptions. An LTL shipment with no scan for 48 hours is a problem even if no exception was posted.
- Close the loop with the booking. When a shipment is delivered, pull the proof of delivery reference into the order record so invoice matching and claims start from the same data.
For a broader view of cross-border visibility, see our article on international cargo tracking.
What ExFreight’s API covers today
Available upon request, with a test environment and assistance. Connectivity gives access to ExFreight’s online rating, booking and tracking system. See how the ExFreight freight API works
Freight API series
Frequently asked questions
Which API is the best for tracking shipments?
The best tracking API depends on what you ship. Parcel shippers usually use a multi-carrier parcel aggregator. Freight shippers get the most complete data from the forwarder or carrier that booked the move, because it holds the booking reference, the manual updates and the exceptions that automated carrier feeds miss.
What is a tracking API?
A tracking API is a connection that lets your software request, or receive, status events for a shipment by its reference number. It returns location, milestones such as pickup, departure, arrival and delivery, and an estimated arrival, so your team and customers see shipment status inside your own systems instead of a carrier portal.
Is there a courier tracking API available?
Yes. Major parcel and express carriers publish courier tracking APIs, and multi-carrier platforms combine many couriers behind one connection. They track by tracking number and return scan events. For palletized freight, LTL, ocean or air cargo, use the tracking API of the forwarder or carrier handling the shipment, since courier APIs do not cover those moves.
How can I track my delivery using the API?
Store the shipment reference returned at booking, then call the tracking endpoint with it, or receive updates pushed to your system if the provider supports it. Map the returned events to your own milestones, show them in your order record, and alert your team when a shipment records an exception or goes silent.
