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. For API users, ExFreight’s tracking endpoint (GET /api/v2/tracking/{billing-code}) returns the shipment status; each leg with its carrier, SCAC, status and actual pickup and delivery times; a signed_by value that serves as proof of delivery; a timeline with scheduled pickup, actual pickup, original ETA, current ETA and delivery; and dated notes, which carry the 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. At minimum, 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. With ExFreight, that reference is the billing code returned at booking.
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. ExFreight’s API v2 tracking is polled: your system calls GET /api/v2/tracking/{billing-code}, and no webhooks are documented. To build the polling list, GET /api/v2/shipments returns the open and archived shipments for your token’s location, 100 per page, with an optional created_since date filter.
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.
ExFreight’s leg statuses map onto that model directly: Booked, Scheduling, Scheduled, Enroute, Delivered and Terminated, plus seven exception types (Customs, Incorrect Bill of Lading, Misrouted, Reconsignment, Refused, Weight & Inspection, Other).
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. ExFreight’s timeline returns both original_eta and current_eta, so drift against the first estimate is visible in every response.
- 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
Access: a Partner Id issued on request, plus an API token each customer retrieves in its portal settings; a separate test environment is available. 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 (with ExFreight, the billing code), then poll the tracking endpoint with it, or receive pushed updates if the provider supports them. 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.




