When calling any HTTP POST endpoint, an idempotency key should be supplied to ensure retried requests don't duplicate the action. This is done by passing an optional unique ID for every HTTP request via the HTTP header field idempotency-key.

Example request

curl --request POST 
--url '' \
--header 'idempotency-key: {{UNIQUE_REQUEST_ID}}'


Use unique IDs

Avoid key collisions with previous requests by using unique ids, such has a database primary key or a generated UUID. Using a timestamp or short random number is discouraged.

If a request is sent again with the same idempotency-key, you will receive a HTTP 409 error code. You can have your application perform the relevant GET request for the object or send the request with a different idempotency-key

Unique external_id field

When creating objects with an external_id field (orders or customers), the value must be unique. If not, you'll get a HTTP status 409 code back with an error code conflictingExternalId and the duplicate (existing) object back.