Rewards

What are Rewards?

Rewards let you give users something when they hit a milestone, and let them choose when to claim it. A reward is awarded automatically when a user meets one of its triggers, for example unlocking an achievement or reaching a streak length. It is only fulfilled when it is redeemed, which you do by calling the redeem endpoint when the user claims it in your product. Awarding a reward never changes a user’s points balance on its own.

Reward Types

There are two types of reward.

Points Rewards

Points rewards grant a set number of points from a points system when they are redeemed. Points are granted at the reward’s points value at the time of redemption, and respect any boosts and the points system’s maximum. If the maximum would be exceeded part way through redeeming several awards, the awards that fit are redeemed and the rest stay unredeemed so they can be retried.

Custom Rewards

Custom rewards do nothing inside Trophy when they are redeemed apart from sending the reward.redeemed webhook. Use them when you want to fulfill the reward yourself.

Rewards or Points Triggers?

Rewards and points triggers can both give users points when something happens, but they work differently.

	Points triggers	Rewards
Points are added to the user’s balance	Automatically, as soon as the trigger fires	Only when the reward is redeemed
Needs a redemption step in your product	No	Yes
Can grant something other than points	No	Yes, with custom rewards
Webhooks	`points.changed`	`reward.awarded` and `reward.redeemed`

If you want points to be applied to a user’s balance automatically and don’t need a redemption step, use a points trigger. Use rewards when users need to claim something, or when you need to fulfill it yourself.

Use Cases

Claimable bonuses

Award users bonus points for hitting a milestone, but let them tap a ‘Claim’ button in your product to receive them. The claim moment is a natural place for a celebration screen or animation.

Prizes and perks

Use custom rewards to hand out things that live outside Trophy, like a discount code, a free month or a physical prize. Trophy tells you when the reward is awarded and redeemed, and your system handles the rest.

Creating Rewards

To create a reward, head to the rewards page and follow the steps below.

New rewards are created as ‘Inactive’ with no triggers so you can configure and test them before they go live.

Click New Reward

Give the reward a name and a unique key. The key is what you’ll use to reference the reward in APIs, and can’t be changed after the reward is created.

Choose a reward type

Choose between a points reward and a custom reward.

Configure the reward

For a points reward, choose the points system and the number of points to grant when the reward is redeemed. You can also add a description which is returned from APIs to be displayed in your application.

Set a redemption limit (Optional)

Limit how many times each user can be awarded the reward. See redemption limits.

Add user filters (Optional)

Restrict the reward to users with specific custom user attributes. See user filters.

Add triggers and activate

Add one or more triggers and then change the reward’s status to active to make it live.

You can also create rewards and their triggers programmatically with the Admin API:

curl -X POST https://admin.trophy.so/v1/rewards \
     -H "X-API-KEY: <api-key>" \
     -H "Content-Type: application/json" \
     -d '[
       {
         "name": "Welcome bonus",
         "key": "welcome-bonus",
         "type": "points",
         "pointsSystemId": "points-system-uuid",
         "points": 100,
         "triggers": [
           {
             "type": "achievement",
             "achievementId": "achievement-uuid",
             "status": "active"
           }
         ]
       }
     ]'

await trophy.admin.rewards.create([
  {
    name: "Welcome bonus",
    key: "welcome-bonus",
    type: "points",
    pointsSystemId: "points-system-uuid",
    points: 100,
    triggers: [
      {
        type: "achievement",
        achievementId: "achievement-uuid",
        status: "active",
      },
    ],
  },
]);

client.admin.rewards.create(
    request=[
        {
            "name": "Welcome bonus",
            "key": "welcome-bonus",
            "type": "points",
            "points_system_id": "points-system-uuid",
            "points": 100,
            "triggers": [
                {
                    "type": "achievement",
                    "achievement_id": "achievement-uuid",
                    "status": "active",
                }
            ],
        }
    ],
)

