Skip to main content
Giving stock is idempotent, controlled by the idempotencyKey you supply on POST /v1/rewards. This makes retries — after a timeout, network blip, or double-click — safe.

​
How it works

  • Generate a fresh idempotencyKey per stock award (a UUID is ideal). Reuse the same key when retrying that same award.
  • The key is unique per app and must be 8–128 characters.
​
First request
201 Created
The award is created. idempotentReplay is false.
​
Retry with the same key and same payload
200 OK
The original award is returned unchanged and idempotentReplay is true. No duplicate is created.
​
Same key, different payload
409 Conflict
Returns a conflict error — a key can’t be reused for a different award.
Concurrent duplicate requests are handled safely too: exactly one award is created, and the others receive it as a replay.
Persist the idempotencyKey alongside whatever triggered the award (e.g. an order id), so a retry naturally reuses the same key.