> For the complete documentation index, see [llms.txt](https://help.openloyalty.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.openloyalty.io/implementation-guide/module-checklists/leaderboards.md).

# Leaderboards

Running contests with leaderboards: choosing the metric and grouping, showing the table and the member's own position, and paying monthly prizes.

A leaderboard ranks members by a metric — usually units earned in a wallet — over a period, and can reward the top positions each month. Members see the top of the table and their own position. Open Loyalty calculates the rankings; your channels display them.

For the Admin Panel side, see [Leaderboards](https://help.openloyalty.io/gamification/leaderboards), [Creating leaderboards](https://help.openloyalty.io/gamification/leaderboards/creating-leaderboards), [Rewarding cycle](https://help.openloyalty.io/gamification/leaderboards/rewarding-cycle) and [Sample leaderboards](https://help.openloyalty.io/gamification/leaderboards/sample-leaderboards).

## Who does what

| Area                           | Responsibility                                                              |
| ------------------------------ | --------------------------------------------------------------------------- |
| **Admin Panel**                | Leaderboard timeframe, tracked metric, grouping, rewarding cycle and budget |
| **Integration layer**          | Reads the table and the member's position; caches the list of leaderboards  |
| **Website / app**              | Contest page with the table, the member's position and "last updated"       |
| **CRM / marketing automation** | Winner messages from webhooks; contest reminders                            |

## Things to design around

| Constraint                                      | What it means                                                                                                                                             |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Up to **3 active leaderboards** per environment | Plan contests so no more than three run at once.                                                                                                          |
| Rankings recalculate **every 4 hours**          | Show the `recalculatedAt` time; don't promise live rankings.                                                                                              |
| **No retroactive calculation**                  | A leaderboard counts from when it starts tracking, even if its start date is in the past. Create it before the contest begins.                            |
| Rewards are paid **monthly**                    | At the end of each calendar month and at the end date — a contest spanning two months pays twice. Payment can take up to about two hours after month end. |
| Rewarded positions **1–100**                    | Prizes can go to the top 100 at most.                                                                                                                     |
| Grouping drops blanks                           | In a grouped leaderboard, members with no value for the grouping field aren't ranked.                                                                     |

## Design decisions

| Decision | Options                                                    | Recommendation                                                                                                                                              |
| -------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Metric   | Units earned in a wallet, or another metric                | A dedicated wallet for the contest (e.g. "contest points" earned only from the promoted product) keeps the ranking about the contest, not about everything. |
| Grouping | One table, or sub-leaderboards (by city, store, attribute) | Group when members can only realistically compete locally; make sure every participant has the grouping value.                                              |
| Prizes   | Units, rewards, badges                                     | Badges or rewards. If prizes are units, don't pay them into the tracked wallet — winners would climb further.                                               |
| Duration | One month, several months, open-ended                      | Calendar months line up with the monthly rewarding cycle.                                                                                                   |

## Recommended flow

{% stepper %}
{% step %}

### Configure (Admin Panel)

Create the leaderboard before the contest starts: timeframe, tracked metric (and wallet), grouping, and the rewarding cycle with reward logic for positions or ranges and a budget.
{% endstep %}

{% step %}

### List the contests

Leaderboards are campaigns with trigger `leaderboard`: `GET /api/{storeCode}/campaign?trigger=leaderboard&active=1`. Cache the list.
{% endstep %}

{% step %}

### Show the table and the member's position

`GET /api/{storeCode}/campaign/{campaign}/leaderboard` returns the top of the table (pass `group` for a grouped leaderboard; `…/leaderboard/group` lists the groups). `GET /api/{storeCode}/campaign/{campaign}/leaderboard/member/{member}` returns the member's score, position, the members around them and `recalculatedAt`.
{% endstep %}

{% step %}

### Announce winners

Rewards are applied by the rewarding cycle; use `CampaignEffectWasApplied` to tell winners.
{% endstep %}
{% endstepper %}

## Sequence diagram

<figure><img src="https://226878483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ4Fuoa1PTF0DrNTgjzJu%2Fuploads%2Fgit-blob-9a09237d5137b0ef76192c2790a1385062b85e6a%2Fig-leaderboards-flow.png?alt=media" alt="Rankings are recalculated every 4 hours from the tracked metric. When a member opens the leaderboard, the integration layer reads the cached list of active leaderboards, then in parallel the top positions with scores and the member&#x27;s own score, position, neighbours and recalculatedAt, and shows the table with the member&#x27;s position and the last update time. At the end of each month and at the end date, the rewarding cycle pays positions 1 to 100 per the reward logic, and CampaignEffectWasApplied webhooks report the winners." width="728"><figcaption><p>Showing a leaderboard and paying prizes</p></figcaption></figure>

## Go-live checklist

### Admin Panel

* [ ] No more than 3 leaderboards are active at the same time.
* [ ] The leaderboard exists before the contest starts tracking.
* [ ] Unit prizes don't go into the tracked wallet.
* [ ] Grouped leaderboards: every participant has the grouping value.

### Integration layer and website / app

* [ ] The page shows the table, the member's own position and the last recalculation time.
* [ ] Grouped leaderboards show the member's own group.

### Validation

* [ ] A test member's score moves after their activity, within one recalculation.
* [ ] At the first month end, the right positions receive the right rewards once.

## Key endpoints

* `GET /api/{storeCode}/campaign?trigger=leaderboard` — [Get campaigns list](https://help.openloyalty.io/api-reference/campaign/get-campaigns-list)
* `GET /api/{storeCode}/campaign/{campaign}/leaderboard` — [Get campaign leaderboard](https://help.openloyalty.io/api-reference/campaign/get-campaign-leaderboard)
* `GET /api/{storeCode}/campaign/{campaign}/leaderboard/member/{member}` — [Get member's ranking in a specific campaign](https://help.openloyalty.io/api-reference/campaign/get-members-ranking-in-a-specific-campaign)
* `GET /api/{storeCode}/campaign/{campaign}/leaderboard/group` — [List distinct group values for a grouped leaderboard](https://help.openloyalty.io/api-reference/campaign/list-distinct-group-values-for-a-grouped-leaderboard)

**Webhooks:** [CampaignEffectWasApplied](https://apidocs.openloyalty.io/#tag/Webhook-event/operation/CampaignEffectWasApplied)

{% hint style="warning" %}
**Common pitfalls**

* Creating the leaderboard after the contest has started and expecting earlier activity to count.
* Paying unit prizes into the tracked wallet, so winners pull further ahead.
* Promising real-time rankings when they update every 4 hours.
* Planning a fourth simultaneous leaderboard.
  {% endhint %}


---

# 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.openloyalty.io/implementation-guide/module-checklists/leaderboards.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.