---
title: "Configure Leaderboards"
slug: "configure-leaderboards"
updated: 2026-11-09T14:37:41Z
published: 2026-11-09T14:37:41Z
canonical: "docs.xtremepush.com/configure-leaderboards"
---

> ## 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.

# Configure Leaderboards

To create a leaderboard, go to **Ways to Earn** > **Leaderboards** and select **Create** and configure the following options.

## Leaderboard score

The **Leaderboard Score** defines how a user's score is calculated, and therefore how users are ranked in the leaderboard. When you configure the leaderboard score, set the **Progress Counter** to one of four options:

- **User Attribute value**: Users are ranked in leaderboards based on a user attribute value, like `total_tokens_won`. Select the attribute under **Score User Attribute**.
- **+1 with every event**: Users are ranked based on the number of times they trigger an event. Select the event under **Desired Action**.

Each time a user triggers that event, their score increases by 1. You can also add further conditions to the event trigger. For example, if you select a `bets_executed` event and add a requirement that its `amount` property is greater than 50, the leaderboard ranks users by how many bets over 50 they have placed.
- **Accumulative (by event field)**: Users are ranked based on the sum of a numeric field from an event. You specify an event (**Desired Action**), and then specify the **Event field path** you want to accumulate. For example, if your selected event is `bet_executed` and the field is `amount`, then users are ranked on the leaderboard based on the `amount` added up across every bet they place.

> [!TIP]
> If you want a leaderboard score that resets to 0 periodically, use the **+1 with every event** or **Accumulative (by event field)** options. See Rewards below for how the rotation period controls this.

- **Custom Expression**: Users are ranked by a mathjs formula you write yourself. The formula runs each time the specified event occurs, and combines the user's existing score with details from that event to calculate the new score.

Available variables are: `currentProgress` (the user's score before this event), `event` (the event that just occurred, including its payload), `extras` (context about the user and quest), and `storage` (read-only).

For example, `currentProgress + 1` adds one point per qualifying event.

Set **Start At** and **End At** to define when the leaderboard is active. If you leave these fields empty, the leaderboard runs indefinitely. The end date also shows in the **Ends At** column of the **Leaderboards** list.

## Tiering

**Tiering** lets you configure a single leaderboard that automatically splits into separate leaderboards for different groups of users, based on a user attribute or segment you choose.

For example, without tiering, a leaderboard with 1,000 users would rank all 1,000 users against each other. If you tier that same leaderboard by level, and you have 5 levels, it splits into 5 separate leaderboards, one per level, so users only compete against others in their own level (around 200 users each).

> [!TIP]
> Tiering is optional. If you don't need to split a leaderboard into groups, you can leave this section empty.

> [!WARNING]
> Before you set up tiering
> 
> Before you set up tiering, consider the following:
> 
> - Rewards apply per leaderboard, not per program.
>   - For example, without tiering, a leaderboard might reward position 1 with 500 tokens, positions 2 to 5 with 250 tokens, and positions 6 to 10 with 150 tokens.
>   - If you tier users into 5 leaderboards, this full set of rewards is given out 5 times over, once per leaderboard.
> - Do not tier by an attribute that can take many different values, such as total quests completed. An attribute with too many possible values can split users into a large number of small leaderboards, leading to over-rewarding, since each leaderboard pays out its own set of rewards.

## User Requirements

Specify which users are eligible to take part in this leaderboard.

- Add a requirement to define which user groups can access the leaderboard, for example `Level ≥ 3`.
- Select **Require users to opt in before they can score** if users must accept the leaderboard before they take part. You cannot change this setting after you save the leaderboard.

When enabled, users see an option to accept or decline the leaderboard in your loyalty widget. If you’re configuring a leaderboard with a rotation period, users only need to accept once and they’ll stay.

## Rewards

Specify the **Rewards** that users receive and how often these rewards are issued.

- **Rotation Period**: The **Rotation Period** determines when these rewards are given out. For example, if you select a rotation period of 1 week, users receive a reward every week for their leaderboard position.

Options range from **10 minutes** to **4 weeks**, or **Until completion**.

> [!TIP]
> If you select **Until Completion**, your users are rewarded at the **Ends At** date you specify under **Leaderboard Score**.
- **Rewards**: Select **Add Reward**, then set a **From position** and **to** range and choose a reward type. See [Loyalty Reward Types](/documentation/docs/loyalty-reward-types) for more information on the different reward types and how to configure them.

The following table shows an example reward configuration for a leaderboard

| From position | To position | Reward |
| --- | --- | --- |
| 1 | 1 | 100 tokens |
| 2 | 5 | 50 tokens and 2 quests |
| 6 | 10 | 30 tokens and 1 quest |
| 11 | 25 | 20 tokens |
| 26 | 50 | 15 tokens |
| 51 | 75 | 10 tokens |
| 76 | 100 | 2 quests |

> [!NOTE]
> What happens when a leaderboard rotates
> 
> On a leaderboard with a **Rotation Period**, users who took part in one cycle are automatically entered into the next, whether or not the leaderboard requires opt-in.
> 
> 
> 
> Each new cycle starts them at 0, or at their current attribute value on a **User Attribute value** leaderboard. They appear in the ranking from the start of the cycle and are rewarded for their final position, like any other participant.
> 
> 
> 
> When a cycle ends, its final results are saved: each participant's final score, position, and tier at the time rewards were given out. By default, only the most recent completed cycle is kept, for up to 30 days. To keep a longer history, contact your account manager. If you delete a leaderboard, its saved results are also deleted.
> 
> 
> 
> These past-cycle results do not appear in the loyalty widget or the dashboard. To show them in your own front end, use the Loyalty API:
> 
> - [Get the archived cycles of a leaderboard](https://docs.xtremepush.com/apidocs/en/get-the-archived-cycles-of-a-leaderboard) lists the saved cycles of a leaderboard, newest first.
> - [Get the current player result in an archived cycle](https://docs.xtremepush.com/apidocs/en/get-the-current-player-result-in-an-archived-cycle) returns the player's final score, position, and opt-in time in one saved cycle.
> - [Get all leaderboards for the current player](https://docs.xtremepush.com/apidocs/en/get-all-leaderboards-for-the-current-player) with `includeEnded=true` also lists leaderboards whose end date has passed.

## Presentation

Specify how the leaderboard appears to users in the loyalty widget.

- **Title**: The title of the leaderboard in the loyalty widget.
- **Description**: The description of the leaderboard displayed to users. You can use markdown formatting to style descriptions with bold, italic, or more.
- **Blocked description**: The message shown to users who do not meet the participation criteria you set. For example, if your leaderboard is only for users on level 2 or higher, the blocked description could be *You need to be level 2 or above to access and take part in the leaderboard.*
- **Score label**: The label shown in the widget for what the leaderboard is ranking users by. For example, if the leaderboard ranks users by bets made, the score label could be *Bets*.
- **Image**: Upload an image for the leaderboard.
- **Payload for event on click**: Provide a URL to direct users to a specific location on your website or app when they select the leaderboard. For example, you can add a link that takes users directly to a live betting page if your leaderboard ranks are based on bets made.

Select **Submit** to save the leaderboard.