Ctrlk
HomepageCase studiesBook a demo
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Creating Leaderboards

This article explains how leaderboards can be created and used in your loyalty program.

Adding a new leaderboard allows you to define the rules, timeframe, and visibility for how members will be ranked in your loyalty program. This process involves setting up basic information, choosing the duration, determining who can see it, and specifying the metric that will be tracked.

Step-by-step instructions

Follow these steps to set up a new leaderboard in your Open Loyalty environment:

1

Go to the Leaderboards section

In the left-hand navigation, under Modules, click on Leaderboards.

2

Add a new leaderboard

On the Leaderboards page, click the Add leaderboard button (located in the top right corner).

3

Basic Info

  • Title and description: Enter a clear Leaderboard name (e.g., "Top Spenders," "Most Active Members") and an optional Leaderboard description to explain its purpose.

4

Timeframe

  • Start date: Select the date when the leaderboard should begin tracking member activity.

  • End date (optional): Choose an end date if you want the leaderboard to stop tracking activity after a specific period.

Leaderboards will not do a retroactive calculation, even if you set a date in the past!

5

Custom Attributes

This section allows you to include custom data fields for additional details. For now, you can leave this as default unless you have specific custom attributes to add.

6

Tracked Metric

  • Select the type of activity you want to measure and rank members by from the Metric dropdown (e.g., "Cumulative earned units in a wallet").

  • If applicable, select the Wallet type.

7

Status

Toggle the Active switch to enable or disable the leaderboard. An active leaderboard will collect data.

8

Leaderboard Grouping

Optionally divide participants into independent sub-leaderboards based on a member attribute. Each group maintains its own Top-1000 ranking and, if a rewarding cycle is configured, its own reward distribution.

Members with a missing or blank value for the selected grouping field will be filtered out from the leaderboard entirely.

Select one of the three grouping options:

No grouping (default)

All members compete together in a single unified ranking. No sub-groups are created.

Custom attribute

Group members by the value of a free-form attribute key stored in their profile.

  • Enter the Key — the custom attribute key whose values define the groups. Members sharing the same value for this key are placed in the same sub-group.

We recommend selecting a grouping with fewer than 500 groups (default limit), including active ones. If you exceed this, not all groups will be rewarded when you enable rewarding.

Address fields

Group members by a standard address field from their member profile. Select the Profile field to group by:

  • Postal code

  • City

  • State

  • Country

We recommend selecting a grouping with fewer than 500 groups (default limit), including active ones. If you exceed this, not all groups will be rewarded when you enable rewarding.

9

Rewarding Cycle (optional)

You can enable the rewarding cycle for top ranking members.

For more information on the rewarding cycle, please refer to this section of the User Guide: Rewarding Cycle

10

Summary

Review all your settings. If everything looks correct, click Add leaderboard.

Final tips

  • Currently, you can have up to 3 active leaderboards within an environment.

  • Members with the same tracked metric value will tie and appear in the same position on the leaderboard.

  • Leaderboards are recalculated every 4 hours.

  • Future updates will expand leaderboard capabilities, including the ability to target specific segments or tiers and introduce additional conditions.

Last updated

Was this helpful?