> For the complete documentation index, see [llms.txt](https://kbase.whitelabel-loyalty.com/product/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kbase.whitelabel-loyalty.com/product/modules/leaderboards.md).
# Leaderboards
### What is the Leaderboards module?
The Leaderboards module creates ranked competitions based on members’ earned points. It adds a social, competitive element to your loyalty program.
Create and manage leaderboards from **Loyalty Console → Users → Leaderboards**. Configure the time window, recurrence, audience, and displayed positions. Recurring leaderboards roll over automatically.
***
### How leaderboards work
#### Ranking
Members are ranked by **earned points** within the leaderboard’s time window. Points from neutralised or refunded events are excluded, so rankings reflect genuine earning activity.
Rankings refresh hourly, rather than in real time. The leaderboard records its last update time.
Tied scores receive the same rank using dense ranking. For example, `1, 2, 2, 3`.
#### Time windows
Every leaderboard uses one of three time window types:
| Type | Behaviour |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Lifetime** | No start or end date. Ranks members by all-time earned points. Always active. |
| **Recurring** | Resets automatically on a weekly, monthly, quarterly, or yearly cadence, anchored to calendar boundaries. Each completed period is frozen and a new period opens automatically. Runs indefinitely until deactivated. |
| **Fixed period** | Admin-defined start and end dates. The board freezes at the end date and remains viewable as a historical record. |
#### Audience targeting
Leaderboards can optionally be restricted to a specific audience. Only members in the target audience are included in the ranking. If a member is removed from the audience mid-period, they are excluded on the next ranking refresh.
If no audience is set, all eligible members in your program are included.
#### Member display names
Members are ranked using their first name and last name initial (e.g. “Sarah T.”) to provide recognition without full identity exposure.
#### Participation
Members choose whether to take part. Members who opt out are excluded from every ranking.
{% hint style="info" %}
Members control their own participation. You cannot opt them in or out.
{% endhint %}
***
### Managing leaderboards
Create, edit, and view leaderboards from **Loyalty Console → Users → Leaderboards**.
The Leaderboard list view.
#### Leaderboard statuses
Leaderboards can have one of three statuses:
| Status | Ranking | Visibility |
| ------------ | ---------------------------------------- | ---------------------- |
| **Active** | Rankings are computed and updated hourly | Visible to members |
| **Inactive** | Rankings are not computed | Not visible to members |
| **Archived** | Rankings are not computed | Not visible to members |
#### Creating & editing a leaderboard
When creating or editing a leaderboard, you can configure the following:
1. **Internal name:** A system reference for the leaderboard, visible only to admins.
2. **Display name & description:** The user-facing name and description shown to members. Supports **localisation** for multi-language programs.
3. **Status:** Active or Inactive. (A leaderboard can also be set to archived when editing — see Leaderboard statuses.)
4. **Ranking method:** How members are ranked. Points based is currently the only option; other ranking methods may be available in future.
5. **Time window type:** Lifetime, recurring or fixed period.
6. **Recurrence schedule:** Shown when the time window is recurring — weekly, monthly, quarterly, or yearly.
7. **Start & end dates:** Shown when the time window is fixed period. Defines when the competition runs.
8. **Audience:** Optionally restrict the leaderboard to a specific audience segment.
9. **Leaderboard size:** The number of top participants displayed to members (default 10).
10. **Display priority:** Controls display ordering when multiple leaderboards are active. Higher-priority leaderboards appear first.
{% tabs %}
{% tab title="Lifetime" %}
{% endtab %}
{% tab title="Recurring" %}
{% endtab %}
{% tab title="Fixed Period" %}
{% endtab %}
{% endtabs %}
{% hint style="info" %}
Leaderboards cannot be deleted. Set a leaderboard to **Archived** to remove it from your program.
{% endhint %}
#### Running multiple leaderboards
You can have multiple active leaderboards at the same time. Use the **display priority** field to control the order in which they’re presented to members — higher priority appears first.
#### Viewing historical periods
For recurring and fixed-period leaderboards, completed periods are frozen and preserved. You can review the final rankings for any historical period from the leaderboard detail screen in the console. Recurring periods roll over automatically — no admin intervention is required.
A weekly recurring leaderboard with historical periods.
***
### Leaderboard use case examples
Use leaderboards for campaigns, tier engagement, or long-term recognition.
{% tabs %}
{% tab title="Monthly Top Earners" %}
Create a recurring monthly leaderboard for all members. Rankings reset each month, giving everyone a fresh start.
{% endtab %}
{% tab title="VIP Race" %}
Create a recurring leaderboard for your VIP audience. This creates exclusivity and motivates members to reach VIP status.
{% endtab %}
{% tab title="Summer Challenge" %}
Create a fixed-period leaderboard from June through August. The final rankings remain available after the campaign ends.
{% endtab %}
{% tab title="All-Time Champions" %}
Create a lifetime leaderboard using all-time earned points. Recognise your most loyal members and set a long-term goal for others.
{% endtab %}
{% endtabs %}
***
### FAQs
#### Can I run multiple leaderboards at the same time?
Yes. You can have multiple active leaderboards simultaneously. Use the display priority field to control which leaderboard appears first.
#### Are rankings updated in real time?
No. Rankings are recomputed hourly, and the last update time is recorded so you can see when the data was last refreshed.
#### Can members participate without showing their name?
In the current version, members are ranked as first name and last initial (e.g. “Sarah T.”). Members who don’t want to be visible can opt out entirely, which removes them from all rankings. There is no anonymous participation mode at this time.
#### What happens when a recurring leaderboard period ends?
The platform automatically freezes the completed period’s rankings and opens a new period. No admin intervention is required. Historical periods and their final rankings are preserved and viewable in the console.
#### Can I award prizes based on leaderboard position?
Automated prize or reward distribution based on leaderboard rank is not currently supported. You can manually review final rankings and issue rewards using other platform tools.
#### Does the leaderboard work in the Loyalty Mobile App?
Leaderboards are not currently supported by our Loyalty Mobile App product. Speak to your account manager for more information.
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://kbase.whitelabel-loyalty.com/product/modules/leaderboards.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.