$trophy->admin->rewards->create([
    [
        'name' => 'Welcome bonus',
        'key' => 'welcome-bonus',
        'type' => 'points',
        'pointsSystemId' => 'points-system-uuid',
        'points' => 100,
        'triggers' => [
            [
                'type' => 'achievement',
                'achievementId' => 'achievement-uuid',
                'status' => 'active',
            ],
        ],
    ],
]);

CreateRewardsResponse response = client.admin().rewards().create(
  List.of(
    CreateRewardRequestItem.builder()
      .name("Welcome bonus")
      .key("welcome-bonus")
      .type(CreateRewardRequestItemType.POINTS)
      .pointsSystemId("points-system-uuid")
      .points(100)
      .triggers(List.of(
        CreateRewardTriggerRequestItem.builder()
          .type(CreateRewardTriggerRequestItemType.ACHIEVEMENT)
          .achievementId("achievement-uuid")
          .status(CreateRewardTriggerRequestItemStatus.ACTIVE)
          .build()
      ))
      .build()
  )
);

response, err := client.Admin.Rewards.Create(
    context.TODO(),
    []*api.CreateRewardRequestItem{
        {
            Name: "Welcome bonus",
            Key: "welcome-bonus",
            Type: api.CreateRewardRequestItemTypePoints,
            PointsSystemId: api.String("points-system-uuid"),
            Points: api.Int(100),
            Triggers: []*api.CreateRewardTriggerRequestItem{
                {
                    Type: api.CreateRewardTriggerRequestItemTypeAchievement,
                    AchievementId: api.String("achievement-uuid"),
                    Status: api.CreateRewardTriggerRequestItemStatusActive.Ptr(),
                },
            },
        },
    },
)

await trophy.Admin.Rewards.CreateAsync(new[]
{
    new CreateRewardRequestItem
    {
        Name = "Welcome bonus",
        Key = "welcome-bonus",
        Type = CreateRewardRequestItemType.Points,
        PointsSystemId = "points-system-uuid",
        Points = 100,
        Triggers = new[]
        {
            new CreateRewardTriggerRequestItem
            {
                Type = CreateRewardTriggerRequestItemType.Achievement,
                AchievementId = "achievement-uuid",
                Status = CreateRewardTriggerRequestItemStatus.Active,
            },
        },
    },
});

result = client.admin.rewards.create([
  {
    name: 'Welcome bonus',
    key: 'welcome-bonus',
    type: 'points',
    points_system_id: 'points-system-uuid',
    points: 100,
    triggers: [
      {
        type: 'achievement',
        achievement_id: 'achievement-uuid',
        status: 'active'
      }
    ]
  }
])

Reward Triggers

Rewards are awarded through triggers. You can add as many triggers as you like to a reward, and each can be activated and deactivated independently.

Triggers work independently of each other. Each active trigger can award the reward on its own, so a user does not need to meet all of a reward’s triggers. For example, a reward with a streak trigger and an achievement trigger is awarded when the user reaches the streak length, and again when they complete the achievement. Any redemption limit applies across all of a reward’s triggers combined.

Types of Triggers

Metric Triggers

The reward is awarded every time the user’s total for a metric grows by the threshold you set, for example “award every 10 tasks completed”. Counting starts from when the trigger was activated. Activating the trigger again, or changing its metric, threshold or event attributes, starts a new count.

Streak Triggers

The reward is awarded every time the user’s current streak grows by the streak length you set, for example “award every 7 days”. The period the trigger was activated in counts as the first period, and changing the streak length starts a new count. A streak that ended before the trigger was activated, or broke after it, does not offset the count.

Streak triggers award repeatedly. Set a redemption limit of 1 to award the reward only once.

Achievement Triggers

The reward is awarded once, when the user completes a specific achievement. Users who completed the achievement before the trigger existed are not awarded.

Leaderboard Triggers

The reward is awarded to the user who finishes a leaderboard run at exactly the rank you set. For leaderboards with breakdown attributes, the user at that rank in each segment is awarded.

Creating Triggers

To add a trigger, open the reward from the rewards page and follow the steps below.

