Skip to main content

Redeem store item

POST 
/store/redeem

Redeems a store item using gems.

Idempotency behavior:

  • send Idempotency-Key per purchase attempt for safe retries
  • same key + same user returns the previous redemption
  • same key reused by a different user returns 409

Request​

Responses​

Successful Response

Request body​

{
  "store_item_id": 12,
  "shipping_address": null
}

shipping_address is required when the item uses webhook/physical fulfillment.

Physical example:

{
  "store_item_id": 99,
  "shipping_address": {
    "name": "Rahul Nema",
    "line1": "123 MG Road",
    "line2": "Near Metro",
    "city": "Bengaluru",
    "state": "Karnataka",
    "pincode": "560001",
    "phone": "+919999999999"
  }
}

Response shape​

{
  "id": 834,
  "status": "fulfilled",
  "gem_cost_at_time": 150,
  "fulfillment_data": {
    "code": "AMZN-XXXX-YYYY",
    "pin": "1234"
  }
}

Redemption behavior​

  1. Server validates item existence and availability window.
  2. Server checks stock and per-player limit.
  3. Server checks wallet gems.
  4. Server deducts gems and records wallet transaction.
  5. Server creates redemption record.
  6. Fulfillment output depends on fulfillment strategy:
    • code_pool: response often returns status = fulfilled with code/pin
    • webhook/provider flows: response is usually status = pending until downstream completion

cURL examples​

Redeem voucher:

curl -X POST "http://localhost:8001/store/redeem" \
  -H "x-client-id: <client-id>" \
  -H "x-client-secret: <client-secret>" \
  -H "Authorization: Bearer <access-token>" \
  -H "Idempotency-Key: user-42:item-12:order-1001" \
  -H "Content-Type: application/json" \
  -d '{"store_item_id":12}'

Redeem physical item:

curl -X POST "http://localhost:8001/store/redeem" \
  -H "x-client-id: <client-id>" \
  -H "x-client-secret: <client-secret>" \
  -H "Authorization: Bearer <access-token>" \
  -H "Idempotency-Key: user-42:item-99:order-1002" \
  -H "Content-Type: application/json" \
  -d '{"store_item_id":99,"shipping_address":{"name":"Rahul Nema","line1":"123 MG Road","city":"Bengaluru","state":"Karnataka","pincode":"560001","phone":"+919999999999"}}'