# Get Wallet Balance
> Source: /api-reference/members/wallet/get-balance
> Get comprehensive wallet balance and tier information
> Endpoint: GET /members/me/wallet/balance

## Overview [#overview]

Returns comprehensive wallet balance including valid points, credit points, pending points, outstanding debt, net balance, total available points, debt status, and tier information with points to next tier.

This is the primary endpoint for displaying wallet status in member-facing applications.

## Authentication [#authentication]

Requires a valid Clerk JWT token in the Authorization header.

<RequestExample>

```bash cURL
curl -X GET "http://localhost:3000/v1/members/me/wallet/balance" \
  -H "Authorization: Bearer YOUR_CLERK_JWT"
```

```typescript TypeScript
const response = await fetch('http://localhost:3000/v1/members/me/wallet/balance', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_CLERK_JWT'
  }
});

const balance = await response.json();
```

```javascript Bruno
// From: /bruno/Members (Surface)/Me/Wallet/Get Wallet.bru
GET {{host}}/members/me/wallet/balance
Authorization: Bearer {{clerkJwt}}
```

</RequestExample>

## Response [#response]

<ResponseField name="validBalance" type="number" required>
  VALID asset balance (net of earnings minus spend)
  
  Points earned from stays that can be used for redemptions
</ResponseField>

<ResponseField name="creditBalance" type="number" required>
  CREDIT asset balance (promotional/early-access points)
  
  Promotional points that can be spent but don't count toward tier progression
</ResponseField>

<ResponseField name="pendingPoints" type="number" required>
  Points currently in escrow waiting for reservation completion
</ResponseField>

<ResponseField name="outstandingDebt" type="number" required>
  Outstanding debt amount (negative balance)
</ResponseField>

<ResponseField name="netBalance" type="number" required>
  Net spendable balance (validBalance + creditBalance - outstandingDebt)
</ResponseField>

<ResponseField name="totalAvailablePoints" type="number" required>
  Total points available for spending (convenience aggregate)
  
  Same as netBalance when positive, 0 when negative
</ResponseField>

<ResponseField name="hasDebt" type="boolean" required>
  Whether the member has outstanding debt
</ResponseField>

<ResponseField name="tierEligiblePoints" type="number" required>
  Points earned this calendar year that count toward tier qualification
</ResponseField>

<ResponseField name="tierLevel" type="number" required>
  Current tier level (1 = Traveler/base tier)
</ResponseField>

<ResponseField name="tierName" type="string" required>
  Current tier name
</ResponseField>

<ResponseField name="pointsToNextTier" type="number | null" required>
  Points needed to reach the next tier
  
  `null` if already at the highest tier
</ResponseField>

<ResponseField name="nextTierName" type="string | null" required>
  Name of the next tier
  
  `null` if already at the highest tier
</ResponseField>

<ResponseExample>

```json 200 Response - Member with Points
{
  "validBalance": 12500,
  "creditBalance": 2000,
  "pendingPoints": 1800,
  "outstandingDebt": 0,
  "netBalance": 14500,
  "totalAvailablePoints": 14500,
  "hasDebt": false,
  "tierEligiblePoints": 8500,
  "tierLevel": 2,
  "tierName": "Explorer",
  "pointsToNextTier": 11500,
  "nextTierName": "Voyager"
}
```

```json 200 Response - Member with Debt
{
  "validBalance": 5000,
  "creditBalance": 1000,
  "pendingPoints": 500,
  "outstandingDebt": 8000,
  "netBalance": -2000,
  "totalAvailablePoints": 0,
  "hasDebt": true,
  "tierEligiblePoints": 3200,
  "tierLevel": 1,
  "tierName": "Traveler",
  "pointsToNextTier": 16800,
  "nextTierName": "Explorer"
}
```

```json 200 Response - Top Tier Member
{
  "validBalance": 75000,
  "creditBalance": 5000,
  "pendingPoints": 0,
  "outstandingDebt": 0,
  "netBalance": 80000,
  "totalAvailablePoints": 80000,
  "hasDebt": false,
  "tierEligiblePoints": 45000,
  "tierLevel": 4,
  "tierName": "Pioneer",
  "pointsToNextTier": null,
  "nextTierName": null
}
```

</ResponseExample>

## Balance Types [#balance-types]

### Valid Balance [#valid-balance]
- **Source**: Points earned from completed stays
- **Usage**: Can be spent on redemptions  
- **Tier Impact**: Counts toward tier qualification
- **Expiration**: Typically 2 years from earn date

### Credit Balance [#credit-balance]
- **Source**: Promotional points, bonuses, adjustments
- **Usage**: Can be spent on redemptions
- **Tier Impact**: Does NOT count toward tier qualification
- **Expiration**: Varies by promotion terms

### Pending Points [#pending-points]
- **Source**: Points in escrow for future/recent stays
- **Usage**: Cannot be spent until converted to Valid
- **Conversion**: Happens after checkout completion
- **Display**: Usually shown as "Points Pending"

## Debt Handling [#debt-handling]

When `hasDebt: true`:
- Member cannot make new redemptions until debt is cleared
- `totalAvailablePoints` will be 0 regardless of credit/valid balances  
- Debt typically occurs from:
  - Redemption refunds/adjustments
  - Booking cancellations after point spend
  - Administrative corrections

## Tier Information [#tier-information]

The tier fields provide context for member progression:
- **Current Status**: `tierLevel` and `tierName`
- **Progression**: `pointsToNextTier` and `nextTierName`  
- **Annual Progress**: `tierEligiblePoints` (current year)

When at the highest tier:
- `pointsToNextTier` and `nextTierName` are `null`
- Show celebration UI instead of progression

## Related Endpoints [#related-endpoints]

- [Get Wallet](/api-reference/members/wallet/get-wallet) - Full wallet details
- [Get Activity](/api-reference/members/wallet/get-activity) - Recent transactions
- [Get Transactions](/api-reference/members/wallet/get-transactions) - Transaction history