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.
curl -N "$TUJYANE/shipments/7d0f3c52-9a4e-4f1b-8c2d-5e6a7b8c9d01/stream" \ -H "Authorization: Bearer $TUJYANE_API_KEY"Frames
Section titled “Frames”event: pingid: 1data: {"ts":1793696400121}
event: shipment.snapshotid: 2data: {"type":"shipment.snapshot","payload":{"id":"7d0f3c52-...","status":"ASSIGNED"},"ts":1793696400125}
event: partner.positionid: 3data: {"type":"partner.position","payload":{"lat":-1.9392,"lng":30.0871,"at":"2026-11-03T08:20:05.000Z","etaSeconds":95},"ts":1793696405210}
event: shipment.picked_upid: 4data: {"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.
Reconnect
Section titled “Reconnect”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.
Close it
Section titled “Close it”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.
Errors
Section titled “Errors”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).

