TimeToCargo
Examples

Shipments

List tracked shipments, update notes, and archive or delete records

Use these requests to manage tracked shipments in your account: retrieve a list, add or update a note, and archive or delete a record.

  1. GET /v2/shipments returns a paginated list of tracked shipments. Records on the current page are in data.data. The data.meta object contains the current page number, page size, total record count, and total page count. The data.links object provides links to the current, first, last, previous, and next pages. Set status=ACTIVE or status=ARCHIVED to filter the list. The limit parameter sets the page size, up to 500 records.
  2. PATCH /v2/shipments/{id} adds or updates a note of up to 40 characters. Send the note in the note field of the JSON request body: { "note": "..." }. To remove the note, send an empty string: { "note": "" }.
  3. DELETE /v2/shipments with { "shipmentIds": ["..."] } deletes or archives the selected records. The response lists deleted IDs in data.deleted and archived IDs in data.archived.

An active record created no more than 72 hours ago is deleted with a refund of one tracking credit if shipment_status is not IN_TRANSIT (for example, DELIVERED, UNKNOWN, or STUCK). Records with IN_TRANSIT and active records older than 72 hours are archived without a refund. Archived records are deleted without a refund. See the delete operation for the rules.

Request examples

First retrieve the list and choose the id of a tracked shipment. Replace aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee with that ID. The following requests update its note, then delete or archive the selected record.

// List records, update a note, and delete or archive the selected record.
// Set the API URL and request parameters.
const API_BASE = "https://tracking.timetocargo.com/v2";
const shipmentId = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee";

// 1. Retrieve a page of tracked shipments and choose an ID.
const list = await fetch(`${API_BASE}/shipments?api_key=YOUR_TOKEN&page=1&limit=50&status=ACTIVE`, {
    headers: { Accept: "application/json" },
});
if (!list.ok) throw new Error(`HTTP ${list.status}`);
const listBody = await list.json();
if (listBody.status !== "OK") throw new Error(listBody.status_description ?? listBody.status);
console.log(listBody.data.data?.map((row) => ({ id: row.id, note: row.note, track_number: row.track_number })));

// 2. Add or update the selected record’s note.
const note = await fetch(`${API_BASE}/shipments/${shipmentId}?api_key=YOUR_TOKEN`, {
    method: "PATCH",
    headers: { Accept: "application/json", "Content-Type": "application/json" },
    body: JSON.stringify({ note: "Order 4521" }),
});
if (!note.ok) throw new Error(`HTTP ${note.status}`);
const noteBody = await note.json();
if (noteBody.status !== "OK") throw new Error(noteBody.status_description ?? noteBody.status);

// 3. Delete or archive this record according to the API rules.
const removed = await fetch(`${API_BASE}/shipments?api_key=YOUR_TOKEN`, {
    method: "DELETE",
    headers: { Accept: "application/json", "Content-Type": "application/json" },
    body: JSON.stringify({ shipmentIds: [shipmentId] }),
});
if (!removed.ok) throw new Error(`HTTP ${removed.status}`);
const removedBody = await removed.json();
if (removedBody.status !== "OK") throw new Error(removedBody.status_description ?? removedBody.status);
console.log(removedBody.data.deleted, removedBody.data.archived);

For HTTP status and API result handling, see Error handling.

Last updated on

Batch tracking

Submit a task for multiple numbers and retrieve its results

Companies

Find supported carriers, their SCAC codes, and tracking types

On this page

Request examples