> 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. # Loyalty ## Overview The Brevo Loyalty API lets you create and manage points-based or cashback reward programs entirely via API. You can enroll members, credit and debit balances, manage tier progressions, distribute vouchers, and react to loyalty events in real time via webhooks. The Loyalty API is designed to integrate directly into your eCommerce stack. It works alongside the Brevo [eCommerce API](/docs/add-the-ecommerce-app) and [Contacts API](/docs/synchronise-contact-lists), allowing you to connect purchase events, customer profiles, and reward mechanics in a single unified platform. The Loyalty engine is a separate Brevo module. Verify it is enabled on your account under **Loyalty > Programs** in the Brevo app. All Loyalty API endpoints use the base path `https://api.brevo.com/v3/loyalty/`. --- ## Key concepts The Loyalty API uses a layered data model. Understanding how these objects relate to each other before writing your first API call will save significant debugging time. #### Loyalty program The top-level container for your entire reward strategy. A program defines the name, currency type (points or cashback), and publication status. All other loyalty objects — balances, tiers, rewards — belong to a program. A program is created in `inactive` state and only becomes operational after you call the **Publish** endpoint. Configuration changes (tiers, balance definitions) made after publishing require a new publish call to take effect. **Endpoints:** `POST /loyalty/config/programs`, `GET /loyalty/config/programs/{pid}` #### Balance definition The "currency" your members accumulate. A single program can have multiple balance definitions — for example, one for purchase points and one for referral bonus points. Each balance definition independently configures: * **Expiry policy** — `fixed` (calendar date), `rolling` (e.g. 12 months after last activity), or inactivity-based (e.g. after 24 months without purchase) * **Rounding rules** — nearest, `ceiling` (always round up), `floor` (always round down), or no rounding (maintain decimals) * **Capping limits** — minimum balance, maximum balance, max credit/debit per operation, and credit/debit frequency limits **Endpoint:** `POST /loyalty/config/programs/{pid}/balance-definitions` #### Subscription A Brevo contact enrolled in a program. In the API this object is called a subscription — in customer-facing contexts, it represents the member's membership. The subscription record links a Brevo contact to the program and holds their enrollment date, balance values, and tier status. When a contact subscribes, all balances start at `0` and they are placed on the default entry tier. Enrollment can happen: * **Automatically** — triggered after a first purchase via a rule * **Manually** — via API call or a customer sign-up form A subscription ends under conditions such as prolonged inactivity, explicit unsubscribe, GDPR removal, or program anniversary. **Endpoint:** `POST /loyalty/config/programs/{pid}/subscriptions` #### Balance The current value of a member's balance for a given balance definition. Balances are read-only — you modify them by creating transactions, not by writing to balances directly. Balances are governed by limits set in the balance definition: * A **maximum balance cap** refuses credits once the limit is reached — the transaction returns a `balance_transaction_unauthorized` webhook event * A **minimum balance** can trigger automations such as tier downgrade or winback campaigns * **Credit and debit frequency limits** may reject transactions that exceed the allowed number of operations per period Understanding these limits is important for diagnosing unexpected `422` errors or unauthorized transaction webhooks during integration. **Endpoint:** `GET /loyalty/balance/programs/{pid}/subscriptions/{cid}/balances` #### Transaction A single credit or debit event applied to a balance. Transactions go through a two-phase lifecycle: they are created as `pending` (balance unchanged), then either `completed` (balance updated) or `cancelled` (balance unchanged). **Endpoints:** `POST /loyalty/balance/programs/{pid}/transactions`, `POST .../transactions/{tid}/complete`, `POST .../transactions/{tid}/cancel` #### Balance order A group of transactions tied to a single business event — typically a purchase order. A balance order lets you credit or debit across multiple balance definitions in one atomic operation, and complete or cancel them all together when the business event resolves. **Endpoint:** `POST /loyalty/balance/programs/{pid}/create-order` #### Tier group & tier A tier group is the logic container that manages a collection of tiers and defines the global upgrade/downgrade strategy for a balance definition. A member belongs to exactly one tier within a group at any time. Key tier group properties: * `upgradeEvaluationTrigger` — when a member is evaluated for a higher tier (`real_time`, `membership_anniversary`, or `tier_anniversary`) * `downgradeEvaluationTrigger` — when a member is evaluated for a lower tier (same options — commonly set to `membership_anniversary` to avoid mid-year status loss) * `tierOrder` — defines the ranking sequence of tiers within the group Each **tier** defines: * An entry threshold (minimum balance value to reach this tier) * Customer-facing name, description, and image * Rewards attributed on reaching this tier Tier thresholds within the same group must be unique — two tiers cannot share the same entry point. Threshold changes require re-publishing the program. **Endpoints:** `POST /loyalty/config/programs/{pid}/tier-groups`, `GET .../tiers` #### Reward / offer A voucher or benefit attributed to a member. Rewards can be attributed automatically via rules (e.g. on tier upgrade, on birthday) or manually via API. Voucher codes can be displayed in your storefront and applied at checkout. **Endpoint:** `GET /loyalty/balance/programs/{pid}/subscriptions/{cid}/vouchers` --- ## How the objects relate ``` Loyalty Program (inactive → active after publish) │ ├── Balance Definition (e.g. "Purchase Points") │ └── Tier Group (e.g. "VIP Levels") │ ├── Tier: Bronze (threshold: 0 pts) │ ├── Tier: Silver (threshold: 300 pts) │ └── Tier: Gold (threshold: 500 pts) │ └── Reward / Offer (e.g. "10% birthday voucher") Brevo Contact └── Subscription (member record) ├── Balance (current value, per Balance Definition) │ └── Transactions (credit/debit history) └── Vouchers (attributed rewards) ``` --- ## Transaction lifecycle Every credit or debit follows a two-phase pattern. The balance is not updated until you explicitly complete the transaction. ``` Create Transaction / Balance Order │ ▼ status: PENDING (balance not updated) │ ┌─────┴─────┐ ▼ ▼ COMPLETE CANCEL │ │ Balance Balance updated unchanged │ Tier re-evaluated │ Reward attributed (if rule matches) ``` Use `autoComplete: true` when creating a transaction to skip the manual completion step — useful for instant rewards like sign-up bonuses or birthday credits. For purchase flows, always keep transactions in `pending` state until the order is confirmed.