Points API
Add points & XP to your app in minutes
Build engaging point systems that reward user behavior. Award XP automatically, track levels, and create progression mechanics that keep users coming back.
SDKs for
Endpoints
Points endpoints
Award and track user points programmatically. Points are automatically awarded based on metrics, or you can award bonus points manually.
Get a user's points for a specific points system, including recent awards.
Path Parameters
idstringrequiredID of the user.
keystringrequiredKey of the points system.
Query Parameters
awardsintegerNumber of recent point awards to return (default: 10).
Response
namestringDisplay name of the points system.
totalnumberTotal points accumulated.
maxPointsnumberMaximum 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: {...}
// }]
// }Create points boosts for multiple users. Boosts multiply points earned during a time period.
Request Body
systemKeystringrequiredKey of the points system to boost.
boostsarrayrequiredArray 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",
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.
- 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}
/>
);Built for production workloads
Reliable infrastructure designed for performance at scale.
- API Uptime
- 99.99%
- Avg Response Time
- <50ms
- Integration Time
- < 1 hour
- API Calls / Month
- 10M+
Buy vs. Build
Why use Trophy for points & XP?
Point systems require ledger-grade consistency. Building and maintaining a reliable point economy in-house is harder than it looks.
| Key Considerations | Build | Why does it matter? | |
|---|---|---|---|
| Integration Time | Points accrue automatically from metric events. Configure multipliers and level thresholds in the dashboard. | Build point ledger, transaction history, multiplier system, level progression, and anti-abuse safeguards. Expect 3-5 weeks. | Point systems require transactional consistency — every award, deduction, and multiplier must be atomic. Building this correctly from scratch takes longer than expected. |
| 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. |
| Scalability | Trophy handles high-frequency point calculations across millions 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 reads in a gamification system. Caching helps until cache invalidation introduces its own consistency bugs. |
| Ongoing Maintenance | 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. | 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. Configure multipliers and level thresholds in the dashboard.
Build
Build point ledger, transaction history, multiplier system, level progression, and anti-abuse safeguards. Expect 3-5 weeks.
Why does it matter?
Point systems require transactional consistency — every award, deduction, and multiplier must be atomic. Building this correctly from scratch takes longer than expected.
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.
Scalability
Trophy handles high-frequency point calculations across millions 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 reads in a gamification system. Caching helps until cache invalidation introduces its own consistency bugs.
Ongoing Maintenance
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.
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
Points, XP & Rewards FAQ
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?
- You create points systems in the Trophy dashboard (e.g., "XP", "coins", "loyalty points") and configure which metric events award points and how many. When users trigger events, points are automatically awarded and tracked.
- Can I build a loyalty rewards program with this API?
- Yes. Trophy's points system supports any reward mechanic — loyalty points for purchases, XP for engagement, coins for referrals. You configure point values per metric, set caps, and use boosts for promotions like double-points weekends.
- What are points boosts and multipliers?
- Boosts let you temporarily multiply the points a user earns. For example, a 2x boost during a promotional event doubles all XP earned. Boosts can have start and end dates and are applied automatically.
- 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, and any configured max. You handle the level calculation and UI rendering in your app based on the point totals.
- Can I have multiple points systems in the same app?
- Yes. You can create as many points systems as you need — for example, "XP" for progression, "coins" for a virtual currency, and "loyalty" for a rewards program. Each system is tracked independently with its own configuration.
- Can I display XP and points in React, React Native, or mobile apps?
- Yes. Trophy's server-side SDKs (Node.js, Python, Go, Java, PHP, Ruby, .NET) 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.
