API changelog
Changes in v2 and migration from v1
2.1
The current API version. See the API reference for operations, parameters, and response formats.
2.0
The first major update after v1 redesigned tracking requests and shipment management, and added document-based tracking and webhooks.
| Change | What v2 introduced |
|---|---|
| Endpoints and methods | Requests moved to /v2/tracking, /v2/tracking/batch, and /v2/shipments. Deletion uses DELETE. See the migration table below for the full mapping. |
| Document-based tracking | Track by bill of lading (bl) or booking (bk) number, as well as by container number. |
| Request parameters | value and type replace container_number. For example, container_number=MSDU8368827 becomes value=MSDU8368827&type=container. |
| Batch requests | The tracked_items array contains objects with company and track_number: { value, type }. Each task accepts up to 500 numbers of different types. |
| Response format | Container data uses a consistent data.containers array. Responses also include related numbers in data.references, tracking details in data.tracking_metadata, and original parameters in request. |
| Shipment management | Paginated lists, notes, and operations to archive or delete tracked shipments. |
| Supported companies | GET /v2/companies returns carrier SCAC codes and supported tracking types. |
| Webhooks | Receive tracking events as updates become available. See Webhooks. |
Continue to pass your API key in the api_key query parameter. Responses include success, status, status_description, and data where those fields are defined for the operation.
Migrating from v1
Do not switch a production client to v2 without validating responses and error handling. You can migrate incrementally.
| v1 | v2 |
|---|---|
GET /v1/container | GET /v2/tracking |
POST /v1/containers | POST /v2/tracking/batch |
GET /v1/containers | GET /v2/tracking/batch |
GET /v1/apikey | GET /v2/apikey |
GET /v1/subscriptions/get | GET /v2/shipments |
POST /v1/subscriptions/remove | DELETE /v2/shipments |
| none | GET /v2/companies |
| none | webhooks: /v2/webhooks, /v2/webhook-event-types, /v2/webhook-notifications |
Replace container_number with value and pass a required type: container, bl, or bk.
GET /v1/container?api_key=YOUR_TOKEN&company=AUTO&container_number=MSDU8368827
GET /v2/tracking?api_key=YOUR_TOKEN&company=AUTO&value=MSDU8368827&type=containerBills of lading and bookings require the carrier’s SCAC code — check the cn, bl, and bk flags with GET /v2/companies.
Processing is asynchronous: the API returns a task ID without waiting for tracking results. The response to POST /v2/tracking/batch includes a task_id. Use it with GET /v2/tracking/batch to retrieve the results. Task data is cached for up to 6 hours.
Replace containers containing container_number with tracked_items containing track_number. A request accepts up to 500 numbers, and may mix containers, bills of lading, and bookings.
{
"tracked_items": [
{
"company": "AUTO",
"track_number": { "value": "MSDU8368827", "type": "container" }
},
{
"company": "COSU",
"track_number": { "value": "ABCD1234567890", "type": "bl" }
}
]
}v1 returns a single container in data.container. v2 always returns containers in data.containers, including a one-item array for a single container. Do not read the first element without checking the array.
v2 also adds:
data.referencesfor related shipment numbers;request, an echo of the requestedtrack_numberandcompany;data.tracking_metadata, which may benullbefore a shipment is created.
Keep handling status separately from the HTTP status: HTTP 200 does not guarantee status: "OK". See Errors for all codes.
GET /v1/subscriptions/get returned the full list. GET /v2/shipments uses pagination: pass page, limit (up to 500), and optionally status. Tracked shipments are in data.data, with data.meta and data.links.
For deletion, replace POST /v1/subscriptions/remove with subscriptionIds by DELETE /v2/shipments with shipmentIds.
Deletion and credit refunds depend on when the tracking record was created and its shipment status. Review the shipment management example and the delete operation.
Webhooks are new in v2. Create a subscription, store its signing secret, and receive events at your callback_url. Verify the HMAC signature and deduplicate by x-timetocargo-event-id. See Webhooks.
v1
v1 is for existing integrations only. Documentation: Swagger UI.
It supports containers only: GET /v1/container, batch POST/GET /v1/containers, GET /v1/apikey, and GET /v1/subscriptions/get / POST /v1/subscriptions/remove. Do not use v1 for new work.
Last updated on