Idempotency

Overview

Idempotency in the context of a RESTful API means that it is safe for a client to repeatedly make the same API call with the same result every time. I.e. doing the exact POST request that will create an entity two times will only create the record once, yet returning the same response on all requests to the caller.

By default, this feature will not come into effect, unless explicitly specified by the caller by passing an idempotency_id in the namespace of the resource.

These resources support idempotency:

• address
• bank_account
• bank_deposit
• bank_opening_balance
• bank_reconciliation
• bank_transfer
• business_exchange_rate
• contact
• contact_allocation
• contact_opening_balance
• contact_payment
• contact_person
• hosted_artefact_payment_setting
• journal
• journal_code
• ledger_account
• ledger_account_opening_balance
• migration_tax_return
• opening_balance_journal
• other_payment
• product
• product_sales_price_type
• purchase_corrective_invoice
• purchase_credit_note
• purchase_invoice
• purchase_quick_entry
• sales_corrective_invoice
• sales_credit_note
• sales_estimate
• sales_invoice
• sales_quick_entry
• sales_quote
• service
• service_rate_type
• stock_item
• stock_movement
• tax_profile

Making an Idempotent Request

Pass a random 32 character hyphenless GUID in the namespace of the entity to enable idempotency, as shown in the example below:

POST /address
Content-Type: application/json

{
  "address": {
    "idempotency_id": "c3a8adaa26daf36e02f3c672b69e3323",
    ...
  }
}

The random GUID must be generated by the client. For the next 7 days, a repetition of this very same request will return the exact same result as the first request and not create a new object.

When you re-use an idempotency id on a different resource, an error is returned:

[
  {
    "$severity": "error",
    "$dataCode": "IdempotencyResourceMismatch",
    "$message": "Entity type mismatch",
    "$source": ""
  }
]

Don’t use this feature for GET and DELETE request, as they are idempotent by definition.

Idempotency works for POST as well as PUT requests.

By its HTTP definition, PUT requests are idempotent. However, it is the nature of accounting that the modification of an object can lead to further actions. E.g. when a line item is added to a sales invoice, it will cause a new transaction to be recorded. Other side effects like the sending of an email can also be triggered. To avoid such behaviour, a client can use the idempotency feature on update calls.