API reference

Retrieve a delivery

One delivery, by id or tracking code — both work, because an integrator usually stores whichever their own system saw first.

GET/api/v1/dispatch/deliveries/{id}

Path parameter#

idstringrequired
Either the delivery id (a UUID) or its tracking_code (e.g. DCAB12CD34). Tracking codes are matched case-sensitively, as returned.

Scoped to your key

The lookup is scoped to your company and your key's environment. A test key asking for a live delivery gets 404, not a redacted record — a sandbox must never be able to surface a real customer's address.

Request#

curl "https://api.rheochat.com/api/v1/dispatch/deliveries/DCAB12CD34" \
  -H "Authorization: Bearer rk_test_YOUR_KEY"

Response#

200
{
  "id": "0f9a1c8e-6b2a-4f0d-9b7e-3c5a1d2e4f60",
  "tracking_code": "DCAB12CD34",
  "environment": "live",
  "livemode": true,
  "status": "in_transit",
  "payment_status": "paid",
  "reference": "your-order-4821",
  "currency": "NGN",
  "delivery_fee": 1800,
  "platform_fee": 200,
  "rider_payout": 1400,
  "distance_km": 4.62,
  "eta_minutes": 26,
  "pickup": {
    "name": "Mama Put Kitchen",
    "phone": "+2348012345678",
    "address": "12 Ahmadu Bello Way, Jos",
    "lat": 9.8965,
    "lng": 8.8583
  },
  "dropoff": {
    "name": "Amaka O.",
    "phone": "+2348098765432",
    "address": "5 Rwang Pam St, Jos",
    "lat": 9.9285,
    "lng": 8.8921
  },
  "item_description": "Jollof rice x2",
  "created_at": "2026-09-20T09:14:02.118Z",
  "events": [
    { "status": "pending",    "note": "Booking created via API",     "created_at": "2026-09-20T09:14:02.118Z" },
    { "status": "assigned",   "note": "Assigned to Musa I.",         "created_at": "2026-09-20T09:14:47.902Z" },
    { "status": "picked_up",  "note": "Parcel collected",            "created_at": "2026-09-20T09:31:08.310Z" },
    { "status": "in_transit", "note": "On the way to the drop-off",  "created_at": "2026-09-20T09:31:44.007Z" }
  ],
  "request_id": "b6d3f7c2-…"
}

Fields

FieldTypeMeaning
statusstringWhere the parcel is. See the lifecycle.
payment_statusstringWhere the money is: cod, unpaid, paid, failed, refunded.
referencestring | nullYour own identifier, as sent at booking.
pickupobjectName, phone, address and coordinates of the collection point.
dropoffobjectThe same for the destination.
item_descriptionstring | nullWhat is being carried.
created_atstringISO 8601, UTC.
eventsarrayEvery status change, oldest first, each with a human note and a timestamp.

Rider identity and live position are not returned by this endpoint. The public tracking page for a tracking_code shows them to the recipient, which is the person that information is for.

Errors#

StatusCodeWhen
401invalid_api_keyBad or revoked key.
404not_foundNo delivery with that id or tracking code — in this environment, for this company. Check your key's environment before assuming it is gone.

Polling#

There are no webhooks yet, so this endpoint is how you follow a delivery. Poll roughly every 30 seconds while a delivery is in flight, every 60 while it waits for a rider, and stop once it reaches delivered or cancelled. See Following a delivery.