How do I protect against duplicate writes in the API?

Last updated: September 13, 2024

When creating customers or subscriptions through the API, you want to ensure that you do not create duplicate resources in Orb.

Request idempotency

Orb's API supports idempotency to allow safe request retries without duplicating actions. A unique idempotency key may be provided in the Idempotency-Key header for all POST/PATCH operations.

curl --request POST \ 
     --url https://api.withorb.com/v1/subscriptions \ 
     --header 'Idempotency-Key: U9djswkfm802dq2' \ 
     --header 'Accept: application/json' \ 
     --header 'Authorization: Bearer null' \ 
     --header 'Content-Type: application/json'

Keys will expire after 48 hours, and Orb may re-execute side effects. Orb will include Idempotent-Replayed: true in the response to signal that the response is being served from a previous action. This can be taken to mean that no new side effects were executed.

Idempotency keys for GET/PUT/DELETE requests will be ignored since these requests are idempotent by default.

Learn more about request idempotency in our docs.