​
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, Standalone 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": {
    "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
        }
      }
    ]
  }
}

​
Standalone Achievements

Standalone 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
Standalone achievements serve as an easy way to reward users for completing any action that you think is important for retention. Just like metric achievements, standalone 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 standalone 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

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 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 an API call.
3

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.
4

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.
5

Hit save

Save the new achievement.

​
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 standalone 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"
  }
}

​
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 along with details of ‘rarity’ (the percentage of users who have completed each 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,
    "completedPercentage": 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,
    "completedPercentage": 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,
    "completedPercentage": 20
  }
]

​
User Achievements

If instead you’re building user-specific UI elements, then use the user achievements endpoint to get only the achievements a specific user has completed. Use this data to display achievements against a user’s profile for example.

​
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

​
Get Support

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