Achievements API
The API for achievements and badges
Add achievements and badges to your app in under an hour. Trophy handles trigger evaluation, badge hosting, progress tracking and rarity calculations so you can focus on the user experience. Start for free, scale to millions of users.
SDKs for
Endpoints
Achievement endpoints
Use Trophy's achievement tracking API to award badges automatically from metric events, streak milestones, or direct API calls. Progress is evaluated in real time with every event you send.
Send a metric event to track user activity and power achievements.
Path Parameters
keystringrequiredUnique reference of the metric as set when created.
Request Body
userUserrequiredThe user that triggered the event (must include id).
valuenumberrequiredThe value to add to the user's current total for the given metric.
Response
eventIdstringUnique identifier for the created event.
totalnumberThe user's new total for this metric.
achievementsAchievement[]New achievements unlocked by this event.
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
// - Evaluates achievement triggers
// - Returns new unlocked achievements
Get a user's achievements. By default returns only completed achievements.
Path Parameters
idstringrequiredID of the user.
Query Parameters
includeIncompletestringSet to "true" to include incomplete achievements.
Response
keystringUnique key of the achievement.
namestringDisplay name of the achievement.
achievedAtISO 8601When the achievement was completed (null if incomplete).
badgeUrlstringURL of the achievement badge image.
raritynumberPercentage of users who have completed this achievement.
Example
import { TrophyApiClient } from '@trophyso/node';
const trophy = new TrophyApiClient({
apiKey: 'YOUR_API_KEY'
});
// Fetch all achievements for a user
const achievements = await trophy.users
.achievements("user-123");
// Response:
// [
// {
// key: "completed-onboarding",
// name: "Completed Onboarding",
// trigger: "api",
// achievedAt: "2021-01-01T00:00:00Z",
// badgeUrl: "https://...",
// rarity: 50
// }
// ]Mark an achievement as completed for a user. Use for API-triggered achievements.
Path Parameters
keystringrequiredUnique reference of the achievement as set when created.
Request Body
userUserrequiredThe user that completed the achievement (must include id).
Response
completionIdstringUnique identifier for the completion.
achievementAchievementThe completed achievement with badge URL and metadata.
pointsobjectPoints awarded for this completion, keyed by points system.
Example
import { TrophyApiClient } from '@trophyso/node';
const trophy = new TrophyApiClient({
apiKey: 'YOUR_API_KEY'
});
// Complete an achievement for a user
await trophy.achievements.complete(
"finish-onboarding",
{
user: { id: "user-123" }
}
);
// Returns completionId, achievement
// object, and any points awardedLightning-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 achievements
const achievements = await trophy.users
.achievements("user-123");
// Display badges
for (const a of achievements) {
console.log(a.name, a.badgeUrl);
}
Gamification UI Library
Pixel-perfect achievements 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.
- 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 achievements API?
A badge award API looks simple on the surface — store a completion flag, return a URL. The trigger evaluation, deduplication, and progress tracking underneath are where the complexity compounds.
| Key Considerations | Build | Why does it matter? | |
|---|---|---|---|
| Integration Time | Configure achievements in the dashboard, integrate with one API call. Live in under an hour. | Design trigger evaluation engine, badge hosting mechanism, progress tracking, and rarity calculations. Expect 3-4 weeks for initial setup, with ongoing maintenance required for new achievements and updates. | Achievement systems look simple on the surface but require complex trigger logic for progression thresholds, streak milestonesand compound conditions that grows with every new achievement added. |
| Reliability | Exactly-once achievement completion with built-in deduplication. | You must guarantee achievements are awarded exactly once — not zero times, not twice — even under concurrent events and race conditions. | Double-awarding an achievement erodes user trust and creates support tickets. Missing one frustrates users who earned it and creates a bad experience. Both are hard to debug retroactively. |
| Scalability | Trophy evaluates achievement triggers millions of times a day in real time without performance degradation. | As you add more achievements and users, trigger evaluation becomes a combinatorial problem. Naive implementations degrade quickly and become hard to change at scale. | Every metric event needs to be checked against every relevant achievement which requires careful indexing and query optimization at scale. |
| Ongoing Maintenance | Add and update achievements from the dashboard. No code changes or deployments needed. Non-technical users can do this themselves. | Each new achievement requires code changes for trigger logic, database migrations for new thresholds, and testing across edge cases. Each update requires a deploy, creating a bottleneck between product and engineering. | Product teams want to iterate on achievements frequently. If every change requires a deploy, you create a bottleneck between product and engineering. |
| Feature Development | Badge hosting, rarity calculations, progress tracking, and new trigger types ship regularly. | Features like rarity percentages, progress bars, and compound triggers each require significant development and ongoing maintenance. | Users expect polished achievement experiences — progress indicators, rarity badges, shareable completions. Building each of these in-house adds up. |
Integration Time
Configure achievements in the dashboard, integrate with one API call. Live in under an hour.
Build
Design trigger evaluation engine, badge hosting mechanism, progress tracking, and rarity calculations. Expect 3-4 weeks for initial setup, with ongoing maintenance required for new achievements and updates.
Why does it matter?
Achievement systems look simple on the surface but require complex trigger logic for progression thresholds, streak milestonesand compound conditions that grows with every new achievement added.
Reliability
Exactly-once achievement completion with built-in deduplication.
Build
You must guarantee achievements are awarded exactly once — not zero times, not twice — even under concurrent events and race conditions.
Why does it matter?
Double-awarding an achievement erodes user trust and creates support tickets. Missing one frustrates users who earned it and creates a bad experience. Both are hard to debug retroactively.
Scalability
Trophy evaluates achievement triggers millions of times a day in real time without performance degradation.
Build
As you add more achievements and users, trigger evaluation becomes a combinatorial problem. Naive implementations degrade quickly and become hard to change at scale.
Why does it matter?
Every metric event needs to be checked against every relevant achievement which requires careful indexing and query optimization at scale.
Ongoing Maintenance
Add and update achievements from the dashboard. No code changes or deployments needed. Non-technical users can do this themselves.
Build
Each new achievement requires code changes for trigger logic, database migrations for new thresholds, and testing across edge cases. Each update requires a deploy, creating a bottleneck between product and engineering.
Why does it matter?
Product teams want to iterate on achievements frequently. If every change requires a deploy, you create a bottleneck between product and engineering.
Feature Development
Badge hosting, rarity calculations, progress tracking, and new trigger types ship regularly.
Build
Features like rarity percentages, progress bars, and compound triggers each require significant development and ongoing maintenance.
Why does it matter?
Users expect polished achievement experiences — progress indicators, rarity badges, shareable completions. Building each of these in-house adds up.
FAQ
Frequently asked questions
Have a different question and can’t find the answer you’re looking for?
- What is the difference between achievements and badges?
- In Trophy, the achievements API and badges API are two sides of the same concept. An achievement is a milestone a user can reach; each achievement has a badge — an image that represents the accomplishment. You configure both the trigger conditions and badge for each achievement in the dashboard.
- How do I trigger achievements automatically?
- Trophy's gamification achievements API evaluates three trigger types: metric thresholds (e.g., "wrote 10,000 words"), streak milestones (e.g., "7-day streak"), and direct API calls (e.g., "profile completed") for custom logic. Triggers are evaluated automatically whenever you send a metric event — no polling or scheduled jobs needed.
- How do I award badges programmatically with custom images?
- Upload any badge image when creating an achievement in the Trophy dashboard. Trophy hosts image files and returns the badge URL in every API response, so you can award badges programmatically and render them in your app without managing your own asset storage. Alternatively if you already have asset storage, you can pass a custom badge URL to Trophy directly.
- How do I show achievement progress to users?
- Use the get achievements endpoint to fetch both completed and in-progress achievements. The response includes progress data so you can render progress bars, completion percentages and rarity statistics.
- Can I use achievements for onboarding milestones?
- Yes, Trophy's achievements API is well-suited to onboarding sequences — "completed profile", "first project created", "invited a teammate" — triggered via the API when users complete each step. Across Trophy's platform, users who complete an achievement on their first day retain at 33.42% at day 30, compared to 20.36% for users who don't. so designing the first session so an achievement fires before the user leaves is one of the highest-leverage retention decisions you can make.
- Can I display badges in React, React Native, or mobile apps?
- Yes. Adding achievements to any app with Trophy uses server-side SDKs (Node.js, Python, Go, Java, PHP, Ruby, and .NET) to handle trigger evaluation and completion logic on your backend. The API returns badge image URLs and completion data 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.
