Dropoint for developers

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_phonerequiredThe customer. A Kenyan mobile number.
quote_idrecommendedFrom Prices at checkout: keeps the price and the drop-off pin.
lat, lng / address / areaThe drop-off, when there's no quote_id.
instructionsDirections for the rider (gate, floor…).
items[{"name": "Ankara dress", "quantity": 2}], or item as text.
size, fragileParcel size, and whether it's fragile.
referencerecommendedYour order number. Comes back in every answer and webhook.
order_urlA link to the order in your shop's admin.
order_totalWhat the customer paid you, for the store's records.
paid_onlinetrue when the customer already paid you. Stores can approve these automatically.
cod_amountMoney the rider collects from the customer by M-Pesa at the door; it reaches the store's wallet, less Dropoint's share.
fee_paid_bystore (default) or recipient (the customer pays the delivery fee at the door).
email, channelThe customer's email; your platform (e.g. woocommerce).
branch_id, vehicle_typeThe shop it leaves from; the vehicle.
delivery_feeStores on their own prices only: a price you set for this order.
start_atawaiting_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#

CodeMeaning
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_lowA 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).
Base address: https://api.dropoint.co.ke/api/integrations/v1 · Questions? Use Support on the store portal.