Delivery & tracking

Every order Kibanda delivers has one tracking picture, whatever is carrying it. The same picture drives the customer's tracking page, what the shop assistant says when a customer asks "where is it?", the messages the customer gets, and GET /v1/orders/:id/tracking.

Ways an order can travel

Method	Who reports progress	What the customer sees
`rider`	The shop's rider in WhatsApp (picked up → arrived → delivered), plus their location link	Live map, ETA, "almost there", delivery code
`courier`	The shop, or your system through the API (carrier + tracking number)	Carrier, tracking number, the carrier's own tracking page, ETA
`meetup`	The shop, or your system (a matatu, a bus parcel, a stage or agent where the customer collects)	Where to collect, when, a collection code, an "I've collected it" button
`partner`	A logistics partner through the API	Partner status, ETA, position if they share it
`pickup`	The shop (ready → collected)	"Ready to collect" and a pickup code

The tracking link

Each order has a private link, https://api.kibanda.africa/t/<token>. It is sent to the customer with the payment confirmation and again when the order is on its way. The page shows the status, a live map when there is a position, the ETA, the handover code once it's needed, and a timeline. It refreshes itself.

The link is unguessable and shows no phone numbers. Anyone holding it can see the order's items and status, so share it only with the customer.

Riders and live location

Riders work in WhatsApp. Their delivery card includes a location link: one tap on Share my location and, while the page is open, the rider's phone reports its position every few seconds (WhatsApp's own live-location sharing doesn't reach businesses). From that Kibanda:

keeps the ETA current (road distance at boda speeds, from the rider's latest position);
tells the customer when the rider is about 800 m away, once ("Your rider is almost there…");
keeps a position trail for the delivery, useful when a customer says the rider never came.

Before any position arrives, the ETA is estimated from the shop's location to the customer's pin.

Sending an order another way

From WhatsApp, the shop taps Send another way on an order and describes it in one line, e.g. "Super Metro KBX 123A to Rongai stage, around 4pm" or "Pickup Mtaani PM-88213, Kahawa agent". The assistant reads it into carrier, reference, collection point and time, and the customer gets the details and their tracking link. When it gets there the shop taps It's arrived; the customer gets a collection code and confirms with I've collected it, which completes the order.

From your system, use the API below.

Hand an order to a courier, partner or meet-up point

POST /v1/orders/:id/fulfillment

Field
`method`	Required. `courier`, `meetup` or `partner`.
`carrier`	Who carries it: `"Pickup Mtaani"`, `"G4S"`, `"Super Metro"`.
`tracking_ref`	Tracking number, waybill, or vehicle registration.
`tracking_url`	The carrier's own tracking page (https).
`meet_point`	Where the customer collects: a stage, agent, office.
`meet_location`	`{ "lat": -1.29, "lng": 36.82 }` of the collection point, for the map.
`eta`	When it's expected, ISO 8601 (`2026-10-24T16:00:00+03:00`).
`note`	Anything the customer should know (who to ask for).
`external_id`	Your or the partner's id for the shipment.

curl https://api.kibanda.africa/v1/orders/ord_9f2c…/fulfillment \
  -H "Authorization: Bearer $KIBANDA_KEY" -H "Content-Type: application/json" \
  -d '{"method":"courier","carrier":"Pickup Mtaani","tracking_ref":"PM-88213","meet_point":"Kahawa Sukari agent","eta":"2026-10-24T14:00:00+03:00"}'

The order must be confirmed (paid, or pay-on-delivery placed) and not already with a rider. The customer is told straight away. Returns the tracking object.

Report progress

POST /v1/orders/:id/fulfillment/updates

Field
`status`	`in_transit`, `arrived` (at the collection point or door), `delivered`, or `failed`.
`eta`	A new expected time. The customer is told when it changes.
`location`	`{ "lat", "lng" }` of the parcel or vehicle, shown on the map.
`note`, `tracking_url`	Updated details.

arrived sends the customer their collection code (meet-up) and the I've collected it button. delivered completes the order exactly like a rider's delivery: stock is consumed, the customer is asked whether everything arrived, and order.delivered is sent to your webhooks.

A logistics partner without a native integration can be connected this way with an API key limited to orders, or through a bridge such as Zapier.

Retrieve tracking

GET /v1/orders/:id/tracking

The tracking object

{
  "object": "tracking",
  "order": "ord_564aecc5ad9c437a9ff957ac42c6efb4",
  "method": "rider",
  "stage": "on_the_way",
  "headline": "Order #2 is on the way 🛵",
  "eta": "2026-10-23T16:11:56.000Z",
  "url": "https://api.kibanda.africa/t/8f92a4ec097243608cd873",
  "rider": { "name": "Otieno", "location": { "lat": -0.285, "lng": 36.0275 }, "seen_at": "2026-10-23T15:59:02.000Z" },
  "consignment": null,
  "timeline": [
    { "at": "2026-10-23T15:12:06.926Z", "text": "Order placed" },
    { "at": "2026-10-23T15:12:40.965Z", "text": "Paid" },
    { "at": "2026-10-23T15:21:57.784Z", "text": "Handed to the rider" },
    { "at": "2026-10-23T15:22:18.216Z", "text": "On the way" }
  ]
}

stage is one of awaiting_payment, preparing, on_the_way, arrived, ready (pickup), delivered, failed, cancelled. consignment holds carrier, tracking_ref, tracking_url, meet_point and note for courier, meet-up and partner deliveries. A rider's location is included only while it's fresh (the last five minutes).