​
What Are Achievements?

Achievements are rewards that users can unlock as they use your platform. They can be used to reward users for making continued progress along core user journeys, or to motivate users to explore more nascent features. Achievements work best when designed to incentivize users to take actions that are likely to lead to increased retention.
Use Trophy’s metric analytics to compare the retention of each user interaction, then configure achievements around these interactions to maximize retention impact.
Here we’ll have a look of the types of achievements you can build with Trophy, the different ways to use them, and how to integrate them into your platform. Watch Charlie run walk through using achievements in a NextJS application:

​
Achievement Types

Trophy offers three types of achievements, Metric, API and Streak achievements, detailed below.

​
Metric Achievements

Metric achievements are tied to Metrics and are best used when you want to incentivize users to take the same action over and over again. Let’s take the example of a book-writing platform that uses Trophy to encourage users to write more often with metric achievements as follows:
  • 1,000 words
  • 2,500 words
  • 5,000 words
  • 10,000 words
  • 25,000 words
  • 50,000 words
In this case you would create a metric called Words Written and create achievements against the metric for each milestone. Since these achievements are directly tied to the Words Written metric, Trophy will automatically track when users unlock these achievements as they increment the metric. When achievements are unlocked, Trophy includes information about the unlocked achievements in the Event API response, and automatically triggers Achievement Emails if configured.
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": {
    "point-system-key": {
      "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
          }
        }
      ]
    }
  }
}

​
API Achievements

API achievements can only be completed once and are useful for rewarding users for taking specific actions. Common examples include:
  • A user completing their profile after signing up
  • A user linking their social account to a platform
  • A user sharing their product experience on social media
API achievements serve as an easy way to reward users for completing any action that you think is important for retention. Just like metric achievements, API achievements can also trigger automated Achievement Emails if configured.

​
Streak Achievements

Streak achievements are directly tied to a user’s Streak and are automatically unlocked when users reach a particular streak length. You can create as many streak achievements as you like for increasing lengths of streak, for example 7 days, 30 days and 365 days to motivate users to use your app more and more. Just like metric and API achievements, you can add a custom name and assign a badge to streak achievements.

​
Creating Achievements

To create new achievements, head to the achievements page in the Trophy dashboard and hit the New Achievement button:
1

Enter a name

Enter a name for the achievement. This will be returned from APIs and made available for use in emails and other areas of Trophy where appropriate.
2

Enter a description (Optional)

Enter a short description of the achievement. This will be returned from APIs and made available for use in emails and other areas of Trophy where appropriate.
3

Upload a badge (Optional)

You can upload and assign a badge to the achievement that will be returned in API responses and made available in emails and other areas of Trophy where appropriate.
4

Choose a trigger type

Choose how you want this achievement to be unlocked.
  • Choosing Metric will mean the achievement will be automatically unlocked when the user’s metric total reaches the achievement trigger value.
  • Choosing Streak will mean the achievement will be automatically unlocked when the user’s streak length reaches the achievement trigger value.
  • Choosing API Call will mean the achievement will only be unlocked when explicitly marked as completed by your code through a request to the complete achievement API.
5

Set up trigger

Once you’ve chosen the trigger type for the achievement, you need to set up the trigger settings.
  • If you chose the Metric trigger, you’ll need to choose the metric and the user’s total value that should unlock the achievement when reached.
  • If you chose the Streak trigger, you’ll need to set the streak length that should unlock the achievement.
  • If you chose the API Call trigger, you’ll need to choose a unique reference key you’ll use the complete the achievement via the API.
6

Add attribute filters (Optional)

You can assign attribute filters to an achievement to further restrict who can unlock them and when.
  • To limit a Metric achievement to only apply to events with specific custom event attributes, select an attribute and enter a value in the Event Attribute section.
  • To limit any type of achievement to only apply to a user with one or more specific custom user attributes, add attributes and the desired values in the User Attributes section.
7

Hit save

Save the new achievement.

​
Managing Achievements

Trophy has built in tools to help you test and control which achievements can be unlocked, by who and when, without affecting production.

​
Achievement Statuses

Here’s an overview of the different achievement statuses and what they mean. Inactive All achievements are created as inactive. Inactive achievements can’t be completed and aren’t returned in any achievement APIs. Users won’t see them until you make them active. Active When you make an achievement active, it makes it ‘live’. Users can complete it and it will be returned from all achievement APIs. Locked When you lock an achievement, users who haven’t unlocked it yet won’t be able to unlock it anymore, but users who have already unlocked it won’t be affected. Locked achievements are only returned in APIs for users who have already achieved them. Archived Archived achievements can’t be completed and aren’t returned in any achievement APIs.
Once you archive an achievement it disappears from Trophy so be sure to only archive achievements that you no longer need.
Archived achievements can be restored by contacting support.

