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

No matter the type of achievement, they work best when designed to incentivize users to take actions that are likely to lead to increased retention. So before jumping in, have a think about what those actions might be in your context.

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.

​
Achievement Types

Trophy offers two types of achievements, Multi-stage and One-Off, detailed below.

​
Multi-stage

Multi-stage 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 multi-stage 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 Emails if configured.

Response
{
  "eventId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
  "metricId": "d01dcbcb-d51e-4c12-b054-dc811dcdc623",
  "total": 750,
  "achievements": [
    {
      "metricId": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
      "completed": [
        {
          "id": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
          "name": "500 words written",
          "metricId": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
          "metricValue": 500,
          "metricName": "words written",
          "achievedAt": "2020-01-01T00:00:00Z"
        }
      ]
    }
  ],
  "currentStreak": {
    "frequency": "daily",
    "length": 1,
    "expires": "2025-04-12",
    "extended": true,
    "periodEnd": "2025-04-05",
    "periodStart": "2025-03-31",
    "started": "2025-04-02"
  }
}

​
One-off

One-off 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

One-off achievements serve as an easy way to reward users for completing any action that you think is important for retention.

Just like multi-stage achievements, one-off achievements can also trigger automated Emails if configured.

​
Creating Achievements

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

1

Choose a metric

If you want to assign this achievement to a metric for use as part of multi-stage achievements, then choose a metric. Otherwise continue to the next step.

2

Enter a metric value

If you’re assigning this achievement to a metric as part of multi-stage achievements then choose the value of the metric that should unlock this Achievement. Otherwise continue to the next step.

3

Choose a name

Choose a name for the achievement. This will be made available for use in emails and other areas of Trophy where appropriate. If you’re assigning this achievement to a metric as part of multi-stage achievements this is optional and defaults to [count] [metric] e.g. “100 words written”.

4

Choose a key

Choose a key for the achievement. This is a unique string that you’ll use to refer to the achievement when using APIs. Not required for multi-stage achievements.

5

Upload a badge _Optional_

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

6

Hit save

Save the new achievement.

​
Completing Achievements

If you’re using Multi-stage Achievements, there’s no need to explicitly complete Achievements.

Once you’ve integrated the Metric into your platform, all achievements linked to it will be automatically tracked.

However if you’re using any one-off 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",
    "name": "Finish onboarding",
    "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",
    "name": "Finish onboarding",
    "badgeUrl": "https://example.com/badge.png",
    "key": "finish-onboarding",
    "achievedAt": "2021-01-01T00:00:00Z"
  }
}

​
Achievement Analytics

If you have multi-stage acheivements 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!