> For the complete documentation index, see [llms.txt](https://docs.rafflex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rafflex.io/additional-settings/leaderboards.md).

# Leaderboards

Leaderboards let your customers compete for prizes by earning points through Instant Wins. Here's how to set up and manage leaderboards on your competitions.

***

### Turn On Leaderboards

Leaderboards are switched off for new sites. Turn them on once for your whole site, then add a leaderboard to each competition you want one on.

1. In the **admin panel**, find the **Content** group in the left-hand menu and click **Settings**.
2. In the Settings side menu, click **Product**.
3. Switch on **Enable Leaderboards**.
4. Click **Save Settings**.

Each competition now has a **Leaderboard** section. Nothing changes on your site until you enable a leaderboard on a competition (see below).

{% hint style="warning" %}
You cannot switch **Enable Leaderboards** off while any active competition with leaderboard prizes is still running, or ended in the last 7 days. This makes sure every leaderboard pays its final prizes. If you try, the setting will not save and you will see which competitions are holding it on.

To switch off sooner, turn the leaderboard off on each of those competitions first. Any leaderboard prize not yet paid on a competition will not be paid once its leaderboard is off.
{% endhint %}

***

### How Leaderboards Work

A leaderboard adds a competitive layer to a competition. You choose which [Instant Wins](/create-your-first-raffle/add-instant-wins.md) award points. Every time a customer wins one of those Instant Wins, the points are added to their score on a leaderboard shown on the competition page. When the leaderboard period ends, the top players win the leaderboard prizes you have set up.

Here is the flow:

1. You switch on **Enable Leaderboard** on a competition and choose how long each leaderboard period lasts.
2. You add **Leaderboard Prizes** for the top positions.
3. You choose which Instant Wins award points, and how many.
4. Customers buy tickets. Whenever one of their tickets wins a points-awarding Instant Win, they score those points.
5. The competition page shows the live standings, so customers can see where they rank.
6. When the period ends, the standings are locked in, winners are recorded and site credit prizes are paid automatically.

The leaderboard runs alongside your main draw. The draw winners are still picked at random from every ticket, and a draw winner can also hold a leaderboard place. If you want the leaderboard prizes to be the only end prizes, see [Leaderboard Only Competitions](#leaderboard-only-competitions).

{% hint style="info" %}
Points are scored when a customer wins a points-awarding Instant Win, not for simply buying a ticket. Each winning Instant Win ticket adds its points once.
{% endhint %}

***

### Enable a Leaderboard

1. In the admin panel, click **Competitions** in the left-hand menu.
2. Click the competition you want to add a leaderboard to (or click **New Competition** to create one).
3. Scroll down the form, past the switches such as **Add To Slider** and **Auto draw**, until you reach **Enable Leaderboard**.
4. Switch **Enable Leaderboard** on. The leaderboard settings and the **Leaderboard Prizes** section appear underneath.
5. Choose your **Leaderboard Duration**, **Reset Time** (Daily and Weekly only) and **Tiebreaker**. Each one is explained below.
6. Add your prizes (see [Add Leaderboard Prizes](#add-leaderboard-prizes)).
7. Read the **How this leaderboard pays out** summary to check it does what you expect.
8. Click **Save changes** at the bottom of the page (or **Create**, if this is a new competition).

Under the switch, the form explains: *"Adds a points leaderboard on top of the draw. Players earn points from the Instant Wins you mark as awarding points, and the top-ranked players take the Leaderboard Prizes below. The draw winners are picked separately, unless Draw Winner Quantity is 0."*

{% hint style="info" %}
**Save the competition before you set up points.** The points options on your Instant Wins only appear once the competition has been saved with **Enable Leaderboard** switched on.
{% endhint %}

***

### Choose a Duration

**Leaderboard Duration** controls how long each leaderboard period lasts before the board resets. You have three options:

| Option                                                                | How it works                                                                                                                                                                                                         |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Match Competition (one board, pays out when the competition ends)** | One leaderboard runs for the whole competition. There are no resets, no countdown and no period selector. The standings are locked in and prizes are awarded when the competition ends. This is the simplest option. |
| **Daily (resets once every 24 hours)**                                | Each period lasts 24 hours and resets at your **Reset Time**. When a period resets, its prizes are paid out and the board starts again from zero for the next period.                                                |
| **Weekly (resets once every 7 days)**                                 | Each period lasts 7 days and resets at your **Reset Time**. When a period resets, its prizes are paid out and the board starts again from zero for the next period.                                                  |

{% hint style="info" %}
Daily and Weekly periods do not follow calendar days or weeks. They run in a repeating 24 hour or 7 day cycle that starts from your competition's start date and your **Reset Time**. For example, a Weekly leaderboard on a competition that starts on a Thursday resets every Thursday, not every Monday.
{% endhint %}

#### Reset Time (Daily and Weekly only)

**Reset Time** is the time of day a Daily or Weekly leaderboard resets. It starts at **00:00** (midnight), but you can pick any time. For example, choosing **20:00** means each period ends at 8pm, which is a great time to announce your leaderboard winners.

#### Reset Schedule

When you choose Daily or Weekly, a **Reset Schedule** line appears. It shows exactly when the first reset will happen, for example **First resets Fri 10 Oct at 20:00, then every day** (or **then every 7 days** for Weekly). Use it to double check the schedule before you save.

The first reset happens at your **Reset Time** on the day after the competition starts (Daily), or on the same day of the following week (Weekly). If the competition has already started when you switch the leaderboard on, it counts from the day you save instead. Everything scored before that first reset counts towards the first period, so the very first period can be a little shorter or longer than the ones after it. For example, a Daily leaderboard on a competition that starts on Thursday at 2pm with a **Reset Time** of 20:00 first resets on Friday at 20:00.

{% hint style="warning" %}
**The schedule locks once it is saved.** After you save a competition with a Daily or Weekly leaderboard, **Leaderboard Duration** and **Reset Time** are greyed out and can no longer be changed. Once the first reset has passed, the **Reset Schedule** shows **Resets every day** (or **Resets every 7 days**) with the date and time of the next reset. This keeps every customer's points in the period they were scored in. Changing the competition's start date later does not move the schedule either, so check it carefully before you save.
{% endhint %}

{% hint style="info" %}
A **Match Competition** leaderboard can still be switched to Daily or Weekly until the first points are scored. Once anyone has scored, the duration is locked. On some older leaderboards you may see the message *"This board already has recorded entries, so its schedule can't be changed"*. These boards keep resetting at midnight (every day, or every Monday for Weekly), and the **Reset Time** has no effect on them.
{% endhint %}

***

### Set the Tiebreaker

When two or more players have the same number of points, the **Tiebreaker** decides who ranks higher. Every position in the leaderboard table is numbered separately, so customers never see two players sharing the same rank.

| Tiebreaker                                   | How it works                                                                                                                                                                                                                       |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **First to Score (earliest scorer wins)**    | The player who scored their first points earliest ranks higher. If Player A scored their first points at 8am and Player B at 9am, Player A ranks above Player B. This rewards players who get involved early. This is the default. |
| **Most Tickets (highest ticket count wins)** | The player with the most paid tickets in the competition ranks higher. If Player A has 10 tickets and Player B has 3, Player A ranks above Player B. This rewards players who have bought more tickets.                            |

{% hint style="warning" %}
**Most Tickets** counts all of a customer's paid tickets in the competition, not just tickets bought during the current Daily or Weekly period. A customer who bought heavily earlier in the competition carries that advantage into later ties.
{% endhint %}

Prizes follow the tiebreaker order. If three players are tied on points, the tiebreaker decides who finishes 1st, 2nd and 3rd, and each receives that position's prize.

***

### How This Leaderboard Pays Out

Below the settings, a **How this leaderboard pays out** box sums up in plain English what will happen with the options you have chosen. It updates as you change the settings, so read it before you save. It covers three things:

|                                | What the summary tells you                                                                                                                                                                                                                               |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **When prizes are awarded**    | For **Match Competition**, the standings lock and prizes are awarded when the competition ends, whether or not the draw has run. For **Daily** and **Weekly**, each period pays out within a minute of its reset, then the board starts again from zero. |
| **How prizes are paid**        | Site credit prizes are paid into the winners' wallets automatically. Any other prize is marked as paid by you from the **Leaderboard Winners** tab.                                                                                                      |
| **How it works with the draw** | If **Draw Winner Quantity** is 1 or more, the draw winners are picked at random from every ticket and can also hold a leaderboard place. If it is **0**, the competition is leaderboard only (see below).                                                |

***

### Leaderboard Only Competitions

You can run a competition where the leaderboard prizes are the only end prizes, with no main draw at all.

1. Switch **Enable Leaderboard** on and set up your prizes as normal.
2. Make sure **Auto draw** is switched off, as it needs at least one draw winner.
3. Set **Draw Winner Quantity** to **0**. The form describes this as *"0 means no draw: leaderboard prizes only."*
4. Click **Save changes**.

The payout summary then confirms: *"With 0 draw winners this is a leaderboard-only competition: no draw takes place, the leaderboard prizes are the only end prizes, and the results page lists it under Leaderboard rather than Winners."*

Once the competition ends, it goes straight into your Results page without waiting to be drawn. Its card shows **Ended** with the end date and **Leaderboard** with the number of prizes awarded, followed by each position with the winner's name and prize.

{% content-ref url="/pages/CObOV4NyT8LpbYGo0Gf1" %}
[Results and Winners Pages](/customise-your-site/manage-your-pages/results-and-winners-pages.md)
{% endcontent-ref %}

***

### Add Leaderboard Prizes

Prizes are set once per competition and reused for every leaderboard period. The same prizes apply whether the leaderboard runs daily, weekly or for the whole competition. Only the top players receive a prize, one player for each prize you create.

1. In the **Leaderboard Prizes** section of the competition, click **Add Prize**.
2. Optionally upload a **Prize Image** (PNG or JPG, up to 512KB). It is shown on the prize card on your competition page.
3. Enter the **Rank** (1 for 1st place, 2 for 2nd place, and so on, up to 100).
4. Enter a **Prize Description**, for example "£100 Site Credit" or "AirPods Pro".
5. If the prize is site credit, switch on **Site Credit** and enter the **Payout Amount** (see below).
6. Click **Add Prize** again for each extra position you want to reward.
7. Click **Save changes**.

The section explains: *"Define prizes for top leaderboard positions. Prizes with a payout are awarded automatically when the period ends."*

{% hint style="warning" %}
**Number your ranks 1, 2, 3 and so on, with no gaps or repeats.** Prizes are handed out in rank order: the top player gets the lowest rank number, the next player gets the next one, and so on. If you skip a number (for example 1, 2 and 5), the 3rd placed player receives the rank 5 prize.
{% endhint %}

#### Site Credit prizes

Switch on **Site Credit** when you want the prize paid automatically. The form explains: *"Automatically pay the winner when the period ends."* A **Payout Amount** box then appears for you to enter the amount of credit.

When the period ends, the credit goes straight into the winner's wallet with no action needed from you, and the winner is marked as paid. The wallet transaction reads, for example, *"Leaderboard 1st place prize for \[Competition Name]. Competition Period: \[start] to \[end]."* See [Site Credit and Wallets](/additional-settings/site-credit-and-wallets.md) for how customers use their credit.

Leave **Site Credit** off for anything you will send yourself, such as a physical prize or a cash transfer. You then mark it as paid once it has been sent (see [Managing Leaderboard Winners](#managing-leaderboard-winners)).

{% hint style="info" %}
If a period has fewer scoring players than you have prizes, the extra prizes simply go unawarded for that period.
{% endhint %}

***

### Configure Instant Win Points

Not every Instant Win needs to award points. You choose which ones count towards the leaderboard and how many points each one is worth. Points can be from 1 to 10,000.

{% tabs %}
{% tab title="When creating Instant Wins" %}

1. Open the competition and click the purple **Instant Wins** button at the top of the page.
2. Click **Add Instant Win** and fill in the prize as normal.
3. Switch on **Leaderboard Points** on that row.
4. Enter the number of **Points** the winner earns (it starts at 1).
5. Repeat for each prize, then click **Create Instant Wins**.

See [Add Instant Wins](/create-your-first-raffle/add-instant-wins.md) for the rest of the builder.
{% endtab %}

{% tab title="On an existing Instant Win" %}

1. Open the competition and scroll down to the tabs below the form.
2. Open the **Instant Wins** tab.
3. Click **Edit** next to the Instant Win you want to change.
4. Switch on **Award Leaderboard Points** (*"Award points to the leaderboard when this instant win is revealed."*).
5. Enter the **Points Value** (*"Number of points awarded for this instant win."*).
6. Click **Save changes**.

To stop an Instant Win awarding points, switch **Award Leaderboard Points** off and save.
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
The points options only appear on competitions that have been saved with **Enable Leaderboard** switched on. If you cannot see them, enable the leaderboard on the competition and save it first.
{% endhint %}

{% hint style="info" %}
**Make some prizes worth chasing.** You can give different Instant Wins different point values. For example, a big prize could award 100 points while smaller prizes award 10, which makes the leaderboard more exciting to follow.
{% endhint %}

{% hint style="info" %}
Changing an Instant Win's points only affects wins from then on. Points that customers have already scored stay as they were.
{% endhint %}

{% hint style="info" %}
If you cancel an order, any leaderboard points the customer earned from that order's Instant Wins are removed automatically. If that period has already paid out, the winners already awarded stay as they are.
{% endhint %}

***

### What Your Customers See

When a leaderboard is enabled, a **Competition Leaderboard** section appears on the competition page, both while it is running and after it has ended. It includes:

* **Prize cards** for each leaderboard prize, showing the image, the position (for example **1st Place**) and the description. On mobile the cards scroll sideways. On desktop the top 3 are shown, with a **Show All Prizes** button if you have more.
* **Leaderboard Resets In** (Daily and Weekly only), a countdown in days, hours, minutes and seconds to the next reset, with a line such as **Resets daily at 8:00pm** or **Resets Thursdays at 8:00pm**.
* **Your Current Position** (logged in customers who have scored), showing their rank and points for the current period.
* **Period** buttons (Daily and Weekly only), to switch between **Current** and the most recent finished periods.
* **The leaderboard table**, showing **Rank**, **Player** and **Points**. The top 3 have gold, silver and bronze badges. A logged in customer's own row is highlighted and marked **You**.
* **Load More**, to show more players beyond the first 10 (up to 100 players in total).
* **Last updated**, showing how recently the standings were refreshed.

Player names follow your **Winners Name Display** setting (in **Settings**, then the **User Experience** tab), so you can show display names, first name and last initial, full names, or "Anonymous". Before anyone has scored, the table says *"No points scored yet. Be the first to reveal an instant win!"*

{% hint style="info" %}
Customers do not need to be logged in to view the leaderboard. Once a period has finished (or a Match Competition leaderboard has been finalised), each winner's prize is shown next to their name in the table.
{% endhint %}

***

### When Prizes Are Awarded

You do not need to do anything for prizes to be awarded. RaffleX handles it automatically:

* **Daily and Weekly:** each period is finalised shortly after it resets. A period where nobody scored is skipped.
* **Match Competition:** the leaderboard is finalised shortly after the competition ends, whether it reaches its end date or sells out. If you draw the main winners yourself after the competition has ended (with a [live draw](/drawing-winners/truenorth-live-stream-draws.md) or a [manual draw](/drawing-winners/manual-draw.md)), the leaderboard is finalised at the same moment.

When a period is finalised:

1. Players are ranked by total points, then by your tiebreaker.
2. The top player receives the first prize, the next player the second prize, and so on, until the prizes run out.
3. Each winner appears in the **Leaderboard Winners** tab.
4. Site credit prizes are paid into the winner's wallet straight away and marked as paid. Other prizes stay unpaid until you mark them.

{% hint style="warning" %}
**Keep the competition switched on until its leaderboard has paid out.** Prizes are only awarded automatically for active competitions, and a Match Competition leaderboard also needs at least one prize set up. If a Daily or Weekly competition ends part way through a period, that last period pays out at its normal reset time.
{% endhint %}

{% hint style="info" %}
RaffleX does not send leaderboard winners an email. Let your winners know yourself, for example by contacting them directly or announcing the results on social media.
{% endhint %}

***

### Managing Leaderboard Winners

After a period has been finalised, you can see and manage its winners in the admin panel.

1. Click **Competitions** and open the competition.
2. Scroll down to the tabs below the form and open **Leaderboard Winners**.

The table shows each winner's **Period**, **Rank**, **Winner** name, **Points**, **Prize** and a **Paid** or **Unpaid** badge. Paid winners are shown in green. From here you can:

* **Mark Paid** on a winner once you have sent a prize yourself.
* **Mark Unpaid** to reverse it if you marked a prize by mistake.
* **View User** to open the winner's customer account in a new tab, so you can find their contact details.
* Tick several winners and choose **Mark Paid** from the bulk actions to update them all at once.
* Use the **Paid** filter to show only **Paid** or **Unpaid** winners, so you can see which prizes still need sending.

{% hint style="info" %}
Site credit prizes are already marked as paid when they are awarded. You only need to mark winners as paid for prizes you fulfil yourself, such as physical items or cash transfers.
{% endhint %}

#### Archive Previous Period (Daily and Weekly)

Daily and Weekly leaderboards pay out on their own. If you ever need to finalise a finished period straight away, click **Archive Previous Period** at the top of the **Leaderboard Winners** tab and confirm. RaffleX finalises any recently finished period that has not been paid out yet and shows **Period Archived** with the dates. If there is nothing to do, you see **No Period to Archive** instead. It is safe to click more than once, as it never awards the same prize twice.

#### Finalise Competition Leaderboard (Match Competition)

A Match Competition leaderboard finalises automatically when the competition is drawn, or shortly after it ends or sells out, whichever comes first. If it has ended but has not been finalised yet, a **Finalise Competition Leaderboard** button appears at the top of the **Leaderboard Winners** tab as a backup.

1. Click **Finalise Competition Leaderboard**.
2. Check the preview of the final standings, showing each **Rank**, **Player**, **Points** and **Prize**.
3. Read the warning: *"This will lock in the final standings below, create winner records, and pay any site-credit prizes. This cannot be undone."*
4. Click **Confirm**. You see **Leaderboard Finalised** once it is done.

If nobody has scored or no prizes have been set up, the preview tells you there is nothing to finalise. The button disappears once the leaderboard has been finalised.

***

### How Ties Work

When two or more players have the same number of points, the tiebreaker decides the order. There are no shared positions in the table.

For example, if Player A and Player B both have 500 points and the tiebreaker is **First to Score**, the player who scored first ranks higher. One finishes 1st and the other 2nd, and each receives that position's prize.