Redeem Gift Card

Redeem a gift card for an order

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

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"
}'

Response

{
  "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
  }
}