For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Help CenterAPI KeysStatusSign In
GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelog
  • Getting started
    • Overview
    • Quickstart
    • Authentication
    • Rate limits
  • Messaging API
    • Send transactional email
    • Send transactional SMS
    • Send transactional WhatsApp
  • Marketing Platform
    • Manage your contacts
    • Track website activity
    • Send WhatsApp campaigns
    • Weekly event exports
  • Webhooks
    • Getting started
    • Conversations webhooks
    • Payment webhooks
    • Marketing webhooks
    • Transactional webhooks
    • Loyalty webhooks
    • Batched webhooks
    • Secure webhook calls
    • Meetings and phone webhooks
    • Push notification webhooks
    • Sales CRM webhooks
  • Conversations
    • Getting started
    • Customize the chat widget
    • JavaScript API reference
    • REST API reference
    • Conversations webhooks
  • eCommerce
    • Activate eCommerce app
    • Manage product categories
    • Manage products
    • Manage orders
    • Coupon collections
    • eCommerce tracker events
  • Loyalty
    • Overview
    • Set up a program
    • Enroll members
    • Credit & debit points
    • Read member data
    • Best practices
  • Custom Objects
    • Custom objects management
  • Brevo tracker and events
    • Getting started
    • JavaScript implementation
    • REST implementation
    • Legacy tracker documentation
    • Events
  • Accounts and settings
    • Senders and domains
    • User activity logs
    • External feeds
    • Invited users
LogoLogo
Help CenterAPI KeysStatusSign In
On this page
  • Overview
  • Authentication
  • Steps
Loyalty

Set up a loyalty program

Learn how to create, configure, and publish a loyalty program via the Brevo API.
Was this page helpful?
Previous

Enroll members

Learn how to subscribe Brevo contacts to a loyalty program.
Next
Built with

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)

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

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/config/programs/{pid}/balance-definitions

$curl --request POST \
>  --url https://api.brevo.com/v3/loyalty/config/programs/27xxdd7a-.../balance-definitions \
>  --header 'api-key: YOUR_API_KEY' \
>  --header 'content-type: application/json' \
>  --data '{
>    "name": "Purchase Points",
>    "unit": "points",
>    "expiryPolicy": {
>      "type": "rolling",
>      "duration": 12,
>      "unit": "month"
>    },
>    "roundingPolicy": "round_half_up"
>  }'

Request parameters

ParameterTypeRequiredDescription
namestringYesInternal name for this balance type
unitstringYesDisplay label shown to members (e.g. "points", "€")
expiryPolicy.typestringNonever, rolling (from last activity), fixed (calendar date each year), or inactivity-based (after N months without purchase)
expiryPolicy.duration + unitint + stringFor rolling / inactivityDuration before expiry (e.g. 12, "month")
roundingPolicystringNonone (maintain decimals), round_half_up (nearest), floor (always round down), or ceiling (always round up)
maxBalancenumberNoMaximum balance cap. Credits are refused once this limit is reached — triggers a balance_transaction_unauthorized event.
minBalancenumberNoMinimum balance threshold. Falling below this value can trigger automations.
maxCreditPerOperationnumberNoMaximum amount that can be credited in a single transaction.
maxDebitPerOperationnumberNoMaximum amount that can be debited in a single transaction.
creditFrequencyLimitobjectNoMaximum number of credit operations allowed per period.
debitFrequencyLimitobjectNoMaximum number of debit operations allowed per period.
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)

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

$curl --request POST \
>  --url https://api.brevo.com/v3/loyalty/config/programs/27xxdd7a-.../tier-groups \
>  --header 'api-key: YOUR_API_KEY' \
>  --header 'content-type: application/json' \
>  --data '{
>    "name": "VIP Levels",
>    "balanceDefinitionId": "{balanceDefinitionId}",
>    "upgradeEvaluationTrigger": "real_time",
>    "downgradeEvaluationTrigger": "membership_anniversary",
>    "tiers": [
>      { "name": "Bronze", "threshold": 0 },
>      { "name": "Silver", "threshold": 300 },
>      { "name": "Gold",   "threshold": 500 }
>    ]
>  }'

Tier group parameters

ParameterTypeRequiredDescription
namestringYesInternal name for the tier group
balanceDefinitionIdstring (UUID)YesThe balance definition this tier group is evaluated against
upgradeEvaluationTriggerstringYesWhen a member is evaluated for a higher tier
downgradeEvaluationTriggerstringYesWhen a member is evaluated for a lower tier
tiersarrayYesOrdered list of tiers. Each tier requires name and threshold.
metaobjectNoAdditional metadata for the tier group. Supports isInternal (boolean) to mark the group as internal.

Tier evaluation trigger 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 upgradeEvaluationTrigger: real_time and downgradeEvaluationTrigger: membership_anniversary. This upgrades members instantly while protecting them from losing status mid-year.

Tier thresholds within the same group must be unique — two tiers cannot share the same entry point. Any threshold 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.