---
title: Rewards API
canonical_url: "https://trophy.so/developers/rewards"
description: "The rewards API for consumer apps. Award points or custom rewards when users hit milestones, let users redeem them in your app, and fulfill rewards with webhooks. SDKs for Node.js, Python, Go, Java, PHP, Ruby, and .NET."
---

# The rewards API for consumer apps

Trophy is the rewards API for consumer apps, adding redeemable bonus points, discount codes, and custom prizes to your app with a few API calls. Award rewards automatically when users hit milestones, let them redeem rewards when they are ready, and fulfill custom rewards from your own systems with webhooks.

[Full feature documentation](https://docs.trophy.so/features/rewards.md)

## Quickstart: award and redeem a reward

Configure a reward and its triggers in the Trophy dashboard (or via MCP), then send metric events as usual. Show users the rewards they earned and redeem them from your app.

```ts
import { TrophyApiClient } from "@trophyso/node";

const trophy = new TrophyApiClient({ apiKey: process.env.TROPHY_API_KEY });

// 1. Track the metric that powers your reward trigger
const eventResponse = await trophy.metrics.event("workouts", {
  user: { id: "user-123" },
  value: 1,
});

console.log("Rewards awarded:", eventResponse.rewards);

// 2. List the user's rewards that are waiting to be redeemed
const unredeemed = await trophy.users.rewards("user-123", {
  redeemed: false,
});

// 3. Redeem a reward when the user taps redeem
const redemption = await trophy.rewards.redeem("welcome-bonus", {
  user: { id: "user-123" },
});

console.log("Redeemed:", redemption.redemptions);
console.log("Points granted:", redemption.points);
```

## Why use Trophy's rewards API?

A rewards system needs to award each prize exactly once, keep it safe until the user redeems it, and pay it out reliably. Getting that right in-house takes longer than it looks.

| Consideration | Trophy | Build in-house | Why it matters |
| --- | --- | --- | --- |
| Integration Time | Rewards are awarded automatically from the metric events you already send. Configure rewards, triggers, and limits in the dashboard in minutes. | Build reward definitions, trigger evaluation across metrics, streaks, achievements, and leaderboards, a redemption flow, and fulfillment hooks. Expect 3-5 weeks. | Rewards sit on top of every other gamification mechanic. Building them means hooking into each mechanic’s completion logic and keeping them in sync. |
| Reliability | Every award is idempotent, so retries and replays never double-award, and concurrent redeem requests never redeem the same award twice. | You must make sure rewards are never awarded twice, never lost when fulfillment fails, and never redeemed twice under concurrent requests. | Rewards often have real-world value. A duplicated discount code or a lost prize is a support ticket and a broken promise to your users. |
| Fulfillment | Points rewards grant points on redemption with boosts and caps applied. Custom rewards send signed reward.awarded and reward.redeemed webhooks. | Build retry-safe fulfillment for each reward type, plus the event delivery to hand custom rewards off to other systems. | Fulfillment touches your points ledger, billing, and third-party systems. Each one needs its own failure handling. |
| Ongoing Maintenance | Non-technical users can add rewards, change thresholds, set redemption limits, and target user cohorts from the dashboard. | Every new reward or threshold change requires code changes and a release, which creates a bottleneck between product and engineering. | Growth teams want to launch and tune rewards for campaigns and seasons. Making every change a code change slows experimentation. |
| Analytics | Track awards and redemptions over time, compare trigger types, and measure the points rewards actually pay out. | Build reporting on top of your rewards tables to understand which rewards users redeem and what they cost. | Without analytics you can’t tell which rewards motivate users and which ones they ignore. |

## Rewards endpoints

Use Trophy's rewards API to show users the rewards they've earned and redeem them from your app. Rewards are awarded automatically from metric events, streaks, achievements, and leaderboards.

### `POST /metrics/{key}/event`

Send a metric event to track user activity. The response includes any rewards the event awarded.

Docs: https://docs.trophy.so/api-reference/endpoints/events/submit-a-metric-event.md

```ts
// Track a user event
const response = await trophy.metrics.event("workouts", {
  user: {
    id: "user-123"
  },
  value: 1
});

// Rewards awarded by this event:
// [{
//   id: "e1a9c0d4-...",
//   redeemed: false,
//   reward: { key: "streak-bonus", type: "points", points: 50 },
//   trigger: { type: "streak", streakLengthThreshold: 7 }
// }]
console.log(response.rewards);
```

### `GET /users/{id}/rewards`

Get a user's rewards, with the reward and the trigger that awarded it.

Docs: https://docs.trophy.so/api-reference/endpoints/users/get-a-users-rewards.md

```ts
// List rewards waiting to be redeemed
const rewards = await trophy.users
  .rewards("user-123", { redeemed: false });

// Response:
// [{
//   id: "e1a9c0d4-...",
//   awardedAt: "2026-10-20T09:15:00Z",
//   redeemed: false,
//   reward: {
//     key: "welcome-bonus",
//     name: "Welcome bonus",
//     type: "points",
//     points: 100
//   },
//   trigger: {...}
// }]
```

### `POST /rewards/{key}/redeem`

Redeem all of a user's unredeemed awards for a reward. Points rewards grant points, and every redemption sends a reward.redeemed webhook.

Docs: https://docs.trophy.so/api-reference/endpoints/rewards/redeem-a-reward.md

```ts
// Redeem when the user taps "Redeem"
const redemption = await trophy.rewards
  .redeem("welcome-bonus", {
    user: { id: "user-123" }
  });

// Response:
// {
//   reward: { key: "welcome-bonus", ... },
//   redemptions: [{
//     id: "e1a9c0d4-...",
//     redeemedAt: "2026-10-28T12:00:00Z"
//   }],
//   points: { xp: { total: 350, added: 100 } },
//   leaderboards: {}
// }
```

## Code examples

### rewards-inbox.tsx

```ts
// Fetch and display a user's unredeemed rewards

const rewards = await trophy.users
  .rewards("user-123", { redeemed: false });

// Render a redeemable rewards list
return (
  <RewardsInbox
    rewards={rewards}
    onRedeem={(key) => redeemReward(key)}
  />
);
```

### reward-webhook.ts

```ts
// Fulfill custom rewards from a webhook
switch (payload.type) {
  case "reward.redeemed":
    if (payload.reward.type === "custom") {
      await issueDiscountCode(payload.user.id);
    }
    break;
}
```

## FAQ

### How do I add redeemable rewards to my app?

Create a reward and its triggers in the Trophy dashboard, then send metric events as usual. Trophy awards rewards automatically when users meet a trigger. Use the [user rewards](https://docs.trophy.so/api-reference/endpoints/users/get-a-users-rewards) endpoint to show unredeemed rewards and the [redeem](https://docs.trophy.so/api-reference/endpoints/rewards/redeem-a-reward) endpoint when the user redeems one.

### What kinds of rewards can I give users?

Points rewards grant a set number of points from any points system when they are redeemed. Custom rewards can be anything you fulfill yourself, like discount codes, free subscription months, gift cards, or physical prizes. Trophy sends a reward.redeemed webhook so your system knows when to fulfill them.

### What milestones can award a reward?

Rewards can be awarded every time a user’s metric total grows by a threshold, every time their streak grows by a set length, when they complete an achievement, or when they finish a leaderboard at a specific rank. A reward can have as many triggers as you like.

### How does Trophy prevent rewards being awarded or redeemed twice?

Every award has a unique occurrence key, so retried and replayed events never double-award. Redeeming is safe under concurrent requests, and if a points cap blocks a points reward, the award stays unredeemed so it can be retried later.

### Can I limit how many times a user earns a reward?

Yes. Set a redemption limit on a reward to cap how many times each user can be awarded it, and add user attribute filters to the reward or its triggers to target specific cohorts.

### Can I display rewards in React, React Native, or mobile apps?

Yes. Trophy’s server-side SDKs (Node.js, Python, Go, Java, PHP, Ruby, and .NET) return rewards from your backend, which you can render in any frontend — React, React Native, Next.js, Swift, Kotlin, Flutter, or any other framework.