Skip to content

Live tracking

GET /shipments/:id/stream is a Server-Sent Events stream for one Shipment. Use it for a live map or a status screen. Use webhooks, not the stream, as the record of what happened.

Open the stream from your backend with your API key, then pass what you need to your own app. Never send the API key to a browser or a phone.

Terminal window
curl -N "$TUJYANE/shipments/7d0f3c52-9a4e-4f1b-8c2d-5e6a7b8c9d01/stream" \
-H "Authorization: Bearer $TUJYANE_API_KEY"
event: ping
id: 1
data: {"ts":1793696400121}
event: shipment.snapshot
id: 2
data: {"type":"shipment.snapshot","payload":{"id":"7d0f3c52-...","status":"ASSIGNED"},"ts":1793696400125}
event: partner.position
id: 3
data: {"type":"partner.position","payload":{"lat":-1.9392,"lng":30.0871,"at":"2026-11-03T08:20:05.000Z","etaSeconds":95},"ts":1793696405210}
event: shipment.picked_up
id: 4
data: {"type":"shipment.picked_up","payload":{"id":"7d0f3c52-...","status":"PICKED_UP"},"ts":1793696671480}
Frame payload When
ping None. data is { ts }. On connect, then every 25 seconds.
shipment.snapshot The Shipment Once, right after you connect.
shipment.* The Shipment Every event from the event list, as it happens.
partner.position { lat, lng, at, etaSeconds } Every 5 seconds while a partner has the Shipment and sends GPS.

Every frame except ping has data set to { type, payload, ts }. ts is the publish time in milliseconds. The id numbers count the frames of one connection only.

In partner.position, at is when Tujyane published the position. etaSeconds is the time to the pickup before PICKED_UP, and to the Recipient after it. In test mode, positions come about every 3 seconds after pickup.

The server can close a stream at any time, for example during a deploy. Reconnect with a backoff, for example after 1, 2, 5, then 10 seconds.

The stream does not replay frames and ignores Last-Event-ID. After you reconnect, the new snapshot gives the current state. Read GET /shipments/:id/events for the event types you missed.

The stream stays open after the Shipment ends. Close it when you get shipment.delivered, shipment.returned, shipment.cancelled or shipment.expired.

An open stream counts once against your rate limit, when you open it.

The stream does not open when the id is not a UUID (400), or when the Shipment is not yours in this key’s mode (404).