Loyalty webhooks | Brevo API Documentation

Overview

Loyalty webhooks deliver real-time events to your server when something meaningful happens in a program. Use them to trigger automated emails, push notifications, CRM updates, and personalization logic without polling the API.

Loyalty webhooks follow the same setup as all Brevo webhooks. See Webhooks getting started for configuration, security, and retry behavior.

Webhook event reference

Event	Fires when	Recommended automation
`balance_value_updated`	A transaction is completed and balance changes	”You earned X points” email or push notification
`balance_expiration_reminder`	N days before balance expires (configured on balance definition)	“Your points expire soon” campaign
`balance_value_expired`	Points have expired	Winback automation
`balance_minimum_value_reached`	Balance drops below configured minimum	Alert for cashback programs
`balance_maximum_value_reached`	Credit refused — member hit balance cap	Notify customer their cap was reached
`balance_transaction_unauthorized`	Transaction blocked (cap, rule, or cancelled)	Log + optional customer notification
`tier_association_updated`	Member tier upgraded or downgraded	”Welcome to Gold” email + trigger reward attribution
`tier_anniversary_reminder`	N days before tier anniversary (configured on tier group)	Re-engagement: “Maintain your Gold status”
`subscription_created`	Contact enrolled in program	Welcome flow + send digital loyalty card
`subscription_revoked`	Member unenrolled	Offboarding flow
`subscription_month_anniversary`	Monthly enrollment anniversary	Monthly summary email
`subscription_year_anniversary`	Annual enrollment anniversary	Anniversary reward + email
`voucher_expiration_reminder`	Voucher approaching expiry	”Use your reward before it expires” email
`voucher_redeemed`	Member redeemed a voucher	Confirmation + loyalty activity log
`voucher_expired`	Voucher has expired	Re-engagement offer

Event payloads

The currently supported Loyalty events and their payloads are listed below.

Balance webhook events

Membership webhook events

Membership anniversary reminder

Subscription webhook events

Tier webhook events

Voucher webhook events

Balance minimum value reached

Attribute name	Datatype	Description
`balance_definition.id`	String	Balance definition ID
`balance_definition.metadata`	Object	Balance definition data
`balance_definition.name`	String	Balance definition name
`balance_definition.unit`	String	Balance definition unit
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Name of the Loyalty program
`source_event_id`	String	Source event ID
`value`	Numeric	Balance value

1 {
2   "balance_definition": {
3     "id": "a74cxx1d-4a96-4xx3-804e-dc3xxd9axxeb",
4     "metadata": {
5         "key": "value"
6       },
7     "name": "Event",
8     "unit": "points"
9   },
10   "loyalty_program": {
11     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
12     "name": "VIP club"
13   },
14   "source_event_id": "test",
15   "value": 123
16 }

Subscription year anniversary

Attribute name	Datatype	Description
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Name of Loyalty program
`subscription.created_at`	String	Time and date when subscription was created
`subscription.loyalty_subscription_id`	String	Loyalty subscription ID

1 {
2   "loyalty_program": {
3     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
4     "name": "VIP club"
5   },
6   "subscription": {
7     "created_at": "2025-06-10T07:09:01.696Z",
8     "loyalty_subscription_id": "2ba00576-a5a9-400d-8b34-1e21xxd3xxd3"
9   }
10 }

Balance transaction unauthorized

Attribute name	Datatype	Description
`balance_definition.id`	String	Balance definition ID
`balance_definition.metadata`	String	Balance definition metadata
`balance_definition.name`	String	Balance definition name
`balance_definition.unit`	String	Balance definition unit
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Loyalty program name
`reason`	String	Rejection reason
`transaction.type`	String	Transaction type
`transaction.value`	Numeric	Transaction value

1 {
2   "balance_definition": {
3     "id": "a74cxx1d-4a96-4xx3-804e-dc3xxd9axxeb",
4     "metadata": {
5         "key": "value"
6       },
7     "name": "Event",
8     "unit": "points"
9   },
10   "loyalty_program": {
11     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
12     "name": "VIP Club"
13   },
14   "reason": "Amount falls above maximum balance amount limit",
15   "transaction": {
16     "type": "credit",
17     "value": 123
18   }
19 }

