---
title: "Manage Loyalty Events"
slug: "manage-loyalty-events"
updated: 2026-06-10T15:03:03Z
published: 2026-06-10T15:03:03Z
canonical: "docs.xtremepush.com/manage-loyalty-events"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xtremepush.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Loyalty Events

The different types of events you can use in your loyalty solution and how to configure them

The table below summarises the four types of events and where you can view them.

| Event Type | Configurable | Location |
| --- | --- | --- |
| Custom Customer Data Platform (CDP) Events | Yes | **Data Manager** > **Events** |
| Internal Events | No | **Loyalty Hub** > **Events** |
| Scheduled Events | Yes | **Loyalty Hub** > **Events** |
| User Attribute Events | No | **Loyalty Hub** > **Events** |

## Custom CDP Events

After loyalty is enabled on your project, all configured events under Data Manager are available for use in the Loyalty Hub. These are the primary events you use as in your loyalty solution to trigger reward rules, quests, and perks.

To view these events, go to the **Custom Events Sent by You** in the **Event Trigger** section when you configure any reward rule, quest, or perk.

![](https://cdn.document360.io/b056e88b-f6c1-4bd2-b5b8-08e9336a17c9/Images/Documentation/5084cc4c481048706d3aa755d26ad038df65ecaa55945aa166aa970359db03d1-Screenshot_2026-03-05_at_11.09.44(1).png)

> [!NOTE]
> The list of the Custom CDP events can only be viewed under **Data Manager** > **Events**. There is no dedicated tab in the Loyalty Hub to view the list of these events.

## Internal Events

Internal Events are pre-set events within the Loyalty hub that are triggered when users interact with your loyalty widget. For example, *ACHIEVEMENT REWARD CLAIMED* or *QUEST STARTED*.

These events appear in the Loyalty Hub under **Events** > **Internal Events**. You cannot edit these events or add new internal events.

When you configure a reward rule, quest, or perk, these events are available under **Internal Events** in the **Event Trigger** section.

![](https://cdn.document360.io/b056e88b-f6c1-4bd2-b5b8-08e9336a17c9/Images/Documentation/387af3ea5f072552710b70cbdaae959ff514750cb6f88ed494a32de25d197134-3(1).png)

Following is the list of internal events and when they’re triggered:

****List of Loyalty Events and their trigger conditions****

| Event | Trigger Condition |
| --- | --- |
| **ACHIEVEMENT_REWARD_CLAIMED** | A user successfully completes an achievement and claims the reward. |
| **CHALLENGE_COMPLETED** | This event is relevant for quests that involve multiple trigger events known as **Desired Actions**. Each **Desired Action** represents a challenge. The event triggers when a user completes a challenge. |
| **CHALLENGE_PROGRESS_UPDATED** | This event is relevant for quests that involve multiple trigger events known as **Desired Actions**. Each **Desired Action** represents a challenge. The event triggers when a user progresses through a challenge. For example, if the **Desired Action** requires five deposits, this event triggers every time a user makes a deposit until they reach five deposits. |
| **DAILY_CLAIMED** | A user selects a daily bonus button. Daily bonuses are configured when defining levels under **Ways to Earn** > **Levels**. |
| **DIRECT_REWARD_DISTRIBUTED** | A reward is sent directly to a user from the **Widget Preview** tab or the **All Users** tab. |
| **LEVEL_UP** | A user selects the level up option for manual levels. |
| **PERK_ACTIVATED** | A user activates a perk. To activate a perk, the user must have an available perk slot. |
| **PERK_DISABLED** | A user deactivates a perk. |
| **PERK_REWARDED** | A user receives a perk as a reward. |
| **PERK_UPGRADED** | A user upgrades a perk and pays the token cost. To upgrade a perk, the user must have two perks of the same level which must both be below level 5. |
| **PERK_TRIGGERED** | A user successfully completes the perk completion conditions. |
| **GAME_RULE_TRIGGERED** | A user meets a configured game rule condition. |
| **QUEST_ACCEPTED** | A user selects **Start Quest** to begin a quest. |
| **QUEST_CANCELED** | A user either dismisses an unstarted quest or cancels a quest in progress. |
| **QUEST_CLAIMED** | A user claims a reward after completing a quest. |
| **QUEST_COMPLETED** | A user completes all quest completion criteria. |
| **QUEST_LOST** | A user does not start or complete the quest within the required time. |
| **QUEST_PERIOD_COMPLETED** | This event triggers when a user completes the criteria for a recurring quest. For example, if a recurring quest requires a user to place one bet every day for five days, the event triggers each day the user successfully places a bet until the fifth day. |
| **QUEST_STARTED** | A user starts a quest. This quest is triggered along with the QUEST_ACCEPTED event. |
| **EXTERNAL_TRANSACTION_COMPLETED** | An external transaction is processed for the user. This captures details such as the transaction ID, tokens, status of success or failure, balance before, balance after, the requesting party, and labels. |
| **REDEEM_TRANSACTION_COMPLETED** | A user completes a redemption through a third party provider. The webhook backend for Tangible and Currency Conversion must return a 200 status. |
| **REDEEM_TRANSACTION_FAILED** | A redemption attempt fails on the provider side. The webhook backend for Tangible and Currency Conversion returns a status other than 200 or 201. |
| **REWARD_DISTRIBUTED** | A user receives a reward from any loyalty features such as a quest, reward rule, or achievement. |
| **REWARD_CHOSEN** | A user selects a reward. This is only applicable if a **Choose Any** reward modifier is configured. |
| **REWARD_PENDING** | The reward is queued and is awaiting a user choice. This is only applicable if a **Choose Any** reward modifier is configured. |
| **USER_CHARGE_COMPLETED** | A user completes a payment or charge via the API. |
| **USER_CREATED** | A new user account is created. |
| **LEADERBOARD_ROTATED** | A scheduled leaderboard period ends and resets. |
| **POLL_VOTE_SUBMITTED** | A user submits a vote on a poll. |
| **POLL_VOTE_CANCELED** | A user selects **Cancel** before submitting their first vote. |
| **POLL_VOTE_REVOKED** | A user selects **Revoke** to remove a previously submitted vote. |
| **ASSIGNMENT_GIVEN** | A user receives an assignment as a reward. |
| **ASSIGNMENT_ACCEPTED** | A user accepts an unstarted assignment. |
| **ASSIGNMENT_COMPLETED** | A user completes all assignment completion criteria. |
| **ASSIGNMENT_CLAIMED** | A user claims the reward after completing the assignment. |
| **ASSIGNMENT_LOST** | A user does not start or complete the assignment on time. |

## Scheduled Events

In the Loyalty Hub, you can create scheduled events that trigger at a specific time frame that you define. These timestamp events that the same payload:

```json
"day": (number) 
"dayOfweek": (number)
"dayOfyear": (number)
"hour": (number)
"month": (number)
"timezone": (string)
"unixTimestamp": (number)
"weekOfyear": (number)
"year": (number)
"type": (string)
"eventId": (string)
"namespace": (string)
"userId": (string)
```

To create these events go to **Events** > **Scheduled Events**. You must use a CRON expression to define the event schedule.

Use these events in scenarios where you want to automate user attribute changes using reward rules. Some example include:

- A weekly scheduled event that is used as a trigger for a reward rule. This reward rule resets the *weekly_bets* attribute for all users to 0.
- A monthly scheduled event that is used as a trigger for a reward rule. This reward rule sets the *user_activity* status to low for all users with a *total_quest_completed* attribute of less than 10.

To view these events when you configure a reward rule, quest, or perk, go to the under **Scheduled Events** section when selecting an **Event Trigger**.

![](https://cdn.document360.io/b056e88b-f6c1-4bd2-b5b8-08e9336a17c9/Images/Documentation/054f4af3cfe688df91fe544d0f859fe90ee3f8294e4cd2f7d1494acb47c224d1-4(1).png)

## User Attribute Events

In the Loyalty Hub, events are generated when a user’s attribute value changes. These value changes are recorded in the **All Users** tab for each user profile.

All User Attribute events have the same following payload:

```json
"new": (boolean)
"previousValue": (string/boolean/number/Array<string>)
"value": (string/boolean/number/Array<string>)
"dataType": (string)
"eventId": (string)
"namespace": (string)
"userID": (string)
```

The **previousValue** field indicates the former value of the attribute, while the **value** field indicates the new attribute value.

You can view user attribute events under **Loyalty Hub** > **Events** > **Attributes**.

You can use these events to trigger a reward rule, quest, or perk. For example, you might use a change in an *account_verification* attribute to trigger a reward rule. When the status changes from unverified to verified, a reward rule is triggered where a user receives 100 tokens.

These events are listed under **Attribute Events** when you configure a reward rule, quest, or perk.

![](https://cdn.document360.io/b056e88b-f6c1-4bd2-b5b8-08e9336a17c9/Images/Documentation/ab6534f8e61765c1086a8316cebab92672c2c2275a2e2055107cae0e10b3db9c-Screenshot_2026-03-05_at_12.59.39(1).png)