Points API

The points API for consumer apps

Trophy is the points API for consumer apps, adding XP, coins, loyalty points, and levels to your app with a few API calls. Automatically award points for user actions, level up users, and apply multiplers for events, all with full ledger tracking and anti-cheat safeguards.

Get API key API reference

SDKs for

Quickstart

Quickstart: award and read XP

Configure a points system and metric triggers in the Trophy dashboard (or via MCP), then award points by sending metric events. Fetch the user’s balance, awards, and level for your UI.

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

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

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

console.log("Points awarded:", eventResponse.points);

// 2. Read the user's balance, recent awards, level, and maxPoints cap
const points = await trophy.users.points("user-123", "xp");

console.log("Total:", points.total);
console.log("Max points:", points.maxPoints);
console.log("Recent awards:", points.awards);

Buy vs. build

Why use Trophy's points API?

Building a reliable points system API requires ledger-grade consistency. Every award, multiplier, and deduction must be atomic — and getting that right in-house is harder than it looks.

Key Considerations

Build

Why does it matter?

Integration Time

Points accrue automatically from metric events with a full ledger history and anti-cheating safeguards. Configure multipliers and level thresholds in the dashboard in minutes.

Build custom points ledger, transaction history, multiplier system and level progression. Expect 3-5 weeks, or longer for anti-cheating safeguards.

Point systems require transactional consistency — every award, deduction, and multiplier must be atomic. Building this correctly requries exhaustive testing and validation that most teams underestimate.

Reliability

Atomic point transactions with full audit trail. No double-counting, no lost points.

You must ensure points are never double-awarded or silently dropped, even under concurrent events, retries, and partial failures.

Points are a form of virtual currency. Users notice when their balance is wrong, and debugging ledger inconsistencies after the fact is painful if your domain model hasn't been designed to support this.

Scalability

Trophy handles millions of high-frequency points calculations every day across hundreds of thousands of users in real time.

Real-time point aggregation across multiple event sources becomes a hot-path database problem as your user base grows.

Point balance queries are among the most frequent operations in a gamification system. Caching helps until cache invalidation introduces its own consistency bugs.

Ongoing Maintenance

Non-techincal users can adjust multipliers, add point sources, and modify level thresholds from the dashboard.

Changing point values, adding new multiplier rules, or adjusting level thresholds requires code changes and careful data migration work that cause bottlenecks between product and engineering.

Product teams will want to tune point economies frequently. Making every adjustment a code change creates friction between product and engineering.

Feature Development

Level progression, boost mechanics, multiple point currencies, and detailed history ship regularly.

Each new feature — multipliers, boosts, level-up rewards, seasonal points — adds complexity to your ledger and aggregation logic.

Point economies evolve as you learn what motivates users. You'll want to experiment with multipliers, decay, and bonus events without re-engineering your ledger.

Integration Time

Points accrue automatically from metric events with a full ledger history and anti-cheating safeguards. Configure multipliers and level thresholds in the dashboard in minutes.

Build

Build custom points ledger, transaction history, multiplier system and level progression. Expect 3-5 weeks, or longer for anti-cheating safeguards.

Why does it matter?

Reliability

Atomic point transactions with full audit trail. No double-counting, no lost points.

Build

You must ensure points are never double-awarded or silently dropped, even under concurrent events, retries, and partial failures.

Why does it matter?

Scalability

Trophy handles millions of high-frequency points calculations every day across hundreds of thousands of users in real time.

Build

Real-time point aggregation across multiple event sources becomes a hot-path database problem as your user base grows.

Why does it matter?

Point balance queries are among the most frequent operations in a gamification system. Caching helps until cache invalidation introduces its own consistency bugs.

Ongoing Maintenance

Non-techincal users can adjust multipliers, add point sources, and modify level thresholds from the dashboard.

Build

Changing point values, adding new multiplier rules, or adjusting level thresholds requires code changes and careful data migration work that cause bottlenecks between product and engineering.

Why does it matter?