All new reward triggers are created as ‘Inactive’ to allow testing before deployment to production. A trigger’s type can only be changed while it’s inactive.

Click New Trigger

Choose a trigger type.

Set up the trigger

For a Metric trigger, choose the metric and the threshold.
For a Streak trigger, set the streak length.
For an Achievement trigger, choose the achievement.
For a Leaderboard trigger, choose the leaderboard and the rank.

Add attribute filters (Optional)

To limit a Metric trigger to events with specific custom event attributes, add one or more filters in the Event Attributes section. When you set multiple event attribute filters, all of them must match.
To limit any trigger to users with specific custom user attributes, add attributes and the desired values in the User Attributes section.

Click save, then activate

Once you’re happy the trigger will behave as expected, change its status to active to make it live.

Triggers can also be added with the Admin API:

curl -X POST https://admin.trophy.so/v1/rewards/{rewardId}/triggers \
     -H "X-API-KEY: <api-key>" \
     -H "Content-Type: application/json" \
     -d '[
       {
         "type": "metric",
         "metricId": "metric-uuid",
         "metricThreshold": 10,
         "status": "active"
       }
     ]'

await trophy.admin.rewards.triggers.create("reward-uuid", [
  {
    type: "metric",
    metricId: "metric-uuid",
    metricThreshold: 10,
    status: "active",
  },
]);

client.admin.rewards.triggers.create(
    reward_id="reward-uuid",
    request=[
        {
            "type": "metric",
            "metric_id": "metric-uuid",
            "metric_threshold": 10,
            "status": "active",
        }
    ],
)

$trophy->admin->rewards->triggers->create("reward-uuid", [
    [
        'type' => 'metric',
        'metricId' => 'metric-uuid',
        'metricThreshold' => 10,
        'status' => 'active',
    ],
]);

CreateRewardTriggersResponse response = client.admin().rewards().triggers().create(
  "reward-uuid",
  List.of(
    CreateRewardTriggerRequestItem.builder()
      .type(CreateRewardTriggerRequestItemType.METRIC)
      .metricId("metric-uuid")
      .metricThreshold(10)
      .status(CreateRewardTriggerRequestItemStatus.ACTIVE)
      .build()
  )
);

response, err := client.Admin.Rewards.Triggers.Create(
    context.TODO(),
    "reward-uuid",
    []*api.CreateRewardTriggerRequestItem{
        {
            Type: api.CreateRewardTriggerRequestItemTypeMetric,
            MetricId: api.String("metric-uuid"),
            MetricThreshold: api.Int(10),
            Status: api.CreateRewardTriggerRequestItemStatusActive.Ptr(),
        },
    },
)

await trophy.Admin.Rewards.Triggers.CreateAsync("reward-uuid", new[]
{
    new CreateRewardTriggerRequestItem
    {
        Type = CreateRewardTriggerRequestItemType.Metric,
        MetricId = "metric-uuid",
        MetricThreshold = 10,
        Status = CreateRewardTriggerRequestItemStatus.Active,
    },
});

result = client.admin.rewards.triggers.create(
  'reward-uuid',
  [
    {
      type: 'metric',
      metric_id: 'metric-uuid',
      metric_threshold: 10,
      status: 'active'
    }
  ]
)

When Rewards Are Not Awarded

Rewards are only awarded for things users do after a trigger is active. This means:

Existing achievement completions don’t award rewards. If a user completed an achievement before you added an achievement trigger, they aren’t awarded the reward.
Backdated achievements don’t award rewards. When you activate or edit an achievement, or set a user’s signUpDate, Trophy completes achievements for users who already qualify. These silent completions don’t award rewards.
Past progress doesn’t count. Metric and streak triggers count from when the trigger was activated, so progress users made before then isn’t awarded.

Inactive rewards and inactive triggers stop new awards, but existing awards can still be redeemed. Archived rewards are not awarded, listed or redeemed.

Redemption Limits

Set a redemption limit on a reward to cap how many times each user can be awarded it. Once a user reaches the limit they stop being awarded the reward.

