Idempotency

Every Giftronaut order creation request requires an idempotencyKey. Giftronaut rejects a repeated key with 409 DUPLICATE_IDEMPOTENCY_KEY, so a retry never creates a duplicate order.

How it works

Network failures, timeouts, and unexpected errors can leave you uncertain whether a request succeeded. Without idempotency, a naive retry might create a duplicate order and charge your balance twice.

By including an idempotencyKey field in the body of every order creation request (UUID v4 recommended), Giftronaut guarantees that the same key can never create more than one order. The first request with a given key creates the order and returns 201 Created. Any subsequent request that reuses the same key — regardless of whether the body is identical — is rejected with 409 DUPLICATE_IDEMPOTENCY_KEY; the original order is not replayed in the response.

curl -X POST "https://api.giftronaut.com/api/v1/orders/branded-cards" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
    "productId": "10042",
    "sendTiming": { "type": "IMMEDIATE" },
    "emailSetting": { "senderName": "Giftronaut Rewards", "subject": "Your gift has arrived!" },
    "recipients": [
      { "email": "alice@giftronaut.com", "firstName": "Alice", "amount": 50 }
    ]
  }'

Key requirements

Must be a unique string per logical operation (UUID v4 is ideal)
Maximum length: 64 characters
No expiry window: Giftronaut idempotency keys never expire and are checked against all past orders in your organization
Keys are scoped to your organization — different orgs can reuse the same key
Keys are scoped to the environment — Sandbox and Production keys are checked separately

Response behavior

Submitting an order with an already used idempotencyKey will not create a new order.

Scenario	HTTP status	Body
First request with a new key	`201`	New order object
Any retry with the same key (identical or different body)	`409`	Error: `DUPLICATE_IDEMPOTENCY_KEY`

A 409 DUPLICATE_IDEMPOTENCY_KEY means an order with that key already exists — it does not mean your order failed. If a network failure left you unsure whether the first request succeeded, do not blindly change the key and retry. Instead, confirm the outcome by looking up the order with your key: GET /api/v1/orders?clientOrderId={key}. If a matching order is returned, the original request succeeded.

Best practices

When placing orders, if you receive an error, retry the order with the same idempotencyKey
Giftronaut requires the idempotencyKey parameter to ensure duplicate orders are not created when you retry a failed order
Generate the key before the request — not inside a retry loop
Store the key alongside your order record so you can look the order up later via GET /api/v1/orders?clientOrderId={key}
Include idempotencyKey in the body of every order creation request (POST)
GET and DELETE requests are inherently safe to retry