Idempotency
Which requests are safe to send again, and how.
Networks fail. A request can time out after it worked. Placing an order and reporting a complaint carry a reference of your own, so sending them again is safe: to "did it work?", the answer is "send it again and see". Every other request is listed below with what sending it again does.
Orders: external_ref
Every order carries your own reference, external_ref (1 to 100 characters, unique among your orders):
- The same
external_refwith the samequote_idreturns the order it already made, with200 OKinstead of201 Created. Nothing is ordered twice, even when two copies arrive at once. - The same
external_refwith a different quote is refused:409 external_ref_used. A new order needs a new reference. - A quote orders once: a second order from it is
409 quote_used.
Use your own order id as external_ref, and find an order by it with GET /v1/orders?external_ref=....
Complaints: external_ref
A complaint's external_ref (your ticket number, say) works the same way: sent again, it returns the complaint already recorded with 200 OK. See complaints.
Everything else
- Reading (
GET) never changes anything. - A quote is a new price each time: ask again freely.
- Cancelling a cancelled order returns it unchanged.
- Cancelling a cancelled shipment returns the order unchanged.
- Sending the same change to a webhook endpoint (
PATCH) twice leaves it as the first did. Deleting one again answers404: it is already gone. - Sending a delivery again (
resend) while it is still queued queues it once.
Not safe to send twice
Registering a webhook endpoint (POST /v1/webhook-endpoints) has no reference of yours: sending it twice makes two endpoints, each with its own secret, and each event goes to both. After a timeout, look in GET /v1/webhook-endpoints before you register it again.
Webhooks
Kiuki delivers each event at least once, so the same event can reach you twice. Each has an id (also in the Kiuki-Event-Id header): handle each id once.