Product teams will want to tune point economies frequently. Making every adjustment a code change creates friction between product and engineering.

Feature Development

Level progression, boost mechanics, multiple point currencies, and detailed history ship regularly.

Build

Each new feature — multipliers, boosts, level-up rewards, seasonal points — adds complexity to your ledger and aggregation logic.

Why does it matter?

Point economies evolve as you learn what motivates users. You'll want to experiment with multipliers, decay, and bonus events without re-engineering your ledger.

Endpoints

Points endpoints

Use Trophy's points API to award and track XP, loyalty points, or any custom currency. Points accrue automatically from metric events with full ledger history and anti-cheating safeguards.

POST/metrics/{key}/eventView docs

Send a metric event to track user activity and award points.

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.

pointsPoints[]

Points awarded by this event, keyed by points system.

Example

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

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


// Track a user event
await trophy.metrics.event("lessons", {
    user: {
      id: "user-123"
    },
    value: 1
  }
);

// This single event:
// - Records user activity
// - Awards points
// - Returns new points balance

GET/users/{id}/points/{key}View docs

Get a user's points for a specific points system, including recent awards.

Path Parameters

idstringrequired

ID of the user.

keystringrequired

Key of the points system.

Query Parameters

awardsinteger

Number of recent point awards to return (default: 10).

Response

namestring

Display name of the points system.

totalnumber

Total points accumulated.

maxPointsnumber

Maximum points cap (null if unlimited).

awardsAward[]

Recent point awards with trigger details.

Example

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

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

// Fetch user points balance
const points = await trophy.users
  .points("user-123", "xp");

// Response:
// {
//   key: "xp", 
//   name: "XP",
//   total: 2450,
//   awards: [{ 
//     awarded: 10, 
//     trigger: {...} 
//   }]
// }

POST/points/boostsView docs

Create points boosts for multiple users. Boosts multiply points earned during a time period.

Request Body

systemKeystringrequired

Key of the points system to boost.

boostsarrayrequired

Array of boost objects with userId, name, multiplier, start, and optional end.

Response

createdBoost[]

Successfully created boost objects.

issuesIssue[]

Warnings or errors for each boost request.

Example

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

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

// Create a points boost
await trophy.admin.points.boosts.create({
  systemKey: "xp",
  boosts: [{
    userId: "user-123",
    name: "Double XP Weekend",
    start: '2024-01-01',
    end: '2024-01-03',
    multiplier: 2
  }]
});

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 experience points (XP) and loyalty points work?

Trophy's points API lets you define any type of points system — experience points, coins, loyalty points — and configure which user actions award them and how many. When users trigger those actions through metric events, points are awarded and tracked automatically with a full ledger history.

Can I build a loyalty rewards program with this API?

Yes. Trophy's loyalty points API supports any reward mechanic — loyalty points for purchases, XP for engagement, coins for referrals. You configure point values per metric, set caps, set up levels for progression tiers, and use boosts for limited-time events like double-points weekends.

How does Trophy prevent cheating/farming?

Trophy's points API has built in idempotency and deduplication to prevent cheating and farming. Every point award is atomic and only applied once, even if the event is sent multiple times.

How do I display points and levels in my app?

Use the get user points endpoint to fetch a user's total points, recent awards, current level, and any configured caps. You can then render a progress bar, level badge, or any other UI element in your app with full control.

Can I have multiple points systems in the same app?

Yes. Trophy's points API supports multiple independent points systems in the same app — "XP" for progression, "coins" for a virtual currency, "loyalty" for a rewards programme. Each system is configured and tracked independently with its own point values, caps, and boost rules.

Can I display points and levels in React, React Native, or mobile apps?

Yes. Adding points and levels to your app with Trophy uses server-side SDKs (Node.js, Python, Go, Java, PHP, Ruby, and .NET) to handle points logic on your backend. The API returns point totals and award history that 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 for free

Explore

See what's possible

Explore how Trophy can increase user engagement and retention.

Book a call

Compare

Compare plans

Understand the free tier limits and Trophy's usage-based model.

See pricing