Tier anniversary reminder

Attribute name	Datatype	Description
`attributed_at`	String	Time and date of tier attribution
`loyalty_program.id`	String	Loyalty Program ID
`loyalty_program.name`	String	Loyalty Program name
`membership.card_id`	String	Membership Card ID
`membership.created_at`	String	Membership creation date
`reminder.unit`	String	Reminder unit
`reminder.value`	Numeric	Reminder value
`tier.id`	String	Tier ID
`tier.name`	String	Tier name
`tier_group.id`	String	Tier group ID
`tier_group.name`	String	Tier group name

1 {
2   "attributed_at": "2025-06-10T07:09:01.696Z",
3   "loyalty_program": {
4     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
5     "name": "VIP Club"
6   },
7   "membership": {
8     "card_id": "ABCDE00045SS125",
9     "created_at": "2025-06-10T07:09:01.696Z"
10   },
11   "reminder": {
12     "unit": "week",
13     "value": 123
14   },
15   "tier": {
16     "id": "67000bb5-f193-4xxb-bx58-d08dc000c12f",
17     "name": "Gold"
18   },
19   "tier_group": {
20     "id": "2exxx6ee-6x9f-400d-a85d-a312xx1a445b",
21     "name": "Medal"
22   }
23 }

Subscription revoked

Attribute name	Datatype	Description
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Loyalty program name
`loyalty_subscription_id`	String	Loyalty subscription ID

1 {
2   "loyalty_program": {
3     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
4     "name": "VIP Club"
5   },
6   "loyalty_subscription_id": "2ba00576-a5a9-400d-8b34-1e21xxd3xxd3"
7 }

Balance expiration reminder

Attribute name	Datatype	Description
`amount`	Numeric	Balance amount remaining
`balance_definition.id`	String	Balance definition ID
`balance_definition.metadata`	String	Balance definition metadata
`balance_definition.name`	String	Balance definition name
`balance_definition.unit`	String	Balance definition unit
`created_at`	String	Time and date the balance reminder was created
`expires_at`	String	Time and date when balance expires
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Loyalty program name
`membership.card_id`	String	Membership card ID
`membership.created_at`	String	Time and date membership was created
`reminder.unit`	String	Reminder unit
`reminder.value`	Numeric	Reminder value

1 {
2   "amount": 123,
3   "balance_definition": {
4     "id": "a74cxx1d-4a96-4xx3-804e-dc3xxd9axxeb",
5     "metadata": {
6         "key": "value"
7       },
8     "name": "Event",
9     "unit": "points"
10   },
11   "created_at": "2025-06-10T07:09:01.696Z",
12   "expires_at": "2025-06-10T07:09:01.696Z",
13   "loyalty_program": {
14     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
15     "name": "VIP Club"
16   },
17   "membership": {
18     "card_id": "ABCDE00045SS125",
19     "created_at": "2025-06-10T07:09:01.696Z"
20   },
21   "reminder": {
22     "unit": "week",
23     "value": 123
24   }
25 }

Subscription created

Attribute name	Datatype	Description
`created_at`	String	Time and date the subscription was created
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Loyalty program name
`loyalty_subscription_id`	String	Loyalty subscription ID

1 {
2   "created_at": "2025-06-10T07:09:01.696Z",
3   "loyalty_program": {
4     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
5     "name": "VIP Club"
6   },
7   "loyalty_subscription_id": "2ba00576-a5a9-400d-8b34-1e21xxd3xxd3"
8 }

Voucher created

Attribute name	Datatype	Description
`code`	String	Voucher code
`expires_at`	String	Time and date when voucher expires
`id`	String	Voucher ID
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Loyalty program name
`offer.id`	String	Offer ID
`offer.name`	String	Offer name
`offer.public_description`	String	Offer public description
`offer.public_image`	String	Offer public image
`offer.public_name`	String	Offer public name
`source_event_id`	String	Source event ID
`valid_from`	String	Time and date from which the voucher becomes valid

