Idempotent requests

Use an Idempotency-Key to prevent rapid retries from repeating supported write operations.

Send an idempotency key

Supported create and update requests accept the optional Idempotency-Key header. Contact creation, inventory quantity adjustments, manual invoice payments and refunds, purchase-order sending and payments, estimate conversion to invoices or sales orders, and sales-order invoicing, packing, and manual shipping support it as well:

curl "https://yourbusiness.salesbinder.com/api/v3/customers" \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: create-customer-20260717-001" \
  --data '{"name":"Example Customer"}'

Generate a unique value for one logical operation and reuse it only when retrying that same operation. Keys must contain between 1 and 255 visible ASCII characters.

Replay behavior

If the original request completed, an identical retry made during the short idempotency window returns the original response and status. The replay response includes:

Idempotent-Replayed: true

The idempotency window is approximately five minutes. After it expires, reusing the value can create another record.

Conflicting requests

Reusing a key with different request data returns 409 Conflict:

{
  "error": {
    "type": "invalid_request_error",
    "code": "idempotency_key_reused",
    "message": "This idempotency key was already used with different request data.",
    "param": "Idempotency-Key"
  }
}

If an identical request using the same key is still running, the API returns 409 with idempotency_in_progress. Wait briefly and retry the identical request with the same key.

Key isolation

Idempotency values are isolated by account, API credential, HTTP method, and endpoint path. The same text used by another account or API key does not share a stored response.