​
What is a Points system?

Points systems are used to reward users for taking actions in your product. When rewards are closely aligned with user incentives, they can be a powerful retention feature.

Use Trophy’s metric analytics to compare the retention of each user interaction, then configure points around these interactions to maximize retention impact.

Use Trophy to create sophisticated points systems driven by real user interactions with no custom code.

​
Creating Triggers

Points can be awarded as a result of user interactions tracked by Trophy including:

  • Awarding points as users increment Metrics e.g. “earn 10 points for every mile ran”.
  • Awarding points for reaching Streak milestones e.g. reaching 7-day, 14-day and 30-day streaks.
  • Awarding points for unlocking Achievements.

To create a new points trigger, head to the points page in the Trophy dashboard and follow the steps below:

All new points triggers are created as ‘Inactive’ to allow testing and balancing before deployment to production.

1

Choose a trigger type

Choose how you want points to be awarded.

  • Choosing Metric will mean points will be automatically awarded to users incrementally as they increase their metric total for a particular metric.

  • Choosing Streak will mean points will be automatically awarded to users eaech time their streak is increased by a specific length.

  • Choosing Achievement will mean points will be automatically awarded to users when they complete a specific achievement.

2

Set up trigger

Once you’ve chosen the points trigger type, you need to set up the trigger settings.

  • If you chose the Metric trigger, you’ll need to choose the metric, the threshold amount at which to award points, and number of points to award each time the user’s total metric value increases by the threshold amount.

  • If you chose the Streak trigger, you’ll need to set the streak length that should award points and the number of points to award to user’s each time their streak is increased by this length.

  • If you chose the Achievement trigger, you’ll need to choose the achievement that should award points when completed and the number of points to award.

3

Hit save

Save the new points trigger.

​
Balancing Points

Running an effective points system requires finding the optimal pace at which users earn points. Too fast, and users will get points fatigue, rendering them useless. Too slow, and users may get bored and churn.

Trophy’s preview tool can model different scenarios to help you determine how frequently users should earn points.

​
Displaying Points

There are a few ways to use Trophy to fetch and display points in your app.

​
Triggering Transactional UI

Firstly, any points awarded to users as a result of a metric change event are returned in the response when using the (metric change event API](/api-reference/endpoints/metrics/send-a-metric-change-event).

The response includes the user’s new total points, how many points were awarded as a result of the event, and the details of the specific points triggers that fired.

Response
{
  "metricId": "d01dcbcb-d51e-4c12-b054-dc811dcdc623",
  "eventId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
  "total": 750,
  "achievements": [
    {
      "id": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
      "trigger": "metric",
      "metricId": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
      "metricName": "Words Written",
      "metricValue": 500,
      "name": "500 words written",
      "description": "Write 500 words in the app.",
      "achievedAt": "2025-04-02T00:00:00Z"
    }
  ],
  "currentStreak": {
    "length": 1,
    "frequency": "daily",
    "started": "2025-04-02",
    "periodStart": "2025-03-31",
    "periodEnd": "2025-04-05",
    "expires": "2025-04-12"
  },
  "points": {
    "total": 5,
    "added": 5,
    "awards": [
      {
        "id": "2414266f-9d02-4820-866b-47b03e87b702",
        "awarded": 5,
        "trigger": {
          "id": "8126234a-2d8c-498d-b919-2459378accad",
          "type": "metric",
          "metricName": "Words Written",
          "metricThreshold": 10,
          "points": 5
        }
      }
    ]
  }
}

This makes it really simple to read the response and trigger any of the following transactional UI in your application:

  • Displaying in-app notifications and pop-ups
  • Playing sound effects

​
Displaying User’s Points

Trophy also has APIs that allow you fetch user’s points data whenever you want.

First, the user points API returns the user’s total points and up to 100 of the most recent events that awarded points to the user.

You can use this API to display the user’s total points anywhere in your platform as well as a ‘Latest awards’ section or similar.

Then, the user points summary API can be used to fetch historical points data for a particular user.

Data can be aggregated daily, weekly or monthly between a start and end date. Use this API to display points progress charts to users over any timeframe.

​
Displaying Aggregate Data

Additionally there are a number of APIs that can be used to fetch and display points data at the account level.

First, the points summary API returns aggregate points data across your entire user base.

Use this data to display a histogram of points and show users how they compare to others on the platform.

Finally, the points triggers API returns data about the active triggers that award points to users in your Trophy account.

Use this API to show users how they can earn points on your platform. Any new triggers you add will automatically be returned from this API helping to reduce code changes in your platform, and shifting operations to Trophy.

​
Points Analytics

Trophy has built-in analytics to track points awards across your users in real time including:

  • Total points earned by all users over time
  • Most points earned by a single user
  • Average points earned in the first 14 days (useful for understanding new user retention patterns and the impact of points)
  • A breakdown on the most commonly awarded points triggers

​
Get Support

Want to get in touch with the Trophy team? Reach out to us via email. We’re here to help!