Skip to main content
There are two tracking views. Yours is authenticated and identifies the order. Your customer’s is a link with no credentials and no identifiers in it.

​
Your view

Requires shipments:read.
history is the shipment’s public statuses in order, each with the instant it was reached.

​
The customer’s view

Every shipment gets a tracking URL at creation. You do not create, request, or revoke it — it comes back on the create response as trackingUrl, and it is the link to give your buyer.
No Authorization header. The 43-character code in the path is the credential, so the link is bearer-like: anyone holding it can see the shipment’s progress.
The public view is deliberately thinner: coarse driver position only, and no order reference, shipment id, merchant, recipient, pickup, or destination. Responses are no-store and rate limited.

​
Location status

driverLocation is null unless a position is genuinely available. locationStatus always says why: When a position is present it carries recordedAt, ageSeconds, a stale flag, and — in your view only — an optional accuracyMetres.
Never present a STALE position as the driver’s current location. The stale flag and ageSeconds exist so your UI can say “last seen 4 minutes ago” rather than implying live movement.

​
Polling

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. For state changes, webhooks are the right mechanism; tracking is for showing a live map.