Points API

The API for XP, coins and loyalty points

Add points to your app in under an hour. Trophy handles awarding points automatically based on user actions, promoting users between levels, and applying boost multiplers during limited-time events, all with a fully traceable points ledger and cheat prevention safeguards. Start for free, scale to millions of users.

Get API Key API Reference

SDKs for

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

Lightning-Fast Integration

Simple APIs you'll Love

Use our pre-built gamification API to effortlessly build engaging user experiences. Get a team that's 100% focused on engagement.

Get Started API Reference

Type-safe SDKs.: We spend time worrying about abstractions and let you focus on what matters: building a great experience for your users.
Intuitive documentation.: Documentation built by developers for developers. Get started in minutes, not hours.
Effortless debugging.: Get to the root of the issue fast with detailed event logs and error messages.

// Fetch and display points UI

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

// Render XP progress bar
return (
  <XPBar
    total={points.total}
    name={points.name}
    awards={points.awards}
  />
);

Gamification UI Library

Pixel-perfect points UI components

Use our open-source gamification UI components as the foundation for your design system. Customize as you see fit. Designed to work perfectly with the Trophy API.

Get Started UI Library

One-command install: Add any component to your project with a single CLI command. No extra dependencies to manage.
Fully customizable: Every component lives in your codebase. Tweak styles, layout, and behavior to match your brand.
Open-source.: MIT licensed and community-driven. Use in personal projects or production apps without restrictions.

Built for production workloads

Reliable infrastructure designed for performance at scale.

Historical Uptime: 99.99%
Avg Response Time: <50ms
Integration Time: < 1 hour
Users Tracked: 1M+

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?

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.

Build

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

Why does it matter?

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.

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.

FAQ

Frequently asked questions

Have a different question and can’t find the answer you’re looking for?

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.

Gamification infrastructure that retains users

Boost retention and customer lifetime value. Try for free up to 100 MAUs.

Get Started Read Docs