User Filters

Add user attribute filters to a reward, or to individual triggers, to control who can be awarded. A user must match the reward’s filters and the trigger’s filters to be awarded.

Tracking a User’s Rewards

Rewards Awarded by an Event

When a metric event or an achievement completion awards a reward, the response includes it in the rewards array. This is the same shape as the response from the user rewards endpoint. Replaying an event with the same idempotency key returns an empty array. Use this to show a “You earned a reward” message the moment it happens.

Response

{
  ...,
  "rewards": [
    {
      "id": "e1a9c0d4-2b7f-4f3e-8a6d-5c9b1f2e3a47",
      "awardedAt": "2026-10-20T09:15:00Z",
      "redeemed": false,
      "redeemedAt": null,
      "reward": {
        "id": "7c3f1a52-4d1e-4b8a-9a55-1d6f0b7c2e11",
        "key": "streak-bonus",
        "name": "Streak bonus",
        "description": null,
        "type": "points",
        "points": 50,
        "pointsSystemId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
        "pointsSystemKey": "xp"
      },
      "trigger": {
        "id": "b2d4e6f8-1a3c-4e5b-9d7f-0a2c4e6f8b1d",
        "type": "streak",
        "streakLengthThreshold": 7
      }
    }
  ],
  ...
}

Awards from other sources, such as leaderboard triggers when a run finishes, are not returned from API calls. Use the reward.awarded webhook or the user rewards endpoint to find them.

Listing a User’s Rewards

Use the user rewards endpoint to list the rewards a user has been awarded. Filter by redeemed to show only rewards waiting to be claimed, and by date range to page through history.

curl --request GET \
  --url "https://api.trophy.so/v1/users/{id}/rewards?redeemed=false" \
  --header 'X-API-KEY: <api-key>'

trophy.users.rewards("user-id", {
  redeemed: false,
});

client.users.rewards(
    id="user-id",
    redeemed=False,
)

$request = new UsersRewardsRequest([
    'redeemed' => false
]);

$trophy->users->rewards("user-id", $request);

UsersRewardsRequest request = UsersRewardsRequest.builder()
      .redeemed(false)
      .build();

List<UserRewardResponse> response = client.users().rewards("user-id", request);

redeemed := false

response, err := client.Users.Rewards(
    "user-id",
    &api.UsersRewardsRequest{
        Redeemed: &redeemed,
    },
)

await trophy.Users.RewardsAsync("user-id", new UsersRewardsRequest {
   Redeemed = false
});

result = client.users.rewards(
  :id => 'user-id',
  :redeemed => false
)

Response

[
  {
    "id": "e1a9c0d4-2b7f-4f3e-8a6d-5c9b1f2e3a47",
    "awardedAt": "2026-10-20T09:15:00Z",
    "redeemed": false,
    "redeemedAt": null,
    "reward": {
      "id": "7c3f1a52-4d1e-4b8a-9a55-1d6f0b7c2e11",
      "key": "welcome-bonus",
      "name": "Welcome bonus",
      "description": "Points for finishing onboarding",
      "type": "points",
      "points": 100,
      "pointsSystemId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
      "pointsSystemKey": "xp"
    },
    "trigger": {
      "id": "b2d4e6f8-1a3c-4e5b-9d7f-0a2c4e6f8b1d",
      "type": "metric",
      "metricId": "d01dcbcb-d51e-4c12-b054-dc811dcdc623",
      "metricThreshold": 10
    }
  }
]

Each award includes the trigger that earned it as it is configured now, with only the fields for its current type.

Redeeming Rewards

When a user claims a reward in your product, call the redeem endpoint with the reward’s key and the user’s ID.

curl -X POST https://api.trophy.so/v1/rewards/welcome-bonus/redeem \
     -H "X-API-KEY: <api-key>" \
     -H "Content-Type: application/json" \
     -d '{
  "user": {
    "id": "18"
  }
}'

