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

# Get Points Balance

> Check a customer's current points balance

# Get Points Balance

Retrieve a customer's current points balance. This is a lightweight endpoint that returns only the essential balance information.

<Info>
  This endpoint requires **Shop API authentication** (X-API-Key and X-API-Secret headers).
</Info>

## Base URL

| Environment | URL                                                                  |
| ----------- | -------------------------------------------------------------------- |
| Staging     | `https://staging-api.loyalty.lt/{locale}/shop/loyalty-cards/balance` |
| Production  | `https://api.loyalty.lt/{locale}/shop/loyalty-cards/balance`         |

## Query Parameters

<Tip>
  The `card_number` parameter accepts both the card number (e.g., `123-456-789`) and the QR code UUID value. This allows you to search by whatever value you have scanned.
</Tip>

<ParamField query="card_number" type="string">
  Loyalty card number (e.g., `123-456-789`) or QR code value (UUID)
</ParamField>

<ParamField query="card_id" type="integer">
  Loyalty card ID
</ParamField>

<ParamField query="user_id" type="integer">
  User ID to find their card
</ParamField>

<Note>
  At least one query parameter is required.
</Note>

## Request Example

<RequestExample>
  ```bash cURL - By Card Number theme={null}
  curl -X GET "https://staging-api.loyalty.lt/en/shop/loyalty-cards/balance?card_number=123-456-789" \
    -H "X-API-Key: your_api_key" \
    -H "X-API-Secret: your_api_secret"
  ```

  ```bash cURL - By QR Code theme={null}
  curl -X GET "https://staging-api.loyalty.lt/en/shop/loyalty-cards/balance?card_number=550e8400-e29b-41d4-a716-446655440000" \
    -H "X-API-Key: your_api_key" \
    -H "X-API-Secret: your_api_secret"
  ```

  ```javascript JavaScript theme={null}
  async function getBalance(cardNumber) {
    const response = await fetch(
      `https://staging-api.loyalty.lt/en/shop/loyalty-cards/balance?card_number=${cardNumber}`,
      {
        headers: {
          'X-API-Key': 'your_api_key',
          'X-API-Secret': 'your_api_secret'
        }
      }
    );
    
    const data = await response.json();
    return data.data.points;
  }

  const points = await getBalance('123-456-789');
  console.log(`Current balance: ${points} points`);
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json Success Response (200) theme={null}
  {
    "success": true,
    "code": 200,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "message": "Balance retrieved successfully",
    "data": {
      "card_id": 567,
      "card_number": "123-456-789",
      "points": 1250
    }
  }
  ```
</ResponseExample>

## Response Fields

<ResponseField name="card_id" type="integer">
  Loyalty card ID
</ResponseField>

<ResponseField name="card_number" type="string">
  Loyalty card number in format `XXX-XXX-XXX`
</ResponseField>

<ResponseField name="points" type="integer">
  Current points balance (non-expired points only)
</ResponseField>

## Error Codes

| Code | Status | Description                                              |
| ---- | ------ | -------------------------------------------------------- |
| 1100 | 422    | Validation error - at least one query parameter required |
| 1200 | 404    | Loyalty card not found                                   |
| 1004 | 401    | Partner not authenticated                                |

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Get Loyalty Card Info" icon="id-card" href="/api-reference/endpoints/shop/loyalty-cards/info">
    Get full card details including user info and redemption settings
  </Card>

  <Card title="Create Transaction" icon="receipt" href="/api-reference/endpoints/shop/transactions/create">
    Award or redeem points in a purchase transaction
  </Card>
</CardGroup>