Tracking lifecycle

Choose how to retrieve tracking data: a single-number request returns the result in its response, while a batch request creates a task whose results you retrieve separately.

Single-number trackingCopy Anchor Link

GET /v2/tracking is synchronous from the client’s perspective: the request waits for the result and returns it in the same HTTP response.

• For a container number, use company=AUTO to detect the carrier automatically.
• For a bill of lading or booking, specify the carrier’s SCAC code from the companies endpoint.
• force_update requests updated tracking data, and need_route includes route information. See the operation reference for details.

See Examples for request code.

Batch trackingCopy Anchor Link

POST /v2/tracking/batch creates a task for between 1 and 500 numbers and returns a task_id. Processing is asynchronous: the API returns a task ID without waiting for tracking results. After a short wait, pass this ID to GET /v2/tracking/batch to retrieve its state and results.

CREATED means queued, HANDLING means processing, and PROCESSED means complete. Once the task is complete, you can stop requesting its status. Use tracking requests or webhooks to obtain later shipment updates.

Task data is cached for up to 6 hours. Save the results when the task completes. See the batch tracking example for step-by-step code.

CompaniesCopy Anchor Link

GET /v2/companies lists supported carriers, their SCAC codes, and available tracking types. The data object maps each company name to { scac, cn, bl, bk }.

• Pass scac as the company query parameter.
• The cn, bl, and bk flags indicate support for containers, bills of lading, and bookings respectively. Choose a type whose flag is true.
• The response does not currently include a separate carrier availability status. A tracking result can report LINE_IS_UNDER_MAINTENANCE when work on the data source temporarily prevents tracking.

See the companies example to filter carriers by supported tracking type.

Actual and estimated timesCopy Anchor Link

After you request tracking by a container, bill of lading, or booking number, the API returns shipment data in data. The data.containers array contains containers. Each container’s events array describes movements such as loading, vessel arrival, or discharge.

The date field holds the event date, and actual indicates how to interpret it:

When every event has a date, the API returns events from newest to oldest. In that case, the first event with actual: true is the most recent actual event. If any event has no date, the API preserves the order supplied by the carrier to keep the event sequence intact.

The status_code field identifies the event type. For example:

VAT refers to a transit port and does not confirm arrival at the destination. Treat summary.pod.date as an estimated time of arrival (ETA) until an event with code VAD or CDD has actual: true. If you subscribe to tracking.eta_update, a webhook can notify you when the ETA changes. That event reports a changed estimate, not an actual arrival.

The example below reads every container and returns its latest actual event, nearest expected event with a date, and whether it has arrived at the destination port.

function readEvents(data) {
    // A bill of lading or booking can include multiple containers.
    return (data?.containers ?? []).map((container) => {
        const events = container.events ?? [];
        // Events run newest to oldest: select the first actual event.
        const lastActual = events.find((event) => event.actual === true) ?? null;
        // The nearest expected event is last among the dated expected events.
        const expected = events.filter((event) => event.actual === false && event.date);
        const nextExpected = expected.length > 0 ? expected[expected.length - 1] : null;
        const arrived = events.some((event) => event.actual === true && ["VAD", "CDD"].includes(event.status_code));
        return { number: container.number, lastActual, nextExpected, arrived };
    });
}

Managing tracked shipmentsCopy Anchor Link

GET /v2/shipments lists active (ACTIVE) and archived (ARCHIVED) tracking records. PATCH /v2/shipments/{id} adds or updates a note. DELETE /v2/shipments deletes or archives records according to their age and shipment status.

See the shipment management example for request code and credit refund rules.