Skip to main content
When a request times out you cannot tell whether it reached KRA. If you simply send it again, you risk filing two invoices. An idempotency key makes the repeat safe: we recognise the request and give you the original result instead of filing again.

​
The Idempotency-Key header

Send Idempotency-Key on POST /v1/sales and POST /v1/credit-notes.
Use a value that is stable for the document: your own order or invoice id works, and so does a UUID that you store with the order. Do not generate a new random key for each retry, because that defeats the purpose. A key shorter than 8 characters is refused for the same reason.

​
What a repeat returns

Sending the same request with the same key again returns 200 with the original document, and the header:
Nothing is submitted to KRA again, so a replay is safe to send blindly. The header tells you the answer is the earlier result rather than a new one. Send the same body when you repeat a request: the original document is returned as it was filed, and changes in the new request are not applied. A document that failed is not re-driven by repeating the request. Fix the cause and call POST /v1/sales/{id}/retry.

​
Without a key

If you send no Idempotency-Key, your traderInvoiceNumber plays the same role: repeating a request with the same number returns the existing document. Using a number that already exists with a different key is a 409 with the code conflict, and the message tells you to use a new number or repeat the original request with its original key.

​
What is and is not idempotent