1 {
2   "code": "6c",
3   "expires_at": "2025-06-10T07:09:01.696Z",
4   "id": "3c000afd-fb2e-4275-9007-29178f00fd5a",
5   "loyalty_program": {
6     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
7     "name": "VIP Club"
8   },
9   "offer": {
10     "id": "29xx7df8-3cf3-4x5c-8e74-8cd00085000e",
11     "name": "RewardName",
12     "public_description": "offerdescription",
13     "public_image": "imageoffer",
14     "public_name": "offernamepublic"
15   },
16   "source_event_id": "test",
17   "valid_from": "2025-06-10T07:09:01.696Z"
18 }

Balance value expired

Attribute name	Datatype	Description
`balance_definition.id`	String	Balance definition ID
`balance_definition.metadata`	String	Balance definition metadata
`balance_definition.name`	String	Balance definition name
`balance_definition.unit`	String	Balance definition unit
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Loyalty program name
`value`	Numeric	Balance value

1 {
2   "balance_definition": {
3     "id": "a74cxx1d-4a96-4xx3-804e-dc3xxd9axxeb",
4     "metadata": {
5         "key": "value"
6       },
7     "name": "Event",
8     "unit": "points"
9   },
10   "loyalty_program": {
11     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
12     "name": "VIP Club"
13   },
14   "value": 123
15 }

Balance value updated

Attribute name	Datatype	Description
`balance_definition.id`	String	Balance definition ID
`balance_definition.metadata`	String	Balance definition metadata
`balance_definition.name`	String	Balance definition name
`balance_definition.unit`	String	Balance definition unit
`created`	Bool	Tells if balance was created or updated
`expiration_date`	String	Balance expiration date
`initial_value`	Numeric	Initial balance value
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Loyalty program name
`source_event_id`	String	Source event ID
`transaction.type`	String	Transaction type
`transaction.value`	Numeric	Transaction value
`value`	Numeric	Balance value

1 {
2   "balance_definition": {
3     "id": "a74cxx1d-4a96-4xx3-804e-dc3xxd9axxeb",
4     "metadata": {
5         "key": "value"
6       },
7     "name": "Event",
8     "unit": "points"
9   },
10   "created": true,
11   "expiration_date": "2025-06-10T07:09:01.696Z",
12   "initial_value": 123,
13   "loyalty_program": {
14     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
15     "name": "VIP Club"
16   },
17   "source_event_id": "test",
18   "transaction": {
19     "type": "credit",
20     "value": 123
21   },
22   "value": 123
23 }

Membership anniversary reminder

Attribute name	Datatype	Description
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Loyalty program name
`membership.card_id`	String	Membership card ID
`membership.created_at`	String	Membership creation date
`reminder.unit`	String	Reminder unit
`reminder.value`	Numeric	Reminder value

1 {
2   "loyalty_program": {
3     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
4     "name": "VIP Club"
5   },
6   "membership": {
7     "card_id": "ABCDE00045SS125",
8     "created_at": "2025-06-10T07:09:01.696Z"
9   },
10   "reminder": {
11     "unit": "week",
12     "value": 123
13   }
14 }

Subscription member removed

Attribute name	Datatype	Description
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Loyalty program name
`member_id`	Numeric	Member ID

1 {
2   "loyalty_program": {
3     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
4     "name": "VIP Club"
5   },
6   "member_id": 123
7 }

Voucher revoked

Attribute name	Datatype	Description
`code`	String	Voucher code
`id`	String	Voucher ID
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Loyalty program name
`offer.id`	String	Offer id
`offer.name`	String	Offer name
`offer.public_description`	String	Offer public description
`offer.public_image`	String	Offer public image
`offer.public_name`	String	Offer public name
`source_event_id`	String	Source event ID

1 {
2   "code": "test",
3   "id": "test",
4   "loyalty_program": {
5     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
6     "name": "VIP Club"
7   },
8   "offer": {
9     "id": "29xx7df8-3cf3-4x5c-8e74-8cd00085000e",
10     "name": "RewardName",
11     "public_description": "offerdescription",
12     "public_image": "imageoffer",
13     "public_name": "offernamepublic"
14   },
15   "source_event_id": "test"
16 }

Subscription member added

Attribute name	Datatype	Description
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Loyalty program name
`member_id`	Numeric	Member ID

