Loyalty

Loyalty

Build and operate reward programs programmatically with the Brevo Loyalty API.

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 and Contacts API, 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.

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}

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

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

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

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

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

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

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.