Idempotency Keys Explained: How to Prevent Double Charges in API Orders

You send an order to an API. The connection drops before you receive the answer. Did the order go through? If you send it again, will you be charged twice? Idempotency keys solve exactly this problem.

What does idempotent mean?

An operation is idempotent if doing it several times has the same effect as doing it once. Reading data is naturally idempotent. Creating a paid order is not, unless the API helps you.

How an idempotency key works

1. Your system generates a unique key for each order you want to place, for example your own order number.
2. You send it in the Idempotency-Key header.
3. The API remembers the key together with the result.
4. If you send the same key again, you get the original order back and nothing is charged again.

In the SyllHost Reseller API

Both POST /orders/hosting and POST /orders/domain require this header. It must be 8 to 100 characters. Reusing the same key for a different order returns 409 conflict, which protects you from accidental mix-ups.

curl -X POST https://syllhost.com/api/v1/orders/domain \
  -H "Authorization: Bearer sh_live_xxx" \
  -H "Idempotency-Key: shop-order-1001-domain" \
  -H "Content-Type: application/json" \
  -d '{"domain":"acme-traders.com","years":1}'

Choosing good keys

• Use an ID from your own system plus the action, such as order-1001-hosting.
• Do not use a random value generated at retry time, or it will not match the original.
• Store the key with your order before sending the request.

Retry strategy

1. If you get a network error or timeout, wait a moment.
2. Retry with the same key.
3. If you get the original order back, continue as normal.
4. Only create a new key for a genuinely new order.

Combine this with proper error handling. You can also send a reference field with your own order id to find the order later.

A story of the double charge

A store sends an order request. The server processes it, charges the account and starts to reply, but the network drops. The store sees a timeout and, to be safe, sends the same request again. Without protection, the customer now has two orders and two charges. With an idempotency key, the second request carries the same key and the API replies with the first order instead of creating another. The customer is charged once.

Implementing it in your own code

1. When you create an order in your database, also create its idempotency key, for example "shop-" . $orderId . "-hosting".
2. Send that key with the API request.
3. If you need to retry, read the key back from your database and use it again.
4. Mark the order as sent only after you receive a successful response.

Common mistakes

• Generating a new random key on each retry.
• Using the same key for two different orders (returns a conflict).
• Using keys that are too short or predictable such as 1, 2, 3 across systems.

FAQ

How long are keys remembered?

Treat a key as permanently tied to its order. Never reuse one for something else.

Is paying an invoice safe to repeat?

Yes. Paying an already-paid invoice through the API is safe and does not charge again.

Build with our API: read the Reseller API reference and the step-by-step guide. API access is enabled per account, so contact us to request it.