Rewards API

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.

Get API keyAPI reference
SDKs for
NodeJSGoJava.NETPHPPythonRuby

Quickstart

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.

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);

Buy vs. build

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.

Integration Time

Rewards are awarded automatically from the metric events you already send. Configure rewards, triggers, and limits in the dashboard in minutes.
Build
Build reward definitions, trigger evaluation across metrics, streaks, achievements, and leaderboards, a redemption flow, and fulfillment hooks. Expect 3-5 weeks.
Why does it matter?
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.
Build
You must make sure rewards are never awarded twice, never lost when fulfillment fails, and never redeemed twice under concurrent requests.
Why does it matter?
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
Build retry-safe fulfillment for each reward type, plus the event delivery to hand custom rewards off to other systems.
Why does it matter?
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.
Build
Every new reward or threshold change requires code changes and a release, which creates a bottleneck between product and engineering.
Why does it matter?
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
Build reporting on top of your rewards tables to understand which rewards users redeem and what they cost.
Why does it matter?
Without analytics you can’t tell which rewards motivate users and which ones they ignore.

Endpoints

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}/eventView docs

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

Path Parameters

keystringrequired

Unique reference of the metric as set when created.

Request Body

userUserrequired

The user that triggered the event (must include id).

valuenumberrequired

The value to add to the user's current total for the given metric.

Response

eventIdstring

Unique identifier for the created event.

totalnumber

The user's new total for this metric.

rewardsUserReward[]

Rewards awarded by this event. Empty when nothing was awarded or the event was replayed.

Example
import { TrophyApiClient } from '@trophyso/node';

const trophy = new TrophyApiClient({
  apiKey: 'YOUR_API_KEY'
});

// 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}/rewardsView docs

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

Path Parameters

idstringrequired

ID of the user.

Query Parameters

redeemedboolean

Only return rewards that have or have not been redeemed.

startDatestring

Inclusive start of the awarded-at range (YYYY-MM-DD).

endDatestring

Inclusive end of the awarded-at range (YYYY-MM-DD).

skipinteger

Number of rewards to skip (default: 0).

limitinteger

Maximum number of rewards to return (default and max: 100).

Response

idstring

ID of the reward redemption.

redeemedboolean

Whether the reward has been redeemed.

rewardReward

The reward, including its type and points.

triggerTrigger

The trigger that awarded the reward.

Example
import { TrophyApiClient } from '@trophyso/node';

const trophy = new TrophyApiClient({
  apiKey: 'YOUR_API_KEY'
});

// 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}/redeemView docs

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

Path Parameters

keystringrequired

Key of the reward to redeem.

Request Body

userUserrequired

The user redeeming the reward (must include id).

Response

rewardReward

The reward that was redeemed.

redemptionsRedemption[]

The awards redeemed by this request, oldest first.

pointsPoints

Points granted by a points reward, keyed by points system.

leaderboardsLeaderboards

Points leaderboards the user’s rank changed on.

Example
import { TrophyApiClient } from '@trophyso/node';

const trophy = new TrophyApiClient({
  apiKey: 'YOUR_API_KEY'
});

// 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: {}
// }

Built for production workloads

Reliable infrastructure designed for performance at scale.

Uptime SLA
99.99%
p95 API Latency
200ms
Monthly API Requests
150M
Users Tracked
1M+

FAQ

Frequently asked questions

Have a different question and can’t find the answer you’re looking for? Send us an email.

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 endpoint to show unredeemed rewards and the redeem 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.

Get started

Up and running in minutes

Start

Start building

Integrate in minutes, interpret in hours. No credit card required.

Start 30-day trial

Explore

See what's possible

Explore how Trophy can increase user engagement and retention.

Book a call

Compare

Compare plans

Compare Pro, Business, and Enterprise, and estimate cost from monthly active users.

See pricing