Tracking shipments

Once a booking has been lodged with a courier, you can read its progress with one GET request. Pass the Transdirect booking id, the courier’s consignment number (connote), or a courier tracking reference.

curl https://api.transdirect.com.au/api/v5/tracking/623630

Two tracking endpoints

Endpoint	API key	Response	Use it for
GET /api/v5/tracking/{reference}	Not needed	A summary (state, headline, summary) plus per-item events	Showing progress to a customer, or any server-side status check
GET /api/v5/bookings/track/{id}	Required	A compact object keyed by connote, holding a list of events	Integrations that want only the event list

Both read the same stored tracking data. The public endpoint gives you more: an overall state, wording you can show to a customer, and an ISO 8601 timestamp on each event whose time is known.

Where tracking comes from

Transdirect collects scans from each courier and stores them against the booking. When you request tracking for a courier that Transdirect can query directly, the request also asks the courier for new scans before it answers.

A few things follow from that:

• A new booking has no scans. Between confirmation and the courier’s first scan, the public endpoint returns state: "pending" (“Booked, awaiting courier scan”) and an empty event list. The first scan normally appears after pickup.
• Draft quotes and demo bookings never get scans. A quote that was never confirmed was never sent to a courier. A demo booking gets a DEMO- connote but is never lodged, so it stays pending.
• Events can arrive late or out of order. Couriers publish scans in batches. Sort events by occurredAt (public endpoint) rather than relying on array order.

Tracking states

The public endpoint’s state summarises the whole shipment:

state	Meaning
pending	Booked, waiting for the courier’s first scan
picked_up	The courier has collected the shipment
in_transit	Moving through the courier network
out_for_delivery	On board for delivery
delivered	Delivered
attention	The courier reported a problem, such as a futile delivery, an address to check, or damage. helpRecommended is true.
not_found	Nothing matched the reference (returned with HTTP 404)

Each event also carries a stage: picked_up, in_transit, out_for_delivery, delivered, exception or unknown (the public endpoint can also return pending). On the keyed endpoint, the same value is returned as track_status.

How often to poll

Transdirect does not send webhooks or push notifications for tracking, so you poll. Some guidance:

• Start polling after pickup, not after confirmation. Before the pickup date there is nothing to see.
• Every one to two hours is plenty for an in-transit shipment. Couriers rarely publish scans more often than that, and each request can trigger a live lookup with the courier.
• Stop when the shipment is delivered. If it stays attention, show the summary to your customer and contact Transdirect support.
• Store the latest state and compare on each poll, rather than re-processing every event.

Keyed requests count towards your API key’s limit of 600 requests a minute. The public endpoint does not need a key.

Check status without tracking

To see whether a booking is confirmed, paid or cancelled, read status_code from GET /api/v5/bookings/{id}. Tracking describes where the parcel is, not the state of the booking.

Showing tracking to your customers

The public endpoint needs no key, so its response is safe to pass to your own front end through your server. Display headline as the status line and summary as the explanation, then list items[].events with dateText and description.

Related

• Track a booking: full request and response reference for both endpoints
• Booking lifecycle: booking statuses from quote to delivery
• Get a label: the connote appears on the label once the courier has confirmed the booking