Skip to content
KiukiPlatform
Documentation

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_ref with the same quote_id returns the order it already made, with 200 OK instead of 201 Created. Nothing is ordered twice, even when two copies arrive at once.
  • The same external_ref with 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 answers 404: 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.