> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.brevo.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.brevo.com/_mcp/server.

# Read member data

## Overview

Use these endpoints to power loyalty widgets in your storefront, mobile app, or customer account page. All read endpoints are independent — make them in parallel for best performance.

---

## Get current balance

**Endpoint:** `GET https://api.brevo.com/v3/loyalty/balance/programs/{pid}/subscriptions/{cid}/balances`

```bash
curl --request GET \
  --url 'https://api.brevo.com/v3/loyalty/balance/programs/27xxdd7a-.../subscriptions/12345/balances?includeInternal=false' \
  --header 'api-key: YOUR_API_KEY'
```

**Query parameters**

| Parameter         | Type    | Required | Description                                                                             |
| ----------------- | ------- | -------- | --------------------------------------------------------------------------------------- |
| `includeInternal` | boolean | No       | If `true`, includes balances tied to internal balance definitions. Defaults to `false`. |

**Response (200)**

```json
[
  {
    "balanceDefinitionId": "a74cxx1d-4a96-4xx3-804e-dc3xxd9axxeb",
    "name": "Purchase Points",
    "unit": "points",
    "value": 340,
    "expiresAt": "2026-01-01T00:00:00.000Z"
  }
]
```

The response is an array — one entry per balance definition configured on the program.

---

## Get current tier

**Endpoint:** `GET https://api.brevo.com/v3/loyalty/balance/programs/{pid}/subscriptions/{cid}/tier`

```bash
curl --request GET \
  --url https://api.brevo.com/v3/loyalty/balance/programs/27xxdd7a-.../subscriptions/12345/tier \
  --header 'api-key: YOUR_API_KEY'
```

**Response (200)**

```json
{
  "tierGroupId": "2exxx6ee-6x9f-400d-a85d-a312xx1a445b",
  "tierGroupName": "VIP Levels",
  "tierId": "67000bb5-f193-4xxb-bx58-d08dc000c12f",
  "tierName": "Silver",
  "nextTierName": "Gold",
  "nextTierThreshold": 500,
  "currentBalance": 340
}
```

Use `nextTierThreshold` and `currentBalance` to compute the points remaining to the next tier: `500 - 340 = 160 pts to Gold`.

---

## Get available vouchers

**Endpoint:** `GET https://api.brevo.com/v3/loyalty/balance/programs/{pid}/subscriptions/{cid}/vouchers`

```bash
curl --request GET \
  --url https://api.brevo.com/v3/loyalty/balance/programs/27xxdd7a-.../subscriptions/12345/vouchers \
  --header 'api-key: YOUR_API_KEY'
```

**Response (200)**

```json
[
  {
    "id": "3c000afd-fb2e-4275-9007-29178f00fd5a",
    "code": "GOLD10",
    "offerId": "29xx7df8-3cf3-4x5c-8e74-8cd00085000e",
    "offerName": "Gold Welcome Reward",
    "publicDescription": "10% off your next order",
    "expiresAt": "2025-12-31T23:59:59.000Z"
  }
]
```

---

## Get transaction history

**Endpoint:** `GET https://api.brevo.com/v3/loyalty/balance/programs/{pid}/subscriptions/{cid}/transactions`

```bash
curl --request GET \
  --url 'https://api.brevo.com/v3/loyalty/balance/programs/27xxdd7a-.../subscriptions/12345/transactions?status=completed&transactionType=credit&limit=20&offset=1' \
  --header 'api-key: YOUR_API_KEY'
```

**Query parameters**

| Parameter         | Type    | Required | Description                                                                                             |
| ----------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `limit`           | integer | No       | Max transactions to return. Default `20`.                                                               |
| `offset`          | integer | No       | Page number to retrieve (not a record skip count). Default `0`.                                         |
| `status`          | string  | No       | Filter by transaction status. Allowed values: `draft`, `completed`, `rejected`, `cancelled`, `expired`. |
| `transactionType` | string  | No       | Filter by transaction type. Allowed values: `credit`, `debit`.                                          |

Returns transactions for the member ordered by creation date descending.

---

## Building a loyalty widget

A standard loyalty account widget combines three parallel calls:

```
1. GET .../balances     → "You have 340 points"
2. GET .../tier         → "Silver member · 160 pts to Gold"
3. GET .../vouchers     → "1 reward available · GOLD10"
```

Make these calls in parallel — each is independent and does not depend on the others.

```javascript title="Node.js"
const BASE = `https://api.brevo.com/v3/loyalty/balance/programs/${programId}/subscriptions/${contactId}`;
const headers = { 'api-key': API_KEY };

const [balances, tier, vouchers] = await Promise.all([
  fetch(`${BASE}/balances`, { headers }).then(r => r.json()),
  fetch(`${BASE}/tier`,     { headers }).then(r => r.json()),
  fetch(`${BASE}/vouchers`, { headers }).then(r => r.json()),
]);

// Render: "340 pts · Silver · 160 pts to Gold · 1 reward available"
```

```python title="Python"
import asyncio, httpx

BASE = f"https://api.brevo.com/v3/loyalty/balance/programs/{program_id}/subscriptions/{contact_id}"
HEADERS = {"api-key": API_KEY}

async def get_loyalty_data():
    async with httpx.AsyncClient() as client:
        balances, tier, vouchers = await asyncio.gather(
            client.get(f"{BASE}/balances", headers=HEADERS),
            client.get(f"{BASE}/tier",     headers=HEADERS),
            client.get(f"{BASE}/vouchers", headers=HEADERS),
        )
    return balances.json(), tier.json(), vouchers.json()
```

Cache balance and tier responses for 30–60 seconds on high-traffic account pages. These values only change when a transaction is completed, so near-real-time staleness is acceptable for display purposes.