---
title: "Configure a Tournament"
slug: "configure-a-tournament"
updated: 2026-09-16T15:04:29Z
published: 2026-09-16T15:04:29Z
canonical: "docs.xtremepush.com/configure-a-tournament"
---

> ## 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 a Tournament

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

## Leaderboard Score

The **Leaderboard Score** section defines how a user's score is calculated in your tournament, and therefore how users are ranked. Set the **Progress Counter** to one of three options:

- **User Attribute value**: The tournament ranks users based on the value of a user attribute. Select the attribute under **Score User Attribute**. For example, if you select a `total_tokens_won` attribute, the tournament ranks users by their total tokens won.
- **+1 with every event**: The tournament ranks users based on a user action (event). Select the event under **Desired Action**. Each time a user triggers that event, their score increases by 1. You can add a requirement to count only qualifying occurrences of the event.
- **Accumulative (by event field)**: The tournament ranks users based on the sum of a numeric field from an event. Select the event under **Desired Action**, add an optional requirement, and enter the **Event field path** for the numeric field to add up, for example `$.body.amount`.
- **Custom Expression**: Users are ranked by a mathjs formula you write yourself. The formula runs each time the desired a 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.

## Tiering

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

For example, without tiering, a tournament with 1,000 users would rank all 1,000 users against each other. If you tier that same tournament by level, and you have 5 levels, it splits into 5 separate tournaments, 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 tournament 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 tournament, not per program.
>   - For example, without tiering, a tournament might reward position 1 with 500 tokens, positions 2 to 5 with 250 tokens, and positions 6 to 10 with 100 tokens.
>   - If you tier users into 5 tournaments, this full set of rewards is given out 5 times over, once per tournament.
> - 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 tournaments, leading to over-rewarding, since each tournament pays out its own set of rewards.

## Cycle and Timing

- **Start At** and **End At**: Define when the tournament runs.

## Participation

Tournaments require opt-in by design:

- **Require users to opt in before they can score** is mandatory for tournaments. When you're configuring leaderboards, this setting is optional. Users see an option to accept or decline the tournament in your loyalty widget before their activity counts.
- Add a requirement to define which user groups can access the tournament, for example `Level ≥ 3`.

## Rewards

The **Rewards** section defines what users receive based on their final rank when the tournament ends.

- **Rotation Period**: Leave this field empty. Leaving the field empty means rewards are distributed once, when the tournament ends, and the tournament doesn't repeat.
- Select **Add Reward**, then set a **From position** and **to** range and choose a reward type. See [Loyalty Reward Types](/docs/en/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 tournament:

| From position | To position | Reward |
| --- | --- | --- |
| 1 | 1 | 500 tokens |
| 2 | 5 | 250 tokens |
| 6 | 10 | 100 tokens |
| 11 | 25 | 50 tokens |
| 26 | 50 | 1 quest |

## Presentation

This section defines how the tournament appears to users in the loyalty widget.

- **Title**: The title of the tournament as it appears to users.
- **Description**: The description of the tournament displayed to users. Supports markdown formatting.
- **Blocked description**: The message shown to users who do not meet the participation criteria you set.
- **Score label**: The label for the score you configured, for example "Bets placed".
- **Image**: Upload an image for the tournament.
- **Payload for event on click**: Provide a URL to direct users to a specific location when they select the tournament.

Select **Submit** to save the tournament.