Achievements API

The Achievements API allows you to create, manage, and track achievements for your games. Add gamification elements to increase user engagement and retention.

Authentication

Most endpoints require authentication using either:

• API Key: Include x-api-key header
• Cognito JWT: Include Authorization: Bearer <token> header
• Developer Auth: Special authentication for developer operations

Some endpoints like getAchievementById are public and don't require authentication.

Base URL

https://sdk.getjar.com/achievements

---

Create Achievement

Create a new achievement for your app.

Endpoint

POST /achievements

Request Body

{
  developerId: string;              // Required: Developer ID
  appId: string;                    // Required: App ID
  achievementReference?: string;    // Unique reference code (e.g., "FIRST_WIN")
  name: string;                     // Required: Achievement name
  description: string;              // Required: Short description
  detailedDescription?: string;     // Longer description
  category?: string;                // Category (e.g., "Combat", "Exploration")
  tags?: string[];                  // Tags for filtering
  type: string;                     // STANDARD, PROGRESSION, SECRET, SOCIAL
  rarity: string;                   // COMMON, UNCOMMON, RARE, EPIC, LEGENDARY
  points: number;                   // Points awarded
  xpReward?: number;                // XP reward
  currencyReward?: number;          // Currency reward
  requirements?: {                  // Unlock requirements
    type: string;                   // COUNT, THRESHOLD, COLLECTION, etc.
    target: number;
    conditions?: object;
  };
  isActive?: boolean;               // Default: true
  isHidden?: boolean;               // Default: false
}

Response

{
  achievementId: string;
  achievementReference: string;
  appId: string;
  name: string;
  description: string;
  type: string;
  rarity: string;
  points: number;
  xpReward: number;
  currencyReward: number;
  isActive: boolean;
  isHidden: boolean;
  createdAt: string;
  updatedAt: string;
}

Example

import { AchievementsApi } from "@getjar-iap/sdk";

const achievementsApi = new AchievementsApi(configuration);

const achievement = await achievementsApi.createAchievement({
  createAchievementDto: {
    developerId: "dev_123",
    appId: "app_123",
    achievementReference: "FIRST_WIN",
    name: "First Victory",
    description: "Win your first match",
    detailedDescription: "Complete your first PvP match with a victory",
    category: "Combat",
    tags: ["pvp", "beginner"],
    type: "STANDARD",
    rarity: "COMMON",
    points: 10,
    xpReward: 100,
    currencyReward: 50,
    requirements: {
      type: "COUNT",
      target: 1,
      conditions: { wins: 1 },
    },
    isActive: true,
    isHidden: false,
  },
});

console.log("Achievement ID:", achievement.data.achievementId);

Response Codes

Code	Description
201	Achievement created successfully
400	Invalid achievement data
401	Unauthorized
403	Forbidden

---

Bulk Create Achievements

Create multiple achievements in a single request.

Endpoint

POST /achievements/bulk

Request Body

{
  achievements: Array<{
    achievementReference: string;
    appId: string;
    name: string;
    description: string;
    type: string;
    rarity: string;
    points: number;
    // ... other achievement properties
  }>;
}

Response

{
  created: number;
  achievements: Array<Achievement>;
}

Example

const bulkResult = await achievementsApi.bulkCreateAchievements({
  body: {
    achievements: [
      {
        achievementReference: "LEVEL_10",
        appId: "app_123",
        name: "Reach Level 10",
        description: "Achieve level 10 in the game",
        type: "PROGRESSION",
        rarity: "COMMON",
        points: 25,
      },
      {
        achievementReference: "FIRST_WIN",
        appId: "app_123",
        name: "First Victory",
        description: "Win your first match",
        type: "STANDARD",
        rarity: "COMMON",
        points: 10,
      },
    ],
  },
});

console.log(`Created ${bulkResult.data.created} achievements`);

---

Update Achievement

Update an existing achievement's properties.

Endpoint

PUT /achievements/:appId/:achievementId

Parameters

