Achievements API

Add achievements to your app in minutes

Build engaging achievement systems with a flexible API. Create milestone badges, track progress automatically, and award achievements tied to any user behavior.

Get API KeyAPI Reference
SDKs for
NodeJSGoJava.NETPHPPythonRuby

Endpoints

Achievement endpoints

Track user progress and award achievements automatically based on their metrics, streak, or other triggers.

GET/users/{id}/achievementsView Docs

Get a user's achievements. By default returns only completed achievements.

Path Parameters

idstringrequired

ID of the user.

Query Parameters

includeIncompletestring

Set to "true" to include incomplete achievements.

Response

keystring

Unique key of the achievement.

namestring

Display name of the achievement.

achievedAtISO 8601

When the achievement was completed (null if incomplete).

badgeUrlstring

URL of the achievement badge image.

raritynumber

Percentage 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 
//   }
// ]
POST/achievements/{key}/completeView Docs

Mark an achievement as completed for a user. Use for API-triggered achievements.

Path Parameters

keystringrequired

Unique reference of the achievement as set when created.

Request Body

userUserrequired

The user that completed the achievement (must include id).

Response

completionIdstring

Unique identifier for the completion.

achievementAchievement

The completed achievement with badge URL and metadata.

pointsobject

Points 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 awarded

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.

NodeJS
Go
Java
.NET
PHP
Python
Ruby
Get StartedAPI 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 achievements

const achievements = await trophy.users
  .achievements("user-123");

// Display badges
for (const a of achievements) {
  console.log(a.name, a.badgeUrl);
}

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 achievements?

Building a robust achievement and badge system involves more than storing completion flags.

Integration Time

Configure achievements in the dashboard, integrate with one API call. Live in hours.
Build
Design trigger evaluation engine, badge storage, progress tracking, and rarity calculations. Expect 3-6 weeks.
Why does it matter?
Achievement systems look simple on the surface but require complex trigger logic — metric thresholds, streak milestones, compound conditions — that grows with every new achievement type.

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. Missing one frustrates users who earned it. Both are hard to debug retroactively.

Scalability

Trophy evaluates triggers in real time across millions of users without performance degradation.
Build
As you add more achievements and users, trigger evaluation becomes a combinatorial problem. Naive implementations degrade quickly.
Why does it matter?
Every metric event needs to be checked against every relevant achievement. At scale, this requires careful indexing and query optimization.

Ongoing Maintenance

Add and update achievements from the dashboard. No code changes or deployments needed.
Build
Each new achievement requires code changes for trigger logic, database migrations for new thresholds, and testing across edge cases.
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

Achievements & Badges FAQ

Have a different question and can’t find the answer you’re looking for? Send us an email.

What is the difference between achievements and badges?
In Trophy, achievements and badges are the same concept. An achievement is a milestone a user can reach, and each achievement has a badge — an image that represents the accomplishment. You configure both the trigger conditions and badge artwork in the dashboard.
How do I trigger achievements automatically?
Achievements can be triggered by metric thresholds (e.g., "wrote 10,000 words"), streak milestones (e.g., "7-day streak"), or via a direct API call for custom logic. Trophy evaluates triggers automatically whenever you send a metric event.
Can I create custom badge images and rewards?
Yes. Upload any badge image when creating an achievement in the dashboard. Trophy hosts the images and returns the badge URL in the API response so you can display them in your app.
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 and completion percentages.
Can I use achievements for onboarding milestones?
Yes. A common pattern is creating achievements tied to onboarding steps — "completed profile", "first project created", etc. You can trigger these via the API when users complete each step, or automatically via metric thresholds.
Can I display badges in React, React Native, or mobile apps?
Yes. Trophy's server-side SDKs (Node.js, Python, Go, Java, PHP, Ruby, .NET) handle achievement 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.

Get StartedRead Docs
Trophy