> For the complete documentation index, see [llms.txt](https://help.smartico.ai/welcome/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.smartico.ai/welcome/products/gamification-basics/tournaments/tournament-setup.md).

# Tournament Setup

This document explains the configuration specifics when creating a tournament using the Smartico BO.

Two types of tournaments can be created in the Smartico Back-Office:

1. **Tournaments with Simple Logic:** These tournaments use predefined scoring rules. You select from the available options, and the system handles the rest.
2. **Tournaments with Formula-Based Logic:** These tournaments allow you to create custom scoring rules using a formula that you design.

The only difference between these two types is how the scoring logic is applied. All other tournament settings remain the same.

{% hint style="info" %}
If multiple runs overlap, the user’s progress is counted only for the oldest active run.\
For example, if a run starts every day and lasts 5 days, there will be 5 runs active simultaneously. Even so, the user’s progress will apply only to the first (oldest) active run - not to the newer ones.
{% endhint %}

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-aa40138c93c509a5f30327fb11144025d434e8bd%2FScreenshot_23.png?alt=media&amp;token=d50945f4-d18c-4be0-93d6-2bd20550528d" alt=""><figcaption></figcaption></figure></div>

### Tournaments with Simple Logic

Tournament configurations are located in the ‘Gamification > Tournaments’ section within the Smartico Back Office. The Simple Logic Tournament configuration screen consists of the following main tabs:

* **General** - the tab with the main configurations of a given tournament, like who can see the tournament, scoring rules (pre-defined), name, description, image, image for the tournament lobby, etc.
* **Prize Pool** - used to define the prizes that will be issued to the winners of the tournament
* **Related Games** - used to add related games to the tournament
* **Runs** - showing the list of tournament 'runs' (instances) with a list of participants in every run. The concept of the 'run' is easy to understand in the example of recurring tournaments. If you have a recurring tournament that starts every Monday, you will find all instances of this tournament, with a specific list of participants and winners, in the 'Runs' tab.
* **History** - this tab shows the history of changes in the tournament configuration

#### **Tournament status**

As part of the General setup, you can define the following statuses:

* **Archived** - the tournament is not active or displayed in the gamification widget, and further changes of status are locked
* **Draft** - the tournament is not active or displayed in the gamification widget
* **Paused** - the tournament's future runs will be skipped, new players will not be able to join the tournament, current players will continue to progress in the current run, and prizes will be distributed
* **Published** - the tournament is active and displayed in the gamification widget (based on segmented criteria)

<details>

<summary>Status flow</summary>

1. When creating a new Tournament template, the default status will be **Draft.**
2. You can change **Draft** → **Published** or **Draft** → **Archived.**
3. Once Published you can change **Published** → **Paused** or **Published** → **Archived.**
4. Once Paused you can change **Paused** → **Published.**
5. You can switch between **Paused** and **Published** continuously.
6. Once **Archived** further status change will be disabled, because this status is **final.**

{% hint style="info" %}
*Archiving a tournament won't stop its active runs. To cancel them, you need to navigate to the Runs tab. Otherwise, they will finish as setup.*
{% endhint %}

</details>

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-f034fe4e3241ea0d5961c9666ba4cb0f7b2cb307%2FScreenshot_70.png?alt=media" alt=""><figcaption></figcaption></figure></div>

### Formula-based scoring logic

You can create custom scoring logic using the new ‘Formula-based’ tournament type. This option is accessible through the Creation Wizard. Once selected, you'll have access to the Formula Builder, where you can design your own scoring rules based on specific events and properties.

#### How It Works:

**Step 1.** Create a Formula-Based Tournament:\
When creating the tournament, select ‘Formula-based Tournament’ from the wizard.

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-f49e8a19fea3653f3600081440cf519cc2cf722c%2FScreenshot_24.png?alt=media" alt=""><figcaption></figcaption></figure></div>

**Step 2.** Create a Scoring Formula:\
After saving the template, go to the ‘Scoring Formulas’ tab and click on the ‘Create’ button to start creating the scoring formula.

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-da5c0302494846e6d5477deeda9012e10bbd6ed3%2FScreenshot_25.png?alt=media" alt=""><figcaption></figcaption></figure></div>

**Step 3.** Define Your Formula:\
Give your formula a name, and select the event and the conditions on which it will be based.

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-9cbbc4a6c159f6daf273532366b614e7c8efb4f1%2FScreenshot_26.png?alt=media" alt=""><figcaption></figcaption></figure></div>

**Step 4.** Open the Formula Builder:\
Use the Formula Builder to construct your formula using the properties related to the chosen event.

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-5f6aaaf3f9d19ca5dffa97052db23958625aa65a%2FScreenshot_27.png?alt=media&amp;token=1f0cb007-d70c-4d1a-ac1a-6408a165773e" alt=""><figcaption></figcaption></figure></div>

**Step 5.** Save Your Formula:\
Save the formula once you're satisfied with the logic.

{% hint style="success" %}
If a player's score is non-zero (including negative values) and they meet all the conditions, they will be successfully registered for the tournament. However, if the score is exactly 0, the player will not be registered, even if all other conditions are met.
{% endhint %}

#### Managing Multiple Formulas:

You can create multiple formulas and assign a priority level to each. The formula with the highest priority (1 being the highest) will be executed first. Lower-priority formulas (2, 3, 4, etc.) will be executed afterward.

For example, let's say you create a formula based on a ‘Deposit’ event that awards 10 points for every deposit over 100 EUR. You then create a second formula based on a ‘Casino Bet’ event, awarding 5 points for every bet over 10 EUR, and here is what will happen:

\- If a player deposits more than 100 EUR, they receive 10 points.

\- If a player places a casino bet of over 10 EUR, they receive 5 points.

\- If both actions are performed, the player receives a total of 15 points.

<div><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-d48b6b6f85b09b6d468d8144dbd1e8c43a7763bf%2FScreenshot_31.png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-71edc1c0adb7684c71585f769fe4795afd8bc40b%2FScreenshot_30.png?alt=media" alt=""><figcaption></figcaption></figure></div>

{% hint style="danger" %}
If there are overlapping formulas, the one with the highest priority will be executed. Overlapping could happen if you create 2 formulas with the same event and conditions.
{% endhint %}

### Score accumulation and visualization rules

Beyond how individual scores are calculated, tournament templates provide options for accumulation and leaderboard formatting:

* **Score accumulation rule:**
  * **Default:** Scores accumulate additively on each qualifying event and can include negative values.
  * **No negatives:** Scores accumulate additively, but total scores cannot drop below 0.
  * **Take Max value:** Non-additive scoring where only the player's single highest achieved score is recorded on the leaderboard.
* **Score visualization / rounding rule:** Allows formatting displayed scores on the leaderboard using **Floor** (e.g., dividing scores by a set divisor) or **Square root**. Leaderboard ranking is always calculated using exact raw scores.
* **Tie-breaking:** When two or more players achieve the exact same score, rank priority is given to the player who reached that score first (earliest update timestamp).

### Players with different currencies

If your players bet in different currencies, turn on the **Convert bet and win amounts to the label currency** setting in **Label settings**. Then the bet and win amounts of casino and sport events are converted from the player's wallet currency to the label's default currency before the score is counted, so players are ranked fairly. The setting is off by default; ask your Success manager to change it.

### Players who are allowed to register and see the tournament

You can define two segments of players:

* **Who can see the tournament** - will define the segment of users who will see the tournament
* **Who can register in the tournament** - segment of users who can register. If the user can see but cannot register for the tournament, they will see an error message.

### Ranking Type (Individual vs Clan Tournaments)

By default, tournaments rank **Individual Players**. When the Clans product is enabled, operators can configure **Clan Tournaments** where players compete collectively, scores are aggregated per clan, and prizes are distributed to winning clans and their members. For detailed setup, see the [Clans & Clan Tournaments](/welcome/products/gamification-basics/tournaments/clans-and-clan-tournaments.md) guide.

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-13a634f655f3488c6c4d34178d95ab92c8147e07%2FScreenshot_58.png?alt=media" alt=""><figcaption></figcaption></figure></div>

### Registration rules and tournament time

There are also settings that define the main rules for entering the tournament.

1. **Registration type:**

* Free opt-in - Players can join the tournament free of charge
* Buy-in with points - the player is paying for opt-in with gamification points
* Opt-in and Manual approval - the player can opt in to the tournament, but must be approved by the operator in the Smartico back office. This opt-in logic can be used for closed tournaments, where, behind the scenes, the operator deducts real money from the user's balance. A money deduction can also be automatic if the operator's platform provides an integration API to the wallet.
* Qualification rule - the qualification rule itself can be any event happening for the end-user, and can also include restrictions on the event's attributes. In the case of "Requires qualification", the user must complete the qualification action; after that, he will be able to register and participate in the tournament.\
  \
  **Note:** the system will handle 2 cases: the user can first register and then complete the qualification action, or he can complete the qualification action and then confirm registration.

  A message for non-matching registration conditions will inform the user of the required action.
* Auto (all users) - Players are automatically entered on their first qualifying activity without needing manual opt-in. This option requires the "Allow Auto opt-in tournaments" label setting to be enabled.
* Buy-in with gems or diamonds - Players pay gamification gems or diamonds to enter (available when Gems & Diamonds are enabled for the label).

In 'Opt-in and Manual approval' and 'Requires qualification' tournaments, players who are still waiting for approval or qualification are shown on the leaderboard while the **Show pending registrations on the tournament leaderboard** setting in **Label settings** is on (default). Turn it off to show only approved players.

2. **Allow late registration** - if allowed, players can register after the tournament is already in progress.
3. **When to run** - is defining if it's a one-time tournament, starting on a specific date/time or the tournament is repeating according to a defined schedule. The 'Tournament duration' can be up to the **Max tournament duration, days** setting in **Label settings** (default 90 days); ask your Success manager to change it.
4. **Minimum and maximum number of players:** if the tournament does not get enough players, it will be canceled automatically. In such a case, the buy-in amount, if defined as gamification points, will be returned to the player. Once the maximum number of players is reached, new player registrations are no longer allowed. It’s recommended to have at least 2 users, so if only 1 user joins a tournament, he will be the only participant and the only winner. Neither number can be higher than the **Max players per tournament** setting in **Label settings** (default 200,000); ask your Success manager to change it.

<div><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-872b0678af6279229f00398a4a69c842f4eb48e2%2FScreenshot_71.png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-25a3c7aa1140c4612763f6ee844bd4c0cc092083%2FScreenshot_72.png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-7c17251c812093b0f169bdc4a051eef38149a933%2FScreenshot_73.png?alt=media" alt=""><figcaption></figcaption></figure></div>

### Tournament visibility before starting and after finishing

You can also define when a tournament becomes visible and how long it remains visible after it finishes. For recurring tournaments, it's important to properly configure 3 parameters: tournament duration, visibility before the start, and visibility after the finish. For example:

* The tournament is set to start every Monday at 10 AM and last for 5 days, finishing at 10 AM on Saturday.
* Visibility before the start can be set to 1 day, which means that the tournament will be announced and become visible at 10 AM on Sunday
* The visibility 'after finishing' can be set to 2 days. This means that the finished tournament will be visible till 10 AM on Monday

In such a scenario, there will be an overlapping period from 10 AM Sunday to 10 AM Monday, during which players will see 2 instances of the tournament.

The 'Keep showing in lobby, after finishing' value cannot be more than the **Max days to show a finished tournament** setting in **Label settings** (default 10 days); ask your Success manager to change it.

{% hint style="info" %}
If a Tournament is moved to 'Archived' status while there is an ongoing run, the current (ongoing) run will be completed, and the prizes will be issued.
{% endhint %}

### Prize pool configuration

The prize pool can be defined per place (e.g., 1st, 2nd ) or for a range of places (e.g., 5-10). Prizes can be of 3 types:

* Gamification points
* Bonus (in case the operators' platform is providing an API for issuing the bonus)
* Tangible prize
* Gems & Diamonds (available when Gems & Diamonds are enabled on the label)
* Mini Game attempts (such as Spin the Wheel, Lootbox, or MatchX)
* Prize Drops and Raffle Tickets
* Avatar rewards and Level progression changes

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-3d14454be8931e80c81f1502ff28feaca6cb44d6%2FScreenshot_74.png?alt=media&amp;token=41408dc7-ce7e-414e-8dfa-b2ec4aca7fc8" alt=""><figcaption></figcaption></figure></div>

At the end of the tournament, all players may receive (if configured) marketing communications informing them of the tournament name, their winning position, and the prize.

The leaderboard shows the top players up to the **Max number of tournament places** setting in **Label settings** (default 20). Players outside this top still see their own place. If prizes go to more places than this, all winners still get their prizes, but not all of them are shown on the leaderboard. Ask your Success manager to raise the setting.

### Hide users who did not meet the minimum score from the leaderboard

You can hide users who haven't met the minimum score required to qualify for the Tournament from the leaderboard. By default, this feature is disabled, meaning all users, regardless of their score, will appear on the leaderboard. When enabled, only players who meet the minimum score will be displayed, along with the current player. If the current player hasn’t reached the minimum score, their rank will not be shown.

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-4397672f1269641ec23648881d9772ba46b63e59%2FScreenshot_74.png?alt=media" alt=""><figcaption></figcaption></figure></div>

### Happy hours

Happy Hours allow you to award players extra points on specific days and during specific hours, using UTC time as the standard. You can define which days the bonus applies and set a multiplier to increase the points earned. If you specify a day but omit the hours, the multiplier will apply for the entire day. If you include both the day and a time range, the multiplier will apply only during that window. This gives you flexibility to create full-day events or short bursts of bonus activity, depending on your goals.

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-1288bf637556cdd00cce3eff8ccd924746d8e585%2Fimage.png?alt=media" alt=""><figcaption><p>BO: Happy hours setup in Tournaments</p></figcaption></figure></div>

### Limiting Player Actions in a Tournament

To restrict player actions in a tournament, use the ‘Limit players’ actions in a tournament’ option and specify the desired limit value. Note that in Formula-Based tournaments, the limit is enforced as soon as additional conditions are met, even if the player hasn’t fulfilled the formula's calculation criteria.

**Example Scenario:**

* Tournament Setup:
  * Limit: Casino Bet Count = 3
  * Additional Condition: Last game played = Game A
  * Formula calculation: If the player’s bet amount ≥ 10, award 10 points
* Use Case:\
  A player places three bets on Game A. Regardless of whether the bet amount is greater than, less than, or equal to 10, the player reaches the set limit. Their status changes to ‘Finished’, preventing further progress in the leaderboard.

<div><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-02082ffaea2f9a3c48d400cb5c7f60805cf15384%2FScreenshot_17.png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-e56dbd5a90dab9ccd72ea3ec59da59a3df7a1f7c%2FScreenshot_18.png?alt=media" alt=""><figcaption></figcaption></figure></div>

### Finalizing a tournament

After finishing, every tournament has a 'finalization' status. The need for this status stems from the delayed delivery of events from the casino/sports platform. Even with real-time delivery of events from the platform to the Smartico system, there could be small delays that will lead to the following situations:

* The player makes a bet at 10:59 PM, and it is not delivered to Smartico at that minute
* The tournament is finishing at 11:00 PM and doesn't count the place bet
* The placed bet is finally delivered to Smartico at 11:01 PM, but the tournament is already over and the winners have been announced.

To mitigate this problem, tournaments have a 'Finalization' status, which lasts for the period specific to the integrated platform. The length of this period is chosen to ensure that all events are delivered to Smartico and to enable a fair selection of winners.

{% hint style="info" %}
Please contact your Customer Success Manager regarding the finalization period defined for your integration
{% endhint %}

### Multiple ‘Happy hours’ per day in Tournaments

You can set multiple Happy Hours per day in Tournaments.\
For example, you can configure a Happy Hour on Monday from 10:00–16:00 (x2 multiplier) and another from 16:00–22:00 (x3 multiplier).

{% hint style="success" %}
Keep in mind that if time periods overlap, the system will apply the first matching time range.\
Example:

* Tue 00:00–15:00 → x5
* Tue 12:00–18:00 → x10

Between 12:00–15:00, the system will use x5; between 15:00–18:00, x10; and after 18:00, x1.
{% endhint %}

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-4c6fbb299ef51316739afb0f068174df3e8ae942%2FScreenshot_3.png?alt=media" alt=""><figcaption><p>BO: Happy hours in Tournaments</p></figcaption></figure></div>

### Activity period for scoring formula

You can set an Activity Period for tournament scoring formulas. It’s disabled by default. When enabled, you can add a start and end date, and the formula will be applied only within this time window. Any actions made outside the selected period won’t count; players will not be able to progress in the tournament and earn points.

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-d9822a17d160b6f0c4e6016dd6d8464cdb8cdb70%2FScreenshot_13.png?alt=media" alt=""><figcaption></figcaption></figure></div>

### Inform players about their positions in the middle of the tournament

Set up the schedule and send a special event "**Tournament: leaderboard update**" (tournament\_leaderboard\_update)

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-acb765982670aad7f0ee777c0c94da17f558d933%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure></div>

This is ideal for sending targeted campaigns - such as notifying the Top 10 players of their current standing to drive late-stage competition. Once enabled, you can choose from three scheduling modes:

* Daily: Sends the event at a set time each day.
* Days of the Week: Choose specific days + time (e.g., weekends only).
* Specific Dates & Times: Set specific date or dates and times

Also, you can define how many top-ranked users should receive the event based on your chosen schedule. For example, you can configure the system to only trigger the '**Tournament: leaderboard update**' event for the top 20 players based on current standings at the scheduled time.

The event is coming with '**tournament\_leaderboard\_position**' property, so you can build a communication like

```soy
Hi, your position in the tournament is {{event.tournament_leaderboard_position}}
```

### Frequently Asked Questions (FAQ)

**Q: How do I notify tournament winners with automated messages or CRM journeys?**\
**A:** When a tournament instance finishes, the system automatically triggers the **Tournament: Win** event for all winning participants (and the **Tournament: Lose** event for non-winning participants if configured). You can create CRM Automation Rules or Journeys triggered by the "Tournament: Win" event to automatically send private inbox messages, emails, or push notifications to winners.

**Q: Which dynamic tags are available for tournament communication templates?**\
**A:** In communications triggered by tournament lifecycle events, you can include dynamic tags to display the player's winning position, the prize awarded, the tournament name, description, and end time.

**Q: Why are some players who performed actions not appearing as registered in Auto tournaments?**\
**A:** In Auto-registration tournaments, a player is only registered upon earning a non-zero score. If a player's initial qualifying action results in exactly 0 points, the system does not register them until an action producing points occurs.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.smartico.ai/welcome/products/gamification-basics/tournaments/tournament-setup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.