Parameter	Type	Description
appId	string	The unique application identifier
achievementId	string	The achievement ID or reference

Request Body

{
  name?: string;
  description?: string;
  detailedDescription?: string;
  category?: string;
  tags?: string[];
  points?: number;
  xpReward?: number;
  currencyReward?: number;
  requirements?: object;
  isActive?: boolean;
  isHidden?: boolean;
}

Example

const updated = await achievementsApi.updateAchievement({
  appId: "app_123",
  achievementId: "FIRST_WIN",
  updateAchievementDto: {
    name: "First Victory - Updated",
    description: "Win your first match in any game mode",
    points: 15,
    xpReward: 150,
  },
});

Response Codes

Code	Description
200	Achievement updated successfully
400	Invalid update data
401	Unauthorized
404	Achievement not found

---

Update Achievement Statistics

Manually update achievement unlock statistics.

Endpoint

PUT /achievements/:appId/:achievementId/stats

Request Body

{
  totalUnlocks?: number;    // Total times unlocked
  uniqueUnlocks?: number;   // Unique users who unlocked
  unlockRate?: number;      // Percentage (0-100)
}

Example

const stats = await achievementsApi.updateAchievementStats({
  appId: "app_123",
  achievementId: "FIRST_WIN",
  updateAchievementStatsDto: {
    totalUnlocks: 1500,
    uniqueUnlocks: 1200,
    unlockRate: 45.5,
  },
});

---

Delete Achievement

Permanently delete an achievement.

Endpoint

DELETE /achievements/:appId/:achievementId

Parameters

Parameter	Type	Description
appId	string	The unique application identifier
achievementId	string	The achievement ID or reference

Example

await achievementsApi.deleteAchievement({
  appId: "app_123",
  achievementId: "OLD_ACHIEVEMENT",
});

console.log("Achievement deleted successfully");

Response Codes

Code	Description
200	Achievement deleted successfully
401	Unauthorized
404	Achievement not found

---

Get App Achievements

Retrieve all achievements for a specific app with pagination and filters.

Endpoint

GET /achievements/app/:appId

Parameters

Parameter	Type	Required	Description
appId	string	Yes	The application identifier
page	number	No	Page number (default: 1)
limit	number	No	Items per page (default: 20)
type	string	No	Filter by type
rarity	string	No	Filter by rarity
isActive	boolean	No	Filter by active status

Response

{
  items: Array<{
    achievementId: string;
    achievementReference: string;
    name: string;
    description: string;
    type: string;
    rarity: string;
    points: number;
    isActive: boolean;
    stats: {
      totalUnlocks: number;
      unlockRate: number;
    };
  }>;
  pagination: {
    total: number;
    page: number;
    limit: number;
    totalPages: number;
    hasNextPage: boolean;
    hasPreviousPage: boolean;
  }
}

Example

const achievements = await achievementsApi.getAppAchievements({
  appId: "app_123",
  page: 1,
  limit: 20,
  type: "STANDARD",
  rarity: "RARE",
  isActive: true,
});

console.log(`Total achievements: ${achievements.data.pagination.total}`);
achievements.data.items.forEach((achievement) => {
  console.log(`${achievement.name} - ${achievement.points} points`);
});

---

Get Developer Achievements

Retrieve all achievements created by a developer across all their apps.

Endpoint

GET /achievements/developer/:developerId

Parameters

Parameter	Type	Required	Description
developerId	string	Yes	The developer identifier
page	number	No	Page number
limit	number	No	Items per page

Example

const developerAchievements = await achievementsApi.getDeveloperAchievements({
  developerId: "dev_123",
  page: 1,
  limit: 50,
});

console.log(`Total: ${developerAchievements.data.pagination.total}`);

---

Get Achievement Statistics

Get comprehensive statistics for all achievements in an app.

Endpoint

GET /achievements/app/:appId/stats

Response

