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

{
  "valid": true,
  "gift_card": {
    "id": "gc_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
    "code": "GIFT-XMAS-A3B7C9D2",
    "status": "active",
    "current_balance": 3750,
    "initial_balance": 5000,
    "currency": "USD",
    "expires_at": "2025-02-14T23:59:59Z",
    "is_expired": false,
    "days_until_expiry": 390
  },
  "transactions": {
    "total_redeemed": 1250,
    "redemption_count": 2,
    "last_redemption": {
      "date": "2024-01-15T14:30:00Z",
      "amount": 750,
      "order_id": "order_456789"
    }
  },
  "restrictions": {
    "minimum_purchase": null,
    "product_restrictions": false,
    "category_restrictions": false
  },
  "can_be_used": true,
  "messages": []
}
This endpoint checks the current balance and status of a gift card. It’s commonly used at checkout or in customer portals.

​
Authentication

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

​
Request Body

​
code
string
required
Gift card code to check
​
pin
string
Gift card PIN (required for some gift cards)

​
Response

Returns gift card balance and status information. 
curl --location --request POST 'https://api.stateset.com/v1/gift-cards/balance' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "code": "GIFT-XMAS-A3B7C9D2"
}'

{
  "valid": true,
  "gift_card": {
    "id": "gc_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
    "code": "GIFT-XMAS-A3B7C9D2",
    "status": "active",
    "current_balance": 3750,
    "initial_balance": 5000,
    "currency": "USD",
    "expires_at": "2025-02-14T23:59:59Z",
    "is_expired": false,
    "days_until_expiry": 390
  },
  "transactions": {
    "total_redeemed": 1250,
    "redemption_count": 2,
    "last_redemption": {
      "date": "2024-01-15T14:30:00Z",
      "amount": 750,
      "order_id": "order_456789"
    }
  },
  "restrictions": {
    "minimum_purchase": null,
    "product_restrictions": false,
    "category_restrictions": false
  },
  "can_be_used": true,
  "messages": []
}