​
Achievement Workflow

Achievements can be moved through different statuses according to the following workflow:

​
Completing Achievements

If you’re using metric achievements, there’s no need to explicitly complete achievements. Once you’ve set up metric tracking in your code, all achievements linked to the metric will be automatically tracked. Similarly, if you’re using streak achievements, all achievements related to the user’s streak will automatically be unlocked when a user reaches the respective streak length. However if you’re using any API achievements, you will have to mark them as completed for each user as appropriate. To do this, you can use the Complete Achievement API using the key of the achievement you want to complete. This will return back a response that contains details of the achievement that was completed that can be used in any post-completion workflows, like showing an in-app notification.
Response
{
  "completionId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
  "achievement": {
    "id": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
    "trigger": "api",
    "name": "Finish onboarding",
    "description": "Complete the onboarding process.",
    "badgeUrl": "https://example.com/badge.png",
    "key": "finish-onboarding",
    "achievedAt": "2021-01-01T00:00:00Z"
  }
}

​
Backdating Achievements

By default, whenever you move an achievement to ‘Active’ status, Trophy will check if any existing users meet the requirements of the achievement and complete it for them behind the scenes. This means when you release new achievements into production, or edit an existing live achievement, backdating will happen automatically.
When achievements are completed in this way, users don’t receive any notifications this has happened. This is to prevent changes to your achievements in Trophy resulting in users getting lots of notifications.
You can check how many users have completed achievements at any time on the achievements page in the Trophy dashboard. The Users column in the achievements can update during backdating.

​
Using Badges

A badge can be uploaded and assigned to any achievement in Trophy. Trophy will host the image for you and return the URL back to you in relevant API responses to be used as the src property in <img> tags.
Response
{
  "completionId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
  "achievement": {
    "id": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
    "trigger": "api",
    "name": "Finish onboarding",
    "description": "Complete the onboarding process.",
    "badgeUrl": "https://example.com/badge.png",
    "key": "finish-onboarding",
    "achievedAt": "2021-01-01T00:00:00Z"
  }
}

​
Displaying Achievements

Trophy has a number of APIs that support displaying achievements within your applications. Here we’ll look at the different ways to use them and the types of UI’s you can build.
Take a look at our examples center for live demos of APIs in practice.

​
All Achievements

To display a high-level overview of all achievements users can complete, use the all achievements endpoint. Use this data to build UI that gives users an idea of the progression pathways within your application.
The all achievements endpoint returns a list of all achievements within your Trophy account. Each achievement returned also includes completions (the number of users who have compeleted the achievement) and rarity (the percentage of users who have completed the achievement) as follows:
Response
[
  {
    "id": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
    "trigger": "api",
    "name": "Finish onboarding",
    "description": "Complete the onboarding process.",
    "badgeUrl": "https://example.com/badge.png",
    "key": "finish-onboarding",
    "completions": 8,
    "rarity": 80
  },
  {
    "id": "5100fe51-6bce-6j44-b0hs-bddc4e123683",
    "trigger": "metric",
    "name": "500 words written",
    "description": "Write 500 words in the app.",
    "badgeUrl": "https://example.com/badge.png",
    "metricId": "5100fe51-6bce-6j44-b0hs-bddc4e123683",
    "metricName": "words written",
    "metricValue": 500,
    "completions": 6,
    "rarity": 60
  },
  {
    "id": "5100fe51-6bce-6j44-b0hs-bddc4e123684",
    "trigger": "streak",
    "name": "10 days of exercise",
    "description": "Exercise at least once a day for 10 days in a row.",
    "badgeUrl": "https://example.com/badge.png",
    "streakLength": 10,
    "completions": 2,
    "rarity": 20
  }
]

​
User Achievements

If instead you’re building user-specific UI elements, then use the user achievements endpoint to return achievements a specific user has completed.
You can also include achievements that a user has yet to complete by including the query parameter includeIncomplete=true.

​
Achievement Analytics

If you have achievements set up for any of your Metrics, then the metric analytics page displays a chart that shows you the current progress of all Users as follows:

​
Frequently Asked Questions

Use metric achievements for rewarding users for taking the same action over and over again, and to incentivise them to do it more.Use streak achievements for rewarding users for keeping their streak.Use API achievements when you want to reward users for taking specific actions that they only need to take once.
Achievements, like all gamification, offer the best retention when tightly aligned to the user’s core reason for using your platform.Use Trophy’s metric analytics to compare the retention of each user interaction, then configure achievements around these interactions to maximize retention impact.

​
Get Support

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