Skip to main content

​
Read live tracking

The response carries the shipment’s lifecycleState, a locationStatus, an optional driverLocation, and a recommendedRefreshSeconds.

​
Poll at the interval the server asks for

recommendedRefreshSeconds is between 5 and 60 and reflects what is actually knowable right now — a shipment waiting for a driver has nothing to report as often as one in motion.
Honour recommendedRefreshSeconds instead of choosing your own interval. Polling faster does not produce fresher data, and webhooks are the better mechanism for state changes.

​
Location status

driverLocation is null unless a location is genuinely available. locationStatus says why: When a location is present it carries recordedAt, ageSeconds, an optional accuracyMetres, and a stale flag.
Never present a STALE location as the driver’s current position. The stale flag and ageSeconds exist so your UI can say “last seen 4 minutes ago” rather than implying live movement.
A tracking link lets a recipient follow a shipment without credentials.
expiresIn is an ISO 8601 duration and defaults to PT24H. Choose the shortest window that covers the delivery. Revocation is a conditional request — it requires the If-Match ETag of the link.
Omitting If-Match is rejected with 428 Precondition Required; a stale one with 412. See Idempotency and ETags.
A public link exposes shipment progress to anyone holding the URL. Revoke it as soon as the delivery completes if the link’s natural expiry is longer than you need.