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_url you can pay with Flutterwave's test cards (no real money), and POST /deliveries/{id}/pay works 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_exceeded when 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. 429 carries Retry-After. Details.
  • Booking input is bounded. Names, addresses, references and reasons have length limits; emails and phones are validated; weight_kg must 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}/pay for 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 /deliveries honours Idempotency-Key. A repeat with the same key returns the original delivery and its original response, with Idempotent-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.
  • reference is 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.