{
  totalAchievements: number;
  activeAchievements: number;
  hiddenAchievements: number;
  retiredAchievements: number;
  totalPoints: number;
  byType: {
    STANDARD: number;
    PROGRESSION: number;
    SECRET: number;
    SOCIAL: number;
  }
  byRarity: {
    COMMON: number;
    UNCOMMON: number;
    RARE: number;
    EPIC: number;
    LEGENDARY: number;
  }
}

Example

const stats = await achievementsApi.getAppAchievementStats({
  appId: "app_123",
});

console.log("Total Achievements:", stats.data.totalAchievements);
console.log("Total Points:", stats.data.totalPoints);
console.log("By Type:", stats.data.byType);
console.log("By Rarity:", stats.data.byRarity);

---

Get Achievement by ID

Retrieve detailed information about a specific achievement. This endpoint is public.

Endpoint

GET /achievements/:appId/:achievementId

Parameters

Parameter	Type	Description
appId	string	The application identifier
achievementId	string	The achievement ID or reference

Response

{
  achievementId: string;
  achievementReference: string;
  appId: string;
  name: string;
  description: string;
  detailedDescription: string;
  category: string;
  tags: string[];
  type: string;
  rarity: string;
  points: number;
  xpReward: number;
  currencyReward: number;
  requirements: {
    type: string;
    target: number;
    conditions: object;
  };
  isActive: boolean;
  isHidden: boolean;
  isRetired: boolean;
  stats: {
    totalUnlocks: number;
    uniqueUnlocks: number;
    unlockRate: number;
    averageTimeToUnlock: number;
  };
  createdAt: string;
  updatedAt: string;
}

Example

const achievement = await achievementsApi.getAchievementById({
  appId: "app_123",
  achievementId: "FIRST_WIN",
});

console.log("Name:", achievement.data.name);
console.log("Description:", achievement.data.description);
console.log("Points:", achievement.data.points);
console.log("Unlock Rate:", achievement.data.stats?.unlockRate + "%");

---

Achievement Types

STANDARD

Basic achievements for completing specific tasks.

Examples:

• First Win
• Complete Tutorial
• Reach Level 10

PROGRESSION

Achievements tied to player progression.

Examples:

• Reach Level 50
• Complete 100 Missions
• Earn 1,000,000 Gold

SECRET

Hidden achievements that players discover.

Examples:

• Find Secret Area
• Easter Egg Hunter
• Hidden Boss Defeated

SOCIAL

Achievements involving social interactions.

Examples:

• Invite 5 Friends
• Join a Guild
• Share Your Score

---

Achievement Rarity

Rarity affects the perceived value and difficulty of achievements.

Rarity	Points Range	Description
COMMON	5-15	Easy to obtain, basic tasks
UNCOMMON	15-30	Moderate difficulty
RARE	30-60	Challenging accomplishments
EPIC	60-100	Very difficult, skill-based
LEGENDARY	100+	Extremely rare, prestigious

---

Complete Example

Here's a complete workflow for setting up achievements:

import { Configuration, AchievementsApi } from "@getjar-iap/sdk";

const configuration = new Configuration({
  basePath: "https://sdk.getjar.com",
  apiKey: "your-api-key",
});

const achievementsApi = new AchievementsApi(configuration);

