Approve and ready
A website order doesn't go to a rider by itself. The store approves it, packs it, then marks it ready for pickup. Usually the store's staff do this on the store portal or the Dropoint app (they get an alert for each new order). Your system can do it too, for example when the order is packed in your warehouse system.
The stages#
stage | Meaning | Next |
|---|---|---|
awaiting_approval | Arrived, nothing charged | approve/ or reject/ |
preparing | Approved; being packed | ready/ or reject/ |
ready_blocked | Marked ready, but the store's wallet couldn't pay the fee | Dropoint retries after a top-up; or ready/ again |
sent | A real order: fee taken, rider being found | follow order.status |
rejected, cancelled, expired | Closed before it was sent; nothing charged | — |
Orders nobody handles close after 7 days (expired).
Approve#
POST https://api.dropoint.co.ke/api/integrations/v1/stores/orders/{ref}/approve/ (scope orders:write). ref is the delivery_id. Approving an approved order does nothing.
Mark ready#
POST https://api.dropoint.co.ke/api/integrations/v1/stores/orders/{ref}/ready/ (scope orders:write)
| Field | |
|---|---|
approve | true to approve and mark ready in one call. |
vehicle_type | Change the vehicle. |
confirm_fee | Accept a new price after price_changed (send the new_fee). |
Answers the delivery with stage: "sent" and an order:
{"delivery_id": "b3e2…", "stage": "sent",
"order": {"number": "DRP-20261122-35571", "status": "broadcasting", "status_label": "Finding a rider",
"delivery_fee": "240.00", "rider": null}}
When ready fails#
| Code (409) | What to do |
|---|---|
not_approved | Approve first, or send approve: true. |
price_changed | Show the store old_fee and new_fee; call again with confirm_fee. |
wallet_short | The store tops up its wallet; Dropoint then sends it by itself within 6 hours. needed is the fee. |
needs_address | The store pins the drop-off on the portal first. |
needs_price | A store on its own prices sets a price for this order (outside its price list). |
Every error answer also carries the current delivery.
Reject and cancel#
POST https://api.dropoint.co.ke/api/integrations/v1/stores/orders/{ref}/reject/withreason(scopeorders:cancel): before it's sent. Tell your customer and refund them.POST https://api.dropoint.co.ke/api/integrations/v1/stores/orders/{ref}/cancel/withreason: before it's sent nothing was charged; after it's sent it can be cancelled until pickup (a small fee may apply once a rider is assigned).