Shipment tracking
Use GET /v1/shipment/{shipment}/tracking to read a shipment's movement
timeline. The path accepts either the Cargoplot reference or the numeric
shipment id.
Each transport mode describes its journey differently, so the timeline is nested under a key naming the shipment's transport mode. A response carries exactly one of them, decided by the shipment itself.
| Key | Transport mode | Timeline |
|---|---|---|
sea | Sea freight | One entry per container, each with its own events |
air | Air freight | One overall status and one list of events for the shipment |
rail | Rail freight | A status only: no tracking source covers rail yet |
road | Road freight | A status only: no tracking source covers road yet |
etd and eta sit at the top level, beside the mode key, because they mean the
same thing whichever mode it is.
Request
curl -H 'X-Cargoplot-Key: <token>' \
'https://api.cargoplot.com/v1/shipment/C2AE-XEE1/tracking'
Sea response
{
"etd": "2026-09-05",
"eta": "2026-09-08",
"sea": {
"containers": [
{
"container_number": "MSKU1234567",
"container_type": "CONTAINER_TYPE_40_HIGH_CUBE",
"status": "CONTAINER_TRACKING_STATUS_SAILING",
"events": [
{
"type": "SEA_TRACKING_EVENT_TYPE_DEPARTED",
"state": "TRACKING_EVENT_STATE_ACTUAL",
"timestamp": "2026-09-05T10:00:00Z",
"location": {
"un_locode": "SGSIN",
"name": "Singapore"
},
"vessel": {
"name": "Example Vessel",
"voyage": "001W"
}
}
]
}
]
}
}
A sea event names its seaport by UN/LOCODE, and carries the vessel and voyage where they are known.
Air response
Air cargo has no container to hang milestones on, so an air timeline sits at the
shipment level: one status for the whole consignment, and one list of events.
{
"etd": "2026-09-05",
"eta": "2026-09-08",
"air": {
"status": "AIR_TRACKING_STATUS_IN_TRANSIT",
"events": [
{
"type": "AIR_TRACKING_EVENT_TYPE_DEPARTED",
"state": "TRACKING_EVENT_STATE_ACTUAL",
"timestamp": "2026-09-05T11:00:00Z",
"location": {
"iata": "SIN",
"name": "Singapore Changi"
},
"flight": {
"number": "KL0887",
"airline": "KLM"
},
"cargo": {
"pieces": 3,
"weight_kg": 412.5,
"volume_cbm": 1.75
}
}
]
}
}
An air event names its airport by IATA code and carries the flight it happened on. Milestones that did not happen in the air — the handover from the shipper, and the final delivery — carry no flight at all.
airline is the carrier on the waybill, and is itself optional — an event can
carry a flight with a number and no airline. Where a consignment flew
partly with another carrier, every event still names the same one, so read it as
the shipment's airline rather than the leg's.
Air status
air.status describes the consignment as a whole. Unlike a container's
status, it is not derived from the event list, so it can say more than the
events do.
Cargo figures, and when they are absent
cargo says how much of the consignment a milestone covered, which is what
tells the legs of a split movement apart when two of them would otherwise look
identical. Each measure names its unit, and a measure that was not reported is
absent rather than 0.
cargo is omitted entirely when more than one of your shipments shares the same air waybill —
the figures on a shared waybill cover everything on it rather than your consignment alone.
The milestones keep the same flight facts — the aircraft's movements are the same for every consignment on board. One consequence to know about, though: two legs that differ only in their cargo figures become indistinguishable once those figures are gone, and are returned as a single milestone rather than two identical ones. So on a shared waybill you cannot tell the legs of a split movement apart, and the event list can be shorter than the number of legs flown.
On a consolidated master air waybill where yours is the only consignment booked through Cargoplot, cargo is
returned, and its figures still describe the whole waybill — including goods
belonging to parties we have no record of. Treat cargo as "how much moved on
this milestone", not "how much of mine moved", unless you know the waybill
carries your consignment alone.
Rail and road response
No tracking source covers rail or road freight yet, so these shipments carry no
milestones. They answer with their mode key and a status that says so, beside
the shipment's own etd and eta:
{
"etd": "2026-09-27",
"eta": "2026-10-22",
"rail": {
"status": "RAIL_TRACKING_STATUS_UNAVAILABLE"
}
}
A road shipment answers the same way under road, with
ROAD_TRACKING_STATUS_UNAVAILABLE. Read etd and eta for the plan. Neither
key has an events list for now; treat one that appears later as you would a
new field.
The vocabularies
Every value of SEA_TRACKING_EVENT_TYPE_*, AIR_TRACKING_EVENT_TYPE_*,
CONTAINER_TRACKING_STATUS_*, AIR_TRACKING_STATUS_*,
RAIL_TRACKING_STATUS_*, ROAD_TRACKING_STATUS_* and
TRACKING_EVENT_STATE_* is listed with its meaning in the
glossary, along with the
four-letter carrier codes such as GTIN, DEPA and DISC that the same
milestones carry in carrier portals and EDI messages. This endpoint returns the
readable names, never those codes.
Departure and arrival appear in both the sea and the air vocabulary. The two sets are separate, so a switch over one is unaffected as the other grows — but either can gain a member, so handle an unrecognised value rather than assuming your switch is exhaustive. See versioning.
Fields and formats
etd, eta and discharge_date are ISO 8601 calendar dates — "2026-09-05". A date that is not known is absent from the response rather than
present and empty. Event, gate-out and empty-return timestamps are instants, so
they carry a time and use RFC 3339.
Events are ordered from oldest to newest. state tells you whether an event is
TRACKING_EVENT_STATE_EXPECTED or TRACKING_EVENT_STATE_ACTUAL. A container's
status follows its latest actual event, so an expected event does not move the
current status forward.
Location, vessel, voyage, flight, cargo, discharge, gate-out and empty-return details are included when known. Treat absent optional fields as unknown.
When tracking is not available yet
A shipment answers with its mode key even before any movement data exists. On
sea, a known container stays in containers with events: []; on air, events
is []. An empty event list is a valid response, not a reason to discard the
shipment, and etd and eta are still returned.
Test events for emptiness to detect "nothing yet", not a particular
air.status. When the list is empty, the status usually says why:
air.status | Why there are no events |
|---|---|
AIR_TRACKING_STATUS_AWAITING_WAYBILL | The shipment has no air waybill yet. Tracking can start once one is recorded |
AIR_TRACKING_STATUS_AWAITING_AIRLINE_DATA | The shipment has a valid waybill and no airline data has reached us yet. Usually the pre-departure case; one still here well after its etd is worth raising with Cargoplot |
AIR_TRACKING_STATUS_UNAVAILABLE | The waybill is not being tracked as things stand, for example because it is not written as NNN-NNNNNNNN or NNNNNNNNNNN, the shipment is on hold, completed, cancelled or on or past its ETA date, or the airline has no data for it |
Any other status, AIR_TRACKING_STATUS_UNSPECIFIED included, can also come with
an empty list while the airline's first data is on its way. Most of these
states can change when the shipment does — a corrected waybill, a later ETA or
a shipment taken off hold starts tracking — so keep polling rather than
treating a status as final.
The first actual milestone is usually
AIR_TRACKING_EVENT_TYPE_RECEIVED_FROM_SHIPPER, reported when the cargo is
handed over at the origin airport. Until the airline reports the cargo, expect
few or no events, even when etd and eta are filled.
Rail and road shipments answer with a status only, as described
above. The endpoint returns 400 when the shipment is
transported by express or has no transport mode recorded, and 404 when no
matching shipment is visible to your account. See
errors for the common error response shapes.