trophy.rewards.redeem("welcome-bonus", {
  user: {
    id: "18",
  },
});

client.rewards.redeem(
    key="welcome-bonus",
    user={"id": "18"},
)

$request = new RewardsRedeemRequest([
    'user' => new UpsertedUser([
        'id' => '18'
    ])
]);

$trophy->rewards->redeem("welcome-bonus", $request);

RedeemRewardRequest request = RedeemRewardRequest.builder()
      .user(
        UpsertedUser.builder()
          .id("18")
          .build()
      )
      .build();

RedeemRewardResponse response = client.rewards().redeem("welcome-bonus", request);

response, err := client.Rewards.Redeem(
    "welcome-bonus",
    &api.RedeemRewardRequest{
        User: &api.UpsertedUser{
            Id: "18",
        },
    },
)

var request = new RedeemRewardRequest {
   User = new UpsertedUser {
      Id = "18"
   }
};

await trophy.Rewards.RedeemAsync("welcome-bonus", request);

result = client.rewards.redeem(
  :key => 'welcome-bonus',
  :user => {
    :id => '18'
  }
)

Trophy redeems all of the user’s unredeemed awards for that reward at once, oldest first, and returns them in redemptions. For points rewards, the response also includes the combined points granted and any leaderboards the user’s rank changed on.

Response

{
  "reward": {
    "id": "7c3f1a52-4d1e-4b8a-9a55-1d6f0b7c2e11",
    "key": "welcome-bonus",
    "name": "Welcome bonus",
    "description": "Points for finishing onboarding",
    "type": "points",
    "points": 100,
    "pointsSystemId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
    "pointsSystemKey": "xp"
  },
  "redemptions": [
    {
      "id": "e1a9c0d4-2b7f-4f3e-8a6d-5c9b1f2e3a47",
      "awardedAt": "2026-10-20T09:15:00Z",
      "redeemedAt": "2026-10-28T12:00:00Z"
    }
  ],
  "points": {
    "xp": {
      "id": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
      "key": "xp",
      "name": "XP",
      "description": null,
      "badgeUrl": null,
      "maxPoints": null,
      "total": 350,
      "added": 100,
      "awards": [...]
    }
  },
  "leaderboards": {}
}

Redeeming still works for inactive rewards, but not for archived or deleted ones. The request returns an error when it can’t redeem anything:

404 if the user was never awarded the reward.
409 if every award has already been redeemed.

If the points maximum is reached part way through, the awards that fit are redeemed and the rest stay unredeemed so you can retry later.

Webhooks

Trophy sends two webhooks for rewards:

reward.awarded fires when a user is awarded a reward. Nothing has been applied yet.
reward.redeemed fires when the reward is redeemed, once for each award. For custom rewards, this is your cue to fulfill the reward.

Both include the reward, the redemption and the trigger that earned it.

Webhook reward.awarded — request body

{
  "type": "reward.awarded",
  "timestamp": "2026-10-20T09:15:00Z",
  "user": {
    "id": "user-id",
    "email": "user@example.com",
    "tz": "Europe/London",
    "subscribedToEmails": true,
    "created": "2021-01-01T00:00:00Z",
    "updated": "2021-01-01T00:00:00Z",
    "attributes": {
      "department": "engineering",
      "role": "developer"
    }
  },
  "reward": {
    "id": "7c3f1a52-4d1e-4b8a-9a55-1d6f0b7c2e11",
    "key": "welcome-bonus",
    "name": "Welcome bonus",
    "description": "Points for finishing onboarding",
    "type": "points",
    "points": 100,
    "pointsSystemId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
    "pointsSystemKey": "xp"
  },
  "redemption": {
    "id": "e1a9c0d4-2b7f-4f3e-8a6d-5c9b1f2e3a47",
    "redeemed": false,
    "awardedAt": "2026-10-20T09:15:00Z",
    "redeemedAt": null,
    "trigger": {
      "id": "b2d4e6f8-1a3c-4e5b-9d7f-0a2c4e6f8b1d",
      "type": "achievement",
      "achievementId": "5100fe51-6bce-6j44-b0hs-bddc4e123682"
    }
  }
}