1 {
2   "loyalty_program": {
3     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
4     "name": "VIP Club"
5   },
6   "member_id": 123
7 }

Voucher attribution failed

Attribute name	Datatype	Description
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Loyalty program name
`rejection_error`	String	Voucher attribution error
`voucher_offer_id`	String	Voucher offer ID

1 {
2   "loyalty_program": {
3     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
4     "name": "VIP Club"
5   },
6   "rejection_error": "test",
7   "voucher_offer_id": "test"
8 }

Voucher expired

Attribute name	Datatype	Description
`code`	String	Voucher code
`id`	String	Voucher ID
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Loyalty program name
`offer.id`	String	Offer ID
`offer.name`	String	Offer name
`offer.public_description`	String	Offer public description
`offer.public_image`	String	Offer public image
`offer. public_name`	String	Offer public name

1 {
2   "code": "6c",
3   "id": "test",
4   "loyalty_program": {
5     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
6     "name": "VIP Club"
7   },
8   "offer": {
9     "id": "29xx7df8-3cf3-4x5c-8e74-8cd00085000e",
10     "name": "RewardName",
11     "public_description": "offerdescription",
12     "public_image": "imageoffer",
13     "public_name": "offernamepublic"
14   }
15 }

Subscription month anniversary

Attribute name	Datatype	Description
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Loyalty program name
`subscription.created_at`	String	Time and date of subscription creation
`subscription.loyalty_subscription_id`	String	Loyalty subscription ID

1 {
2   "loyalty_program": {
3     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
4     "name": "VIP Club"
5   },
6   "subscription": {
7     "created_at": "2025-06-10T07:09:01.696Z",
8     "loyalty_subscription_id": "2ba00576-a5a9-400d-8b34-1e21xxd3xxd3"
9   }
10 }

Tier association year anniversary

Attribute name	Datatype	Description
`created_at`	String	Tier creation date
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Loyalty program name
`tier.id`	String	Tier ID
`tier.name`	String	Tier name
`tier_group.id`	String	Tier group ID
`tier_group.name`	String	Tier group name

1 {
2   "created_at": "2025-06-10T07:09:01.696Z",
3   "loyalty_program": {
4     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
5     "name": "VIP Club"
6   },
7   "tier": {
8     "id": "67000bb5-f193-4xxb-bx58-d08dc000c12f",
9     "name": "Gold"
10   },
11   "tier_group": {
12     "id": "2exxx6ee-6x9f-400d-a85d-a312xx1a445b",
13     "name": "Medal"
14   }
15 }

Tier association updated

Attribute name	Datatype	Description
`from_tier.id`	String	Previous tier ID
`from_tier.name`	String	Previous tier name
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Loyalty program name
`source_event_id`	String	Source event ID
`tier_group.id`	String	Tier group ID
`tier_group.name`	String	Tier group name
`to_tier.id`	String	New tier ID
`to_tier.name`	String	New tier name
`upgraded`	Bool	Status of update

1 {
2   "from_tier": {
3     "id": "Initial tier identifier",
4     "name": "Initial tier name"
5   },
6   "loyalty_program": {
7     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
8     "name": "VIP Club"
9   },
10   "source_event_id": "test",
11   "tier_group": {
12     "id": "2exxx6ee-6x9f-400d-a85d-a312xx1a445b",
13     "name": "Medal"
14   },
15   "to_tier": {
16     "id": "Final tier identifier",
17     "name": "Final tier name"
18   },
19   "upgraded": true
20 }

Voucher expiration reminder

Attribute name	Datatype	Description
`code`	String	Voucher code
`expired_at`	String	Time and date of voucher expiry
`id`	String	Voucher ID
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Loyalty program name
`membership.card_id`	String	Membership card ID
`membership.created_at`	String	Time and date of membership creation
`offer.id`	String	Offer ID
`offer.name`	String	Offer name
`offer.public_description`	String	Offer public description
`offer.public_image`	String	Offer public image
`offer.public_name`	String	Offer public name
`reminder.unit`	String	Reminder unit
`reminder.value`	Numeric	Reminder value
`valid_from`	String	Time and date voucher is valid from

