Idempotency

Placing orders, paying invoices, renewing, changing plans and cancelling all move money or end a service. A network error in the middle must never turn one click into two charges, so these operations require two extra things.

confirm: trueCopy Anchor Link

Commercial and destructive operations refuse to run unless the body contains "confirm": true. It is a deliberate speed bump: a script has to say it means it.

Idempotency-KeyCopy Anchor Link

Every commercial operation requires an Idempotency-Key header: a unique string of up to 128 characters, chosen by you, for example a UUID.

curl -X POST https://api.deluxhost.net/v1/orders \
  -H "Authorization: Bearer $DELUXHOST_TOKEN" \
  -H "Idempotency-Key: 7c0f1f8e-2b7a-4d5e-9a51-6f1d3c2b8e40" \
  -H "Content-Type: application/json" \
  -d '{
    "confirm": true,
    "items": [{ "productSlug": "<slug from the catalog>", "cycle": "<billing cycle>" }]
  }'

Product slugs and the billing cycles each product offers come from the Product catalog endpoints.

How keys behave:

• A key is reserved per account and per operation the first time we see it.
• Sending the same key again with identical parameters replays the original response, without running the operation a second time.
• Reusing a key with different parameters returns 409.
• If the first attempt is still pending, or it failed, the key answers 409 and is never retried automatically: a payment may already have been accepted by the gateway.

Tip: On a 409 or a timeout, look at the invoice or order before using a new key. A key guarantees a single attempt, not that every attempt succeeds.

Keys are kept until the account is deleted, and the stored responses are encrypted at rest.

Something unclear or missing? Open a ticket and the team will get back to you.