> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Check Gift Card Balance

> Check the balance and validity of a gift card

<Note>
  This endpoint checks the current balance and status of a gift card. It's commonly used at checkout or in customer portals.
</Note>

## Authentication

This endpoint requires a valid API key with `gift_cards:read` permissions.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Request Body

<ParamField body="code" type="string" required>
  Gift card code to check
</ParamField>

<ParamField body="pin" type="string">
  Gift card PIN (required for some gift cards)
</ParamField>

### Response

Returns gift card balance and status information.

<RequestExample>
  ```bash cURL theme={null}
  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"
  }'
  ```

  ```javascript Node.js theme={null}
  const balance = await stateset.giftCards.checkBalance({
    code: "GIFT-XMAS-A3B7C9D2"
  });
  ```

  ```python Python theme={null}
  balance = stateset.gift_cards.check_balance(
    code="GIFT-XMAS-A3B7C9D2"
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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": []
  }
  ```
</ResponseExample>