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

$
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

Response (200)

1
[
2
  {
3
    "balanceDefinitionId": "a74cxx1d-4a96-4xx3-804e-dc3xxd9axxeb",
4
    "name": "Purchase Points",
5
    "unit": "points",
6
    "value": 340,
7
    "expiresAt": "2026-01-01T00:00:00.000Z"
8
  }
9
]

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

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

Response (200)

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

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

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

Response (200)

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

Get transaction history

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

$
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

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.

1
const BASE = `https://api.brevo.com/v3/loyalty/balance/programs/${programId}/subscriptions/${contactId}`;
2
const headers = { 'api-key': API_KEY };
3
4
const [balances, tier, vouchers] = await Promise.all([
5
  fetch(`${BASE}/balances`, { headers }).then(r => r.json()),
6
  fetch(`${BASE}/tier`,     { headers }).then(r => r.json()),
7
  fetch(`${BASE}/vouchers`, { headers }).then(r => r.json()),
8
]);
9
10
// Render: "340 pts · Silver · 160 pts to Gold · 1 reward available"