Sending orders
Send an order#
POST https://api.dropoint.co.ke/api/integrations/v1/stores/orders/ (scope orders:write). Send it when the customer has placed (and, if you take payment online, paid) the order.
| Field | ||
|---|---|---|
recipient_name, recipient_phone | required | The customer. A Kenyan mobile number. |
quote_id | recommended | From Prices at checkout: keeps the price and the drop-off pin. |
lat, lng / address / area | The drop-off, when there's no quote_id. | |
instructions | Directions for the rider (gate, floor…). | |
items | [{"name": "Ankara dress", "quantity": 2}], or item as text. | |
size, fragile | Parcel size, and whether it's fragile. | |
reference | recommended | Your order number. Comes back in every answer and webhook. |
order_url | A link to the order in your shop's admin. | |
order_total | What the customer paid you, for the store's records. | |
paid_online | true when the customer already paid you. Stores can approve these automatically. | |
cod_amount | Money the rider collects from the customer by M-Pesa at the door; it reaches the store's wallet, less Dropoint's share. | |
fee_paid_by | store (default) or recipient (the customer pays the delivery fee at the door). | |
email, channel | The customer's email; your platform (e.g. woocommerce). | |
branch_id, vehicle_type | The shop it leaves from; the vehicle. | |
delivery_fee | Stores on their own prices only: a price you set for this order. | |
start_at | awaiting_approval (default), preparing (already approved), ready (send a rider now), saved (keep it on the portal to send in a pool). |
The answer (201) is the delivery:
{
"delivery_id": "b3e2…", "reference": "WC-1041", "channel": "woocommerce",
"stage": "awaiting_approval", "stage_label": "Waiting for approval", "status": "awaiting_approval",
"customer": {"name": "Achieng Otieno", "phone": "254712555101", "email": null},
"drop_off": {"address": "…", "area": "Kilimani", "point": {"lat": -1.29, "lng": 36.78}, "needs_pin": false},
"items": "2 × Ankara dress", "order_total": "6450.00", "paid_online": true,
"fee": {"amount": "240.00", "priced_by": "dropoint", "held_until": "2026-11-24T13:20:00+03:00", "final": false},
"tracking_url": "https://api.dropoint.co.ke/api/v1/track/…/", "order": null, "test": false
}
The tracking_url works from the start: before a rider is found it says the store is preparing the order.
Never twice: Idempotency-Key#
Send your order number as the Idempotency-Key header. If a network error makes you send the order again, Dropoint gives back the same delivery (200, header Idempotent-Replayed: true) instead of making a second one, even if both copies arrive at the same moment.
POST /api/integrations/v1/stores/orders/
Idempotency-Key: WC-1041
When the address isn't on the map#
If Dropoint can't place the address, the order still arrives (drop_off.needs_pin: true) and the store pins it on the portal before marking it ready. Send lat/lng or a quote_id to avoid this.
Errors#
| Code | Meaning |
|---|---|
invalid_order (400) | A field is wrong; errors lists what. |
invalid_quote (400) | The quote_id isn't one of this store's prices. |
in_progress (409) | The same Idempotency-Key is being placed right now. Retry in a moment. |
own_prices_off, own_prices_not_ready, price_too_low | A delivery_fee was sent but the store isn't on its own prices, Dropoint hasn't set its share yet, or the price is below the fair minimum (lowest is given). |