1 {
2   "code": "10OFF-120006789",
3   "expired_at": "2025-06-10T07:09:01.696Z",
4   "id": "fb0000b4-38fd-4006-9xc5-f7800420617e",
5   "loyalty_program": {
6     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
7     "name": "VIP Club"
8   },
9   "membership": {
10     "card_id": "ABCDE00045SS125",
11     "created_at": "2025-06-10T07:09:01.696Z"
12   },
13   "offer": {
14     "id": "29xx7df8-3cf3-4x5c-8e74-8cd00085000e",
15     "name": "RewardName",
16     "public_description": "offerdescription",
17     "public_image": "imageoffer",
18     "public_name": "offernamepublic"
19   },
20   "reminder": {
21     "unit": "week",
22     "value": 123
23   },
24   "valid_from": "2025-06-10T07:09:01.696Z"
25 }

Voucher redeemed

Attribute name	Datatype	Description
`code`	String	Voucher code
`id`	String	Voucher ID
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Loyalty program name
`offer.id`	String	Offer ID
`offer.name`	String	Offer name
`offer.public_description`	String	Offer public description
`offer.public_image`	String	Offer public image
`offer.public_name`	String	Offer public name

1 {
2   "code": "10OFF-120006789",
3   "id": "fb0000b4-38fd-4006-9xc5-f7800420617e",
4   "loyalty_program": {
5     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
6     "name": "VIP Club"
7   },
8   "offer": {
9     "id": "29xx7df8-3cf3-4x5c-8e74-8cd00085000e",
10     "name": "RewardName",
11     "public_description": "offerdescription",
12     "public_image": "imageoffer",
13     "public_name": "offernamepublic"
14   }
15 }

Balance maximum value reached

Attribute name	Datatype	Description
`balance_definition.id`	String	Balance definition ID
`balance_definition.metadata`	String	Balance definition metadata
`balance_definition.name`	String	Balance definition name
`balance_definition.unit`	String	Balance definition unit
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Loyalty program name
`source_event_id`	String	Source event ID
`value`	Numeric	Balance value

1 {
2   "balance_definition": {
3     "id": "a74cxx1d-4a96-4xx3-804e-dc3xxd9axxeb",
4     "metadata": {
5         "key": "value"
6       },
7     "name": "Event",
8     "unit": "points"
9   },
10   "loyalty_program": {
11     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
12     "name": "VIP Club"
13   },
14   "source_event_id": "test",
15   "value": 123
16 }

Voucher redeem unauthorized

Attribute name	Datatype	Description
`code`	String	Voucher code
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Loyalty program name
`offer.id`	String	Offer ID
`offer.name`	String	Offer name
`offer.public_description`	String	Offer public description
`offer.public_image`	String	Offer public image
`offer.public_name`	String	Offer public name
`reason`	String	Unauthorization reason

1 {
2   "code": "10OFF-120006789",
3   "loyalty_program": {
4     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
5     "name": "VIP Club"
6   },
7   "offer": {
8     "id": "29xx7df8-3cf3-4x5c-8e74-8cd00085000e",
9     "name": "RewardName",
10     "public_description": "offerdescription",
11     "public_image": "imageoffer",
12     "public_name": "offernamepublic"
13   },
14   "reason": "Amount falls above maximum balance amount limit"
15 }

Tier association month anniversary

Attribute name	Datatype	Description
`created_at`	String	Time and date of tier creation
`loyalty_program.id`	String	Loyalty program ID
`loyalty_program.name`	String	Loyalty program name
`tier.id`	String	Tier ID
`tier.name`	String	Tier nae
`tier_group.id`	String	Tier group ID
`tier_group.name`	String	Tier group name

1 {
2   "created_at": "2025-06-10T07:09:01.696Z",
3   "loyalty_program": {
4     "id": "27xxdd7a-af67-0020-ba65-19d60000a26e",
5     "name": "VIP Club"
6   },
7   "tier": {
8     "id": "67000bb5-f193-4xxb-bx58-d08dc000c12f",
9     "name": "Gold"
10   },
11   "tier_group": {
12     "id": "2exxx6ee-6x9f-400d-a85d-a312xx1a445b",
13     "name": "Medal"
14   }
15 }