For the complete documentation index, see llms.txt. This page is also available as Markdown.

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, Creating leaderboards, Rewarding cycle and 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.

1

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.

2

List the contests

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

3

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.

4

Announce winners

Rewards are applied by the rewarding cycle; use CampaignEffectWasApplied to tell winners.

Sequence diagram

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's own score, position, neighbours and recalculatedAt, and shows the table with the member'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.
Showing a leaderboard and paying prizes

Go-live checklist

Admin Panel

Integration layer and website / app

Validation

Key endpoints

Webhooks: CampaignEffectWasApplied

Last updated

Was this helpful?