Loyalty

Set up a loyalty program

Learn how to create, configure, and publish a loyalty program via the Brevo API.
View as Markdown

Overview

This guide walks through creating and configuring a loyalty program via API — from creation through to publishing. You can also configure programs in the Brevo UI (Loyalty > Programs) and use the API exclusively for runtime operations.

Authentication

All Loyalty API requests require your Brevo API key as a request header.

-H "api-key: YOUR_API_KEY"
-H "Content-Type: application/json"

Retrieve your API key from Settings > API Keys in the Brevo app, or at app.brevo.com/settings/keys/api.

Never expose your API key in client-side code. All Loyalty API calls must be made server-side.

Steps

1

Create the program

Endpoint: POST https://api.brevo.com/v3/loyalty/config/programs

curl --request POST \
  --url https://api.brevo.com/v3/loyalty/config/programs \
  --header 'api-key: YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "name": "VIP Club",
    "description": "Earn points on every purchase and unlock exclusive rewards."
  }'

Request parameters

ParameterTypeRequiredDescription
namestringYesProgram name, max 128 characters
descriptionstringNoCustomer-facing description, max 256 characters
documentIdstringNoOptional external document reference
metaobjectNoArbitrary key-value metadata

Response (200)

{
  "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
  "name": "VIP Club",
  "description": "Earn points on every purchase and unlock exclusive rewards.",
  "state": "inactive",
  "createdAt": "2025-03-01T10:00:00.000Z",
  "updatedAt": "2025-03-01T10:00:00.000Z"
}

Save the returned id — you will use it as {pid} (program ID) in all subsequent calls.

state starts as inactive. Members cannot be enrolled until the program is published in Step 4.

2

Define a balance definition

Endpoint: POST https://api.brevo.com/v3/loyalty/balance/programs/{pid}/balance-definitions

curl --request POST \
  --url https://api.brevo.com/v3/loyalty/balance/programs/27xxdd7a-.../balance-definitions \
  --header 'api-key: YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "name": "Purchase Points",
    "unit": "POINTS",
    "balanceAvailabilityDurationValue": 12,
    "balanceAvailabilityDurationUnit": "month",
    "balanceOptionCreditRounding": "natural",
    "balanceOptionDebitRounding": "natural"
  }'

Request parameters

ParameterTypeRequiredDescription
namestringYesInternal name for this balance type, max 128 characters
unitstringYesOne of a fixed set of unit codes: POINTS, EUR, USD, MXN, GBP, INR, CAD, SGD, RON, JPY, MYR, CLP, PEN, MAD, AUD, CHF, BRL
descriptionstringNoShort description, max 256 characters
balanceAvailabilityDurationValue + balanceAvailabilityDurationUnitint + stringNoDuration before the balance expires (unit: day, week, month, year)
balanceAvailabilityDurationModifierstringNonoModification, startOfPeriod, or endOfPeriod — when within the duration the balance actually expires
balanceExpirationDatestringNoFixed expiration date (dd/mm format), as an alternative to duration-based expiry
balanceOptionCreditRounding / balanceOptionDebitRoundingstringNolower, upper, or natural — rounding strategy for credit/debit transactions
balanceOptionAmountOvertakingStrategystringNostrict or partial — whether partial credit is allowed when a transaction would exceed maxAmount
maxAmount / minAmountnumberNoMaximum/minimum allowable balance
maxCreditAmountLimit / maxDebitAmountLimitnumberNoMaximum amount that can be credited/debited in a single operation
imageRefstringNoURL of an optional image reference
metaobjectNoAdditional metadata for the balance definition. Supports isInternal (boolean) to mark the definition as internal. Internal balance definitions are excluded from member-facing balance reads unless includeInternal=true is passed.
3

Configure tier groups (optional)

Creating tiers is a two-step process: first create the tier group, then create each tier within it — tiers can’t be created inline with the group.

Step 1 — create the tier group. Endpoint: POST https://api.brevo.com/v3/loyalty/tier/programs/{pid}/tier-groups

curl --request POST \
  --url https://api.brevo.com/v3/loyalty/tier/programs/27xxdd7a-.../tier-groups \
  --header 'api-key: YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "name": "VIP Levels",
    "upgradeStrategy": "real_time",
    "downgradeStrategy": "membership_anniversary"
  }'

Tier group parameters

ParameterTypeRequiredDescription
namestringYesName of the tier group
upgradeStrategy / downgradeStrategystringNo (default real_time)real_time, membership_anniversary, or tier_anniversary
upgradeSchedule / downgradeScheduleobjectRequired when the matching strategy is schedule-based{durationValue, durationUnit, durationModifier} or {scheduledDate} (DD/MM)
tierOrderarray of stringNoTier IDs in ascending order — set once tiers exist
metaobjectNoAdditional metadata. Supports isInternal (boolean).

Tier evaluation strategy options

ValueDescriptionRecommended use
real_timeTier re-evaluated on every completed transactionUpgrades — reward immediately
membership_anniversaryRe-evaluated once a year on enrollment anniversaryDowngrades — avoid mid-year status loss
tier_anniversaryRe-evaluated once a year on tier entry anniversaryWhen tier-year tracking matters

Set upgradeStrategy: real_time and downgradeStrategy: membership_anniversary. This upgrades members instantly while protecting them from losing status mid-year.

Step 2 — create each tier. Endpoint: POST https://api.brevo.com/v3/loyalty/tier/programs/{pid}/tier-groups/{gid}/tiers

curl --request POST \
  --url https://api.brevo.com/v3/loyalty/tier/programs/27xxdd7a-.../tier-groups/2exxx6ee-.../tiers \
  --header 'api-key: YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "name": "Silver",
    "accessConditions": [
      { "balanceDefinitionId": "a74cxx1d-4a96-4xx3-804e-dc3xxd9axxeb", "minimumValue": 300 }
    ]
  }'

Tier parameters

ParameterTypeRequiredDescription
namestringYesName of the tier
accessConditionsarrayYesMinimum balance thresholds required to access this tier. Each entry is {balanceDefinitionId, minimumValue}.
imageRefstringNoImage URL for the tier
tierRewardsarrayNoRewards granted on reaching this tier, as [{rewardId}]

Access-condition thresholds within the same group must be unique — two tiers cannot share the same entry point. Any change requires re-publishing the program.

4

Publish the program

Endpoint: POST https://api.brevo.com/v3/loyalty/config/programs/{pid}/publish

curl --request POST \
  --url https://api.brevo.com/v3/loyalty/config/programs/27xxdd7a-.../publish \
  --header 'api-key: YOUR_API_KEY'

Response (200): Returns the updated program object with "state": "active".

Any configuration changes made after publishing — to tiers, balance definitions, or rewards — require calling /publish again before they take effect for members.