> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trophy.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Milestones

> Learn how to celebrate user progress with milestones in your web or mobile app with Trophy.

## What are milestones?

> [!NOTE]
>
> Milestones are called achievements in the Trophy API, SDKs and webhooks. For example, see the [all achievements endpoint](https://docs.trophy.so/api-reference/endpoints/achievements/all-achievements.md) and the [`achievement.completed` webhook](https://docs.trophy.so/webhooks/events/achievements/achievement-completed). Field and endpoint names keep the `achievement` naming.

Milestones celebrate progress that users make 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.

Milestones work best when designed to incentivize users to take actions that
are likely to lead to increased retention.

> [!TIP]
>
> Use Trophy's [metric analytics](https://docs.trophy.so/data-sources/metrics.md#metric-analytics) to compare
> the retention of each user interaction, then configure milestones around
> these interactions to maximize retention impact.

Here we'll look at the types of milestones you can build with Trophy, the different ways to use them, and how to integrate them into your platform.

## Milestone types

Trophy offers five types of milestones, [Metric](#metric-achievements), [API](#api-achievements), [Streak](#streak-achievements), [Anniversary](#anniversary-achievements) and [Composite milestones](#composite-achievements), detailed below.

### Metric milestones

Metric milestones are tied to [Metrics](https://docs.trophy.so/data-sources/metrics.md) 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 study platform that uses Trophy to encourage users to view more flashcards with metric milestones as follows:

* 1,000 flashcards
* 2,500 flashcards
* 5,000 flashcards
* 10,000 flashcards
* 25,000 flashcards
* 50,000 flashcards

In this case you would create a metric called *Flashcards Flipped* and create a milestone against the metric for each threshold.

Since these milestones are directly tied to the *Flashcards Flipped* metric, Trophy will automatically track when users unlock these milestones as they [increment the metric](https://docs.trophy.so/data-sources/events.md#tracking-metric-events).

When milestones are unlocked, Trophy includes information about the unlocked milestones in the [Event API](https://docs.trophy.so/api-reference/endpoints/events/submit-a-metric-event.md) response, and automatically triggers [milestone emails](https://docs.trophy.so/features/emails.md#achievement-emails) if configured.

```json Response [expandable] theme={null}
{
  "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": "Flashcards Flipped",
      "metricValue": 500,
      "name": "500 Flashcards Flipped",
      "description": "Flip 500 flashcards in the app.",
      "badgeUrl": null,
      "userAttributes": [],
      "achievedAt": "2020-01-01T00:00:00Z"
    }
  ],
  "currentStreak": {
    "length": 1,
    "frequency": "daily",
    "started": "2025-04-02",
    "periodStart": "2025-03-31",
    "periodEnd": "2025-04-05",
    "expires": "2025-04-12",
    "extended": true
  },
  "points": {
    "xp": {
      "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
      "key": "xp",
      "name": "XP",
      "description": null,
      "badgeUrl": null,
      "maxPoints": null,
      "total": 10,
      "level": {
        "id": "1140fe51-6bce-4b44-b0ad-bddc4e123534",
        "key": "bronze",
        "name": "Bronze",
        "description": "Starting level",
        "badgeUrl": null,
        "points": 0
      },
      "added": 10,
      "awards": [
        {
          "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
          "awarded": 10,
          "date": "2021-01-01T00:00:00Z",
          "total": 10,
          "trigger": {
            "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
            "type": "metric",
            "metricName": "Flashcards Flipped",
            "metricThreshold": 100,
            "points": 10,
            "status": "active",
            "userAttributes": [],
            "created": "2021-01-01T00:00:00Z",
            "updated": "2021-01-01T00:00:00Z"
          }
        }
      ]
    }
  },
  "leaderboards": {
    "daily_champions": {
      "id": "0040fe51-6bce-4b44-b0ad-bddc4e123535",
      "key": "daily_champions",
      "name": "Daily Champions",
      "description": null,
      "status": "active",
      "rankBy": "metric",
      "runUnit": "day",
      "runInterval": 1,
      "maxParticipants": 100,
      "breakdownAttributes": [],
      "metricName": "Flashcards Flipped",
      "metricKey": "flashcards-flipped",
      "threshold": 10,
      "start": "2025-01-01",
      "end": null,
      "startTime": null,
      "endTime": null,
      "previousRank": 50,
      "rank": 12
    }
  },
  "idempotencyKey": "flashcard-view-42",
  "idempotentReplayed": false
}
```

### API milestones

API milestones 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 milestones serve as an easy way to reward users for completing any action that you think is important for retention.

Just like metric milestones, API milestones can also trigger automated [milestone emails](https://docs.trophy.so/features/emails.md#achievement-emails) if configured.

### Streak milestones

Streak milestones are directly tied to a user's [Streak](https://docs.trophy.so/features/streaks.md) and are automatically unlocked when users reach a particular streak length.

You can create as many streak milestones 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 milestones, you can add a custom name and assign a badge to streak milestones.

### Anniversary milestones

Anniversary milestones unlock automatically when a user reaches a specific anniversary of their sign-up date.

Create one milestone for each year you want to celebrate, for example 1 year, 2 years and 5 years. Trophy unlocks each milestone when the user's [`signUpDate`](https://docs.trophy.so/data-sources/users#optional-attributes) plus that number of years is reached.

Users without a `signUpDate` are not eligible. Set `signUpDate` when you [identify](https://docs.trophy.so/data-sources/users.md#identifying-users) or [update](https://docs.trophy.so/data-sources/users.md#keeping-users-up-to-date) users so Trophy can detect anniversaries.

Trophy evaluates the anniversary on the calendar day in the user's [`tz`](https://docs.trophy.so/data-sources/users#optional-attributes). Set `tz` so the milestone unlocks on the correct local day.

Just like other milestone types, anniversary milestones can trigger [milestone emails](https://docs.trophy.so/features/emails.md#achievement-emails) when unlocked.

### Composite milestones

Composite milestones unlock automatically when a user has completed all of the prerequisite milestones you select. They're ideal for creating tiered or mastery-level rewards that recognize users who have accomplished a specific set of milestones.

For example, you could create a "Study Master" composite milestone that unlocks when a user has completed:

* 1,000 flashcards
* 7-day streak
* Complete onboarding

Composite milestones are useful for creating progression pathways and encouraging users to engage across different areas of your app. Just like other milestone types, they can trigger [milestone emails](https://docs.trophy.so/features/emails.md#achievement-emails) when unlocked.

## Creating milestones

To create new milestones, head to the [milestones page](https://app.trophy.so/milestones) in the Trophy dashboard and click the **New milestone** button:

> [!TIP]
>
> You can also create, update, and delete milestones programmatically with the [Admin API](https://docs.trophy.so/admin-api/endpoints/achievements/create-achievements.md).

<video autoPlay muted loop playsInline src="https://mintcdn.com/trophy/vvlxkggAvglghNGz/assets/features/achievements/create_new_achievement.mp4?fit=max&auto=format&n=vvlxkggAvglghNGz&q=85&s=6a0338a0b2d3c88659edbc24ee8689ac" />

**1. Enter a name**

Enter a name for the milestone. 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 milestone. This will be returned from APIs
and made available for use in emails and other areas of Trophy where
appropriate.

**3. Add a badge (Optional)**

You can add a badge by uploading an image or by entering a custom image URL.
The URL is returned in API responses and used in emails and other areas of
Trophy where appropriate.

**4. Choose a trigger type**

Choose how you want this milestone to be unlocked.

* Choosing **Metric** will mean the milestone will be automatically unlocked when the user's metric total reaches the milestone trigger value.

* Choosing **Streak** will mean the milestone will be automatically unlocked when the user's streak length reaches the milestone trigger value.

* Choosing **Anniversary** will mean the milestone will be automatically unlocked when the user reaches the specified anniversary of their [`signUpDate`](https://docs.trophy.so/data-sources/users#optional-attributes).

* Choosing **API Call** will mean the milestone will only be unlocked when explicitly marked as completed by your code through a request to the [complete achievement API](https://docs.trophy.so/api-reference/endpoints/achievements/mark-an-achievement-as-completed.md).

* Choosing **Composite** will mean the milestone will be automatically unlocked when the user has completed all of the prerequisite milestones you select.

**5. Set up trigger**

Once you've chosen the trigger type for the milestone, 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 milestone when reached.

* If you chose the **Streak** trigger, you'll need to set the streak length that should unlock the milestone.

* If you chose the **Anniversary** trigger, you'll need to set the number of years after sign-up that should unlock the milestone.

* If you chose the **API Call** trigger, you'll need to choose a unique reference `key` you'll use to complete the milestone via the [API](https://docs.trophy.so/api-reference/endpoints/achievements/mark-an-achievement-as-completed.md).

* If you chose the **Composite** trigger, you'll need to select the prerequisite milestones that must all be completed for this milestone to unlock. The composite milestone will automatically unlock when a user completes the final prerequisite.

**6. Add attribute filters (Optional)**

You can assign attribute filters to a milestone to further restrict who can unlock them and when.

* To limit a **Metric** milestone to only apply to events with specific [custom event attributes](https://docs.trophy.so/data-sources/events.md#custom-event-attributes), add one or more filters in the **Event Attributes** section.

* To limit any type of milestone to only apply to a user with one or more specific [custom user attributes](https://docs.trophy.so/data-sources/users.md#custom-user-attributes), add attributes and the desired values in the **User Attributes** section.

> [!NOTE]
>
> When you set multiple event attribute filters, all of them must match for the
> metric milestone to apply. In API responses, `eventAttributes` is the
> canonical field and `eventAttribute` is deprecated for legacy compatibility.

**7. Click save**

Save the new milestone.

## Managing milestones

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

### Milestone statuses

Here's an overview of the different milestone statuses and what they mean.

**Inactive**

All milestones are created as inactive. Inactive milestones can't be completed and aren't returned in any milestone APIs. Users won't see them until you make them active.

**Active**

When you make a milestone active, it makes it 'live'. Users can complete it and it will be returned from all milestone APIs.

**Locked**

When you lock a milestone, 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 milestones are only returned in APIs for users who have already achieved them.

### Milestone workflow

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

```mermaid theme={null}
flowchart LR
    A@{ shape: rounded, label: "Inactive" }
    B@{ shape: rounded, label: "Active" }
    C@{ shape: rounded, label: "Locked" }
    A-->B
    B<-->C
    class A milestoneInactive
    class B milestoneActive
    class C milestoneLocked

```

## Completing milestones

If you're using metric milestones, there's no need to explicitly *complete* milestones. Once you've set up [metric tracking](https://docs.trophy.so/data-sources/events.md#tracking-metric-events) in your code, all milestones linked to the metric will be automatically tracked.

Similarly, if you're using streak milestones, all milestones related to the user's streak will automatically be unlocked when a user reaches the respective streak length.

Anniversary milestones are also completed automatically. They unlock when a user reaches the configured anniversary of their [`signUpDate`](https://docs.trophy.so/data-sources/users#optional-attributes). Users without a `signUpDate` cannot unlock them.

Composite milestones are also completed automatically. They unlock as soon as a user has completed all of their prerequisite milestones. No additional API calls are needed.

However if you're using any API milestones, you will have to mark them as completed for each user as appropriate. To do this, you can use the [Complete Achievement API](https://docs.trophy.so/api-reference/endpoints/achievements/mark-an-achievement-as-completed.md) using the `key` of the milestone you want to complete.

This will return back a response that contains details of the milestone that was completed that can be used in any post-completion workflows, like showing an in-app notification.

```json Response theme={null}
{
  "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 milestones

By default, whenever you move a milestone to 'Active' [status](#managing-achievements), Trophy will check if any existing users meet the requirements of the milestone and complete it for them behind the scenes.

This means when you release new milestones into production, or edit an existing live milestone, backdating will happen automatically.

The same applies when you set or change a user's [`signUpDate`](https://docs.trophy.so/data-sources/users#optional-attributes). If the user already qualifies for any active anniversary milestones, Trophy completes them silently.

> [!NOTE]
>
> When milestones are completed in this way, users don't receive any
> notifications this has happened. This is to prevent changes to your
> milestones in Trophy resulting in users getting lots of notifications.

You can check how many users have completed milestones at any time on the [milestones page](https://app.trophy.so/milestones) in the Trophy dashboard. The *Users* column in the milestones can update during backdating.

![](https://mintcdn.com/trophy/vvlxkggAvglghNGz/assets/features/achievements/check_user_completions.png?fit=max\&auto=format\&n=vvlxkggAvglghNGz\&q=85\&s=0756e95318960708d63014ef28ebab92)

## Using badges

<video autoPlay muted loop playsInline src="https://mintcdn.com/trophy/vvlxkggAvglghNGz/assets/features/achievements/upload_badge.mp4?fit=max&auto=format&n=vvlxkggAvglghNGz&q=85&s=1e531139f738671d8267656514e0def2" />

You can assign a badge to any milestone by uploading an image—Trophy serves it and returns the URL—or by providing your own image URL. Relevant API responses include that value in `badgeUrl` for use as the `src` on `<img>` tags.

```json Response {8} theme={null}
{
  "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 milestones

Trophy has a number of APIs that support displaying milestones within your applications. Here we'll look at the different ways to use them and the types of UI's you can build.

### All milestones

To display a high-level overview of all milestones users can complete, use the [all achievements endpoint](https://docs.trophy.so/api-reference/endpoints/achievements/all-achievements.md). Use this data to build UI that gives users an idea of the progression pathways within your application.

<video autoPlay muted loop playsInline src="https://mintcdn.com/trophy/rGjOHIeZYrVU9hOo/assets/features/achievements/displaying_trophy_cabinet.mp4?fit=max&auto=format&n=rGjOHIeZYrVU9hOo&q=85&s=d5562bcf1e0d75c3f42f7e8c0f851911" />

The all milestones endpoint returns a list of all milestones within your Trophy account. Each milestone returned also includes `completions` (the number of users who have completed the milestone) and `rarity` (the percentage of users who have completed the milestone) as follows:

```json Response [expandable] theme={null}
[
  {
    "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 Flashcards Flipped",
    "description": "View 500 flashcards in the app.",
    "badgeUrl": "https://example.com/badge.png",
    "metricId": "5100fe51-6bce-6j44-b0hs-bddc4e123683",
    "metricName": "Flashcards Flipped",
    "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
  },
  {
    "id": "5100fe51-6bce-6j44-b0hs-bddc4e123686",
    "trigger": "anniversary",
    "name": "1 year anniversary",
    "description": "Celebrate one year on the platform.",
    "badgeUrl": "https://example.com/badge.png",
    "anniversaryYears": 1,
    "completions": 4,
    "rarity": 40
  },
  {
    "id": "5100fe51-6bce-6j44-b0hs-bddc4e123685",
    "trigger": "achievement",
    "name": "Study Master",
    "description": "Complete all introductory milestones.",
    "badgeUrl": "https://example.com/badge.png",
    "achievementIds": [
      "5100fe51-6bce-6j44-b0hs-bddc4e123682", "5100fe51-6bce-6j44-b0hs-bddc4e123683", "5100fe51-6bce-6j44-b0hs-bddc4e123684"
    ],
    "completions": 1,
    "rarity": 5
  }
]
```

### User milestones

If instead you're building user-specific UI elements, then use the [user achievements endpoint](https://docs.trophy.so/api-reference/endpoints/users/get-a-users-completed-achievements.md) to return milestones a specific user has completed.

> [!TIP]
>
> You can also include milestones that a user has yet to complete by including
> the query parameter `includeIncomplete=true`.

![](https://mintcdn.com/trophy/vvlxkggAvglghNGz/assets/features/achievements/user_achievements.png?fit=max\&auto=format\&n=vvlxkggAvglghNGz\&q=85\&s=b17619bf505128b705df9b3d3cc408f0)

## Milestone analytics

If you have milestones set up for any of your [Metrics](https://docs.trophy.so/data-sources/metrics.md), then the metric analytics page displays a chart that shows you the current progress of all Users as follows:

![](https://mintcdn.com/trophy/rGjOHIeZYrVU9hOo/assets/features/metrics/achievement_completions.png?fit=max\&auto=format\&n=rGjOHIeZYrVU9hOo\&q=85\&s=29113a61395c95f09bb8d6755caff17a)

## Frequently asked questions

> [accordion] What type of milestones should I use?
>
> Use metric milestones for rewarding users for taking the same action over and over again, and to incentivise them to do it more.
>
> Use streak milestones for rewarding users for keeping their streak.
>
> Use anniversary milestones for rewarding users for remaining on your platform over time.
>
> Use API milestones when you want to reward users for taking specific actions that they only need to take once.
>
> Use composite milestones when you want to create tiered or mastery-level rewards that unlock when users complete a specific set of prerequisite milestones.

> [accordion] What milestones should I create?
>
> Milestones offer the best retention when tightly aligned to the user's core reason for using your platform.
>
> Use Trophy's [metric analytics](https://docs.trophy.so/data-sources/metrics.md#metric-analytics) to compare the retention of each user interaction, then configure milestones around these interactions to maximize retention impact.

## Rewarding milestones

To give users something when they unlock a milestone, like bonus points they claim or a prize you fulfill yourself, add a milestone trigger to a [reward](https://docs.trophy.so/features/rewards.md#achievement-triggers). If you just want points added automatically, use a [points trigger](https://docs.trophy.so/features/points.md#achievement-triggers) instead.

## Milestones in agentic messaging

Milestones also give [agentic messaging](https://docs.trophy.so/agentic-messaging/overview.md) a reason to reach out. Lifecycle agents can celebrate milestones users have just completed, or encourage users who are close to their next one, picking the best message for each user at the best moment.

## Get support

Want to get in touch with the Trophy team? Reach out to us via [email](mailto:support@trophy.so). We're here to help!


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.