Tools
Changelog
Changes to the v1 API, newest first. Additive changes — a new field, a new status — ship without notice, so write clients that ignore fields they do not recognise.
Live API on Dispatch Pro
- Live keys need the Dispatch Pro plan. Test keys stay free on every plan. A free company can no longer create a live key, and a live key whose company is not on Pro (never subscribed, or the plan lapsed) is refused on every call with
402 plan_required. Going live. - Test payments run on Flutterwave test mode. Online test bookings now return a
checkout_urlyou can pay with Flutterwave's test cards (no real money), andPOST /deliveries/{id}/payworks for test deliveries. Test bookings are limited to 50 per company per 24 hours (429 test_limit_reached).
Rate limits, field limits, one price per delivery
- A monthly booking allowance. 50 live API bookings a month on the free plan, 10,000 on Pro, with the count in response headers and a
402 quota_exceededwhen it runs out. Test mode is unlimited and the platform fee is unchanged. Details. - Rate limits are real now. Per company, per environment, per minute: 240 reads, 120 quotes, 60 bookings, 20 payment links.
429carriesRetry-After. Details. - Booking input is bounded. Names, addresses, references and reasons have length limits; emails and phones are validated;
weight_kgmust be a number from 0 to 1000. Over-long or malformed input is refused rather than trimmed, and the response names every field that failed. - One price per delivery. The amount a delivery is charged is now fixed at booking, so a payment link made tomorrow charges what you were quoted today rather than recomputing it.
Hosted checkout links
- An online booking now returns
payment.checkout_url, a hosted Flutterwave page created on our side with the amount, reference and split already on it. Redirect your customer to it and you are done — no publishable key, no checkout widget, no Flutterwave credentials of your own. How payment works. - New endpoint
POST /deliveries/{id}/payfor a fresh link when the first one goes stale, charging the amount the booking quoted rather than today's price. Reference.
Idempotent bookings, and reference is now stored
POST /deliverieshonoursIdempotency-Key. A repeat with the same key returns the original delivery and its original response, withIdempotent-Replay: true. Previously the header was accepted and ignored, so a retried booking created a second delivery. How to use it.- New error code
idempotency_conflict(409), when one key is reused for a different request body. referenceis persisted. Your own identifier was echoed back at booking and then forgotten; it is now stored and returned by retrieve and list.- These docs. The full reference now lives at its own address rather than inside the dashboard.
The delivery API, and test mode
- v1 launched with five endpoints: quote, book, retrieve, list and cancel.
- Test and live keys. A test key runs the same code path at the same prices but charges nobody and pages no one, and can never read live data.
- Keys are hashed. Shown once at creation, stored only as a SHA-256 hash, revoked rather than deleted.
- Server-side pricing. Every booking is re-priced by the same function behind the booking page; amounts in the request body are ignored.
Known gaps#
Not promises with dates, just an honest list of what people ask for and do not yet have: webhooks for status changes, scheduled bookings, filtering on the list endpoint, published rate limits, and an npm package for the SDK.