Milestones API
The milestones API for consumer web and mobile apps
Add milestones to your consumer app in under an hour. Trophy handles trigger evaluation, badge hosting, progress tracking and rarity calculations so you can focus on the user experience. Scales to millions of users.
Quickstart
Quickstart: three-call integration
Configure your milestones in the Trophy dashboard first, then use this code to track user progress, check unlocks, and mark completions. The full lifecycle takes three calls.
import { TrophyApiClient } from "@trophyso/node";
const trophy = new TrophyApiClient({ apiKey: process.env.TROPHY_API_KEY });
// 1. Track a metric event (e.g., user completed a lesson)
const eventResponse = await trophy.metrics.event("lessons", {
user: { id: "user-123" },
value: 1,
});
console.log("Event ID:", eventResponse.eventId);
console.log("Lifetime total:", eventResponse.total);
// 2. Check if any achievements unlocked from this event
if (eventResponse.achievements.length > 0) {
for (const achievement of eventResponse.achievements) {
console.log("Unlocked:", achievement.name, "| Badge:", achievement.badgeUrl);
}
}
// 3. Fetch all achievements for a user (for profile display, history, etc.)
const userAchievements = await trophy.users.achievements("user-123");
for (const a of userAchievements) {
console.log(a.name, "| Achieved:", a.achievedAt, "| Rarity:", a.rarity);
}
// 4. Mark an event-triggered achievement complete (e.g., finished onboarding)
const completion = await trophy.achievements.complete("finish-onboarding", {
user: { id: "user-123" },
});
console.log("Completion ID:", completion.completionId);
console.log("Points awarded:", completion.points);Buy vs. build
Why use Trophy's milestones and achievements API?
A milestones 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.
Integration Time
Reliability
Scalability
Ongoing Maintenance
Feature Development
Reference
Objective types
Trophy milestones can trigger in three ways. Configure the objective type and threshold in the dashboard, then send the matching API call.
| Objective type | What triggers it | Example | How you send it |
|---|---|---|---|
| Metric-based | User's lifetime metric total crosses the threshold you set | Wrote 10,000 words | trophy.metrics.event() with the metric key and value |
| Streak-based | User hits a streak milestone | 7-day streak | trophy.metrics.event() on the streak metric (Trophy tracks consecutive days) |
| Event-based | Your code calls the complete endpoint directly | Completed onboarding | trophy.achievements.complete() with the milestone key |
Metric-based
Track incremental progress toward a threshold. Trophy sums events and unlocks the milestone when the total crosses the configured value.
await trophy.metrics.event("words-written", {
user: { id: "user-123" },
value: 500,
});Streak-based
Track daily activity on a streak metric. Trophy handles the consecutive-day logic and unlocks milestones at configured streak lengths (7 days, 30 days, etc.).
await trophy.metrics.event("daily-practice", {
user: { id: "user-123" },
value: 1,
});Event-based
Trigger a milestone directly when a user completes a one-time action.
await trophy.achievements.complete("finish-onboarding", {
user: { id: "user-123" },
});Endpoints
Milestone endpoints
Use Trophy's milestone tracking API to unlock milestones automatically from metric events, streak lengths, 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 milestones.
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 milestones unlocked by this event.
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 milestones. By default returns only completed milestones.
Path Parameters
idstringrequiredID of the user.
Query Parameters
includeIncompletestringSet to "true" to include incomplete milestones.
Response
keystringUnique key of the milestone.
namestringDisplay name of the milestone.
achievedAtISO 8601When the milestone was completed (null if incomplete).
badgeUrlstringURL of the milestone badge image.
raritynumberPercentage of users who have completed this milestone.
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 a milestone as completed for a user. Use for API-triggered milestones.
Path Parameters
keystringrequiredUnique reference of the milestone as set when created.
Request Body
userUserrequiredThe user that completed the milestone (must include id).
Response
completionIdstringUnique identifier for the completion.
achievementAchievementThe completed milestone with badge URL and metadata.
pointsobjectPoints awarded for this completion, keyed by points system.
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 awardedBuilt for production workloads
Reliable infrastructure designed for performance at scale.
- Uptime SLA
- 99.9%
- p95 API Latency
- 200ms
- Monthly API Requests
- 180M
- Users Tracked
- 1M+
What is the difference between milestones and badges?
In Trophy, badges are part of milestones, not a separate API. A milestone is a goal a user can reach; each milestone has a badge — an image that represents the accomplishment. You configure both the trigger conditions and badge for each milestone in the dashboard.
How do I trigger milestones automatically?
Trophy's milestones API evaluates three trigger types: metric thresholds (e.g., "wrote 10,000 words"), streak lengths (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 a milestone 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 milestone progress to users?
Use the get milestones endpoint to fetch both completed and in-progress milestones. The response includes progress data so you can render progress bars, completion percentages and rarity statistics.
Can I use milestones for onboarding?
Yes, Trophy's milestones 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 a milestone 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 a milestone 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 milestones 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.
Should I use Game Center or a milestones API?
Use Game Center if you're building an iOS or macOS game and want milestones shown in Apple's built-in UI. Use a milestones API like Trophy if your product runs on the web or across platforms, or isn't a game. Trophy keeps milestones in your own UI and out of a single app store.
How do milestones work for a non-game or SaaS app?
The same as any other user action. You send an event with one API call when a user does something worth rewarding, and Trophy tracks progress and unlocks the milestone. You then fetch the result to display it anywhere in your app, on web or mobile.
Can I use Trophy alongside Game Center or Google Play Games?
Yes. Some teams keep platform milestones in Game Center or Google Play Games for their native game builds. They use Trophy for the web and non-game surfaces those store APIs don't reach, and the two run independently.
Is the milestones API the same as an achievements API?
Yes. Milestones are Trophy's name for in-app achievements, and the API uses the achievements name throughout: endpoints like /achievements/{key}/complete and /users/{id}/achievements, the achievements array in metric event responses, and the achievement.completed webhook. If you're looking for an app achievements API, this is it.