async function setupAchievements() {
  const appId = "app_123";
  const developerId = "dev_123";

  // Create starter achievements
  const starterAchievements = [
    {
      achievementReference: "TUTORIAL_COMPLETE",
      appId,
      developerId,
      name: "Tutorial Master",
      description: "Complete the tutorial",
      type: "STANDARD",
      rarity: "COMMON",
      points: 5,
      xpReward: 50,
    },
    {
      achievementReference: "FIRST_WIN",
      appId,
      developerId,
      name: "First Victory",
      description: "Win your first match",
      type: "STANDARD",
      rarity: "COMMON",
      points: 10,
      xpReward: 100,
      currencyReward: 50,
    },
    {
      achievementReference: "LEVEL_10",
      appId,
      developerId,
      name: "Rising Star",
      description: "Reach level 10",
      type: "PROGRESSION",
      rarity: "UNCOMMON",
      points: 25,
      xpReward: 250,
    },
    {
      achievementReference: "SPEED_RUNNER",
      appId,
      developerId,
      name: "Speed Demon",
      description: "Complete a level in under 60 seconds",
      type: "STANDARD",
      rarity: "RARE",
      points: 50,
      xpReward: 500,
      currencyReward: 200,
    },
    {
      achievementReference: "SECRET_AREA",
      appId,
      developerId,
      name: "Explorer",
      description: "Find the secret area",
      type: "SECRET",
      rarity: "EPIC",
      points: 75,
      xpReward: 1000,
      isHidden: true,
    },
  ];

  // Bulk create achievements
  const result = await achievementsApi.bulkCreateAchievements({
    body: { achievements: starterAchievements },
  });

  console.log(`Created ${result.data.created} achievements`);

  // Get all achievements for the app
  const achievements = await achievementsApi.getAppAchievements({
    appId,
    page: 1,
    limit: 100,
  });

  console.log("\nAchievements created:");
  achievements.data.items.forEach((achievement) => {
    console.log(
      `- ${achievement.name} (${achievement.rarity}): ${achievement.points} points`
    );
  });

  // Get achievement statistics
  const stats = await achievementsApi.getAppAchievementStats({ appId });

  console.log("\nAchievement Statistics:");
  console.log(`Total: ${stats.data.totalAchievements}`);
  console.log(`Total Points: ${stats.data.totalPoints}`);
  console.log("By Rarity:", stats.data.byRarity);

  return result;
}

// Run the setup
setupAchievements()
  .then(() => console.log("Setup complete!"))
  .catch((error) => console.error("Error:", error));

---

Best Practices

Design

1. Balance Difficulty: Mix easy, medium, and hard achievements
2. Clear Objectives: Write clear, concise descriptions
3. Fair Requirements: Make requirements achievable and fair
4. Progressive Rewards: Scale points/rewards with difficulty
5. Hidden Achievements: Use sparingly for discovery moments

Implementation

1. Use References: Always set meaningful achievementReference codes
2. Categorize: Organize achievements with categories and tags
3. Track Progress: Update stats regularly for analytics
4. Test Thoroughly: Verify unlock conditions work correctly
5. Localize: Support multiple languages for names/descriptions

Engagement

1. Early Wins: Include easy achievements for new players
2. Long-term Goals: Add challenging achievements for veterans
3. Variety: Create achievements for different play styles
4. Visibility: Balance between hidden and visible achievements
5. Feedback: Celebrate achievement unlocks in-game

Example: Achievement Progression

// Starter achievements (minutes to unlock)
{
  reference: 'TUTORIAL_COMPLETE',
  rarity: 'COMMON',
  points: 5
}

// Short-term goals (hours to unlock)
{
  reference: 'LEVEL_10',
  rarity: 'UNCOMMON',
  points: 25
}

// Medium-term goals (days to unlock)
{
  reference: 'LEVEL_50',
  rarity: 'RARE',
  points: 50
}

// Long-term goals (weeks to unlock)
{
  reference: 'MASTER_PLAYER',
  rarity: 'EPIC',
  points: 100
}

// Prestige achievements (months to unlock)
{
  reference: 'LEGENDARY_CHAMPION',
  rarity: 'LEGENDARY',
  points: 250
}

---

Error Handling

try {
  const achievement = await achievementsApi.createAchievement({
    createAchievementDto: {
      /* ... */
    },
  });
} catch (error) {
  if (error.response) {
    console.error("Status:", error.response.status);
    console.error("Message:", error.response.data.message);

    if (error.response.status === 400) {
      console.error("Validation errors:", error.response.data.errors);
    }
  }
}

---

Support

For additional help or questions:

• Documentation: https://docs.getjar.com
• API Reference: https://sdk.getjar.com/api/docs
• Support: support@getjar.com