Skip to main content
POST
https://api.stateset.com
/
v1
/
gift-cards
/
redeem
curl --location --request POST 'https://api.stateset.com/v1/gift-cards/redeem' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "code": "GIFT-XMAS-A3B7C9D2",
    "amount": 2500,
    "order_id": "order_987654",
    "customer_id": "cust_def456"
}'

{
  "id": "txn_125",
  "object": "gift_card_transaction",
  "type": "redemption",
  "gift_card_id": "gc_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "code": "GIFT-XMAS-A3B7C9D2",
  "amount": 2500,
  "currency": "USD",
  "balance_before": 3750,
  "balance_after": 1250,
  "order_id": "order_987654",
  "customer_id": "cust_def456",
  "status": "completed",
  "created_at": "2024-06-20T16:00:00Z",
  "gift_card": {
    "id": "gc_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
    "current_balance": 1250,
    "expires_at": "2025-02-14T23:59:59Z",
    "is_expired": false,
    "status": "active"
  },
  "metadata": {
    "pos_terminal_id": null,
    "cashier_id": null
  }
}
This endpoint redeems a gift card, deducting the specified amount from the card’s balance. It validates the card and checks all restrictions before processing.

​
Authentication

This endpoint requires a valid API key with gift_cards:write permissions. 
Authorization: Bearer YOUR_API_KEY

​
Request Body

​
code
string
required
Gift card code to redeem
​
pin
string
Gift card PIN (if required)
​
amount
integer
required
Amount to redeem in cents
​
order_id
string
required
Order ID to apply the gift card to
​
customer_id
string
Customer ID making the redemption

​
Response

Returns the redemption transaction details. 
curl --location --request POST 'https://api.stateset.com/v1/gift-cards/redeem' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "code": "GIFT-XMAS-A3B7C9D2",
    "amount": 2500,
    "order_id": "order_987654",
    "customer_id": "cust_def456"
}'

{
  "id": "txn_125",
  "object": "gift_card_transaction",
  "type": "redemption",
  "gift_card_id": "gc_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "code": "GIFT-XMAS-A3B7C9D2",
  "amount": 2500,
  "currency": "USD",
  "balance_before": 3750,
  "balance_after": 1250,
  "order_id": "order_987654",
  "customer_id": "cust_def456",
  "status": "completed",
  "created_at": "2024-06-20T16:00:00Z",
  "gift_card": {
    "id": "gc_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
    "current_balance": 1250,
    "expires_at": "2025-02-14T23:59:59Z",
    "is_expired": false,
    "status": "active"
  },
  "metadata": {
    "pos_terminal_id": null,
    "cashier_id": null
  }
}