Idempotency

Send an Idempotency-Key so a retried request can never buy twice.

Networks fail in the middle of requests. If a purchase times out, you cannot tell whether it went through, and retrying blindly could buy twice.

Send an Idempotency-Key header and the retry is safe:

curl -X POST https://resellerhq.com/api/v1/numbers/orders \
  -H "Authorization: Bearer $RHQ_API_KEY" \
  -H "Idempotency-Key: 6f1c2f0e-5b7a-4d0e-9a51-1c2c8a0b7f11" \
  -H "Content-Type: application/json" \
  -d '{"country":"US","duration":"30d","customerId":"cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"}'

How it behaves

The first request with a key runs normally. Its outcome, success or error, is stored for 24 hours.
A retry with the same key and the same body gets the stored response back. Nothing runs twice.
The same key with a different body answers 422, because that is a mistake, not a retry.
A retry that arrives while the first request is still running answers 409. Wait and try again.

Rules

A key is 8 to 200 characters. A UUID is a good choice.
Use a new key for each new operation, and reuse it only to retry that operation.
Keys are scoped to your account, so they cannot collide with anyone else's.

Every route that spends money accepts the header: ordering and renewing numbers, registering and renewing domains, and ordering mailboxes.

Invoicing

Bill a customer for sales you have already made, discount an invoice before it is issued, correct one already sent with a void or a credit note, and record payments, refunds and statements against their balance.

Webhooks

Receive signed events on your own endpoint, following the Standard Webhooks specification.

On this page

How it behaves Rules