The API supports Idempotency. This allow you to safely retry an operation without performing the action twice. This might be useful when something in the process goes wrong.

Lets say you are sending an invoice over the Peppol network. Something goes wrong and the action is not executed. Meaning we did not store the Idempotency token either. This allows you to retry the action. Until the action is successful, since the Idempotency token was not used before.

An idempotency token is a unique key created by the Client which the server uses to recognize subsequent retries of the same request. Allowing us to make sure its unique.

The key is only stored on the server side when the action is successfully executed.

Usage
If you want to use the Idempotency token in the API you can by simply adding it to the header of the request.

Header field name	Header field value	Content	Mandatory
Idempotency-Key	"Unique value created by the client for each new document"	AlphaNumberic	No

Result after Posting with IdemPotentcy-Key:

Result	Code	Feedback
Success	200	Billit OrderID
Error	409	Error Code: "Idempotent token already exists"
Error	422	Error Code: "Unprocessable entity"

How It Works

Token Generation: The client generates a unique idempotency token for each operation.
Initial Request: The client includes the idempotency token in the header of the API request.
Server Recognition: The server checks if the token has been used before. If not, it processes the request and stores the token.
Retry Attempts: If the request fails and the client retries, it uses the same token. Since the server recognizes the token, it ensures that the operation is not performed more than once.
Token Storage: The idempotency token is stored on the server side only after a successful operation. If the operation fails and the token is not stored, the client can safely retry without risking duplicate actions.

Example when Success

When Posting the document:

The Idenpotency-Key is in the header and is generated by the application of the sender. For each new document, you include a new key in the header.

When this Idempotency-Key is not yet successfully processed by Billit, then the process can continue. The Billit feedback will be status 200 with an ID:

Errors

1) Token already exists:

When the idempotency token is already successfully processed by Billit, error 409 is returned.
This also applies to documents in progress state at Billit, so it will also work with concurrent requests ((introduced on 17/06/2026).

2) Unprocessable entity - error 422 (introduced on 17/06/2026)

This key is used linked to another document number
So this is an error due to the Sender/Requester

Issues managed by Billit

When errors occurs on the Billit level, then idempotency stated will be handled correctly. This also applies to process crashes, unavailable components.