Cargoplot APICargoplot API
API docs
OpenAPI spec

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.

KeyTransport modeTimeline
seaSea freightOne entry per container, each with its own events
airAir freightOne overall status and one list of events for the shipment
railRail freightA status only: no tracking source covers rail yet
roadRoad freightA 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

bash
curl -H 'X-Cargoplot-Key: <token>' \
  'https://api.cargoplot.com/v1/shipment/C2AE-XEE1/tracking'

Sea response

json
{
  "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.

json
{
  "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:

json
{
  "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.statusWhy there are no events
AIR_TRACKING_STATUS_AWAITING_WAYBILLThe shipment has no air waybill yet. Tracking can start once one is recorded
AIR_TRACKING_STATUS_AWAITING_AIRLINE_DATAThe 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_UNAVAILABLEThe 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.