Webhook reward.redeemed — request body

{
  "type": "reward.redeemed",
  "timestamp": "2026-10-28T12:00:00Z",
  "user": {
    "id": "user-id",
    "email": "user@example.com",
    "tz": "Europe/London",
    "subscribedToEmails": true,
    "created": "2021-01-01T00:00:00Z",
    "updated": "2021-01-01T00:00:00Z",
    "attributes": {
      "department": "engineering",
      "role": "developer"
    }
  },
  "reward": {
    "id": "7c3f1a52-4d1e-4b8a-9a55-1d6f0b7c2e11",
    "key": "welcome-bonus",
    "name": "Welcome bonus",
    "description": "Points for finishing onboarding",
    "type": "points",
    "points": 100,
    "pointsSystemId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
    "pointsSystemKey": "xp"
  },
  "redemption": {
    "id": "e1a9c0d4-2b7f-4f3e-8a6d-5c9b1f2e3a47",
    "redeemed": true,
    "awardedAt": "2026-10-20T09:15:00Z",
    "redeemedAt": "2026-10-28T12:00:00Z",
    "trigger": {
      "id": "b2d4e6f8-1a3c-4e5b-9d7f-0a2c4e6f8b1d",
      "type": "achievement",
      "achievementId": "5100fe51-6bce-6j44-b0hs-bddc4e123682"
    }
  }
}

Rewards and Points

Points granted by redeeming a reward behave like any other points:

They show up in the user’s points history and points summary.
They update points leaderboards for that points system.
They are not included in the points returned from metric events and achievement completions, since nothing is granted until redemption.

Rewards Analytics

Each reward in the Trophy dashboard has built-in analytics including:

Awards over time
Redemptions over time
Awards broken down by trigger type
For points rewards, an estimate of the points awarded and the points actually redeemed (including boosts and the points maximum)

Filter by user attributes to compare how different groups of users engage with a reward. Points granted by rewards also appear as their own row in the points source chart.

Get Support

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

Getting Started

Features

Platform

Account

What are Rewards?

Reward Types

Points Rewards

Custom Rewards

Rewards or Points Triggers?

Use Cases

Claimable bonuses

Prizes and perks

Creating Rewards

Reward Triggers

Types of Triggers

Metric Triggers

Streak Triggers

Achievement Triggers

Leaderboard Triggers

Creating Triggers

When Rewards Are Not Awarded

Redemption Limits

User Filters

Tracking a User’s Rewards

Rewards Awarded by an Event

Listing a User’s Rewards

Redeeming Rewards

Webhooks

Rewards and Points

Rewards Analytics

Get Support

​What are Rewards?

​Reward Types

​Points Rewards

​Custom Rewards

​Rewards or Points Triggers?

​Use Cases

​Claimable bonuses

​Prizes and perks

​Creating Rewards

​Reward Triggers

​Types of Triggers

​Metric Triggers

​Streak Triggers

​Achievement Triggers

​Leaderboard Triggers

​Creating Triggers

​When Rewards Are Not Awarded

​Redemption Limits

​User Filters

​Tracking a User’s Rewards

​Rewards Awarded by an Event

​Listing a User’s Rewards

​Redeeming Rewards

​Webhooks

​Rewards and Points

​Rewards Analytics

​Get Support

What are Rewards?

Reward Types

Points Rewards

Custom Rewards

Rewards or Points Triggers?

Use Cases

Claimable bonuses

Prizes and perks

Creating Rewards

Reward Triggers

Types of Triggers

Metric Triggers

Streak Triggers

Achievement Triggers

Leaderboard Triggers

Creating Triggers

When Rewards Are Not Awarded

Redemption Limits

User Filters

Tracking a User’s Rewards

Rewards Awarded by an Event

Listing a User’s Rewards

Redeeming Rewards

Webhooks

Rewards and Points

Rewards Analytics

Get Support