> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudj.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Designing Achievements

> Criteria builder, reward distribution, tiered achievements, multi-language support

A good achievement turns noisy behaviour into a clear milestone members can see and aspire to. The builder has three parts: criteria (what triggers it), reward (what members get), and scope (who can earn it).

## Criteria

Pick the event type + threshold. Events fall into three groups:

### Built-in events

| Event                 | Fires when                      |
| --------------------- | ------------------------------- |
| `challenge_completed` | Member completes a challenge    |
| `reward_earned`       | Member earns any reward         |
| `check_in_completed`  | Daily check-in action           |
| `streak_milestone`    | Streak hits a configured length |
| `level_reached`       | Member hits an XP level         |
| `member_joined`       | Member joins the community      |

### Custom events

Use the **free-text custom event identifier** (#2144) to match events you fire via the Integration API. Example: `purchase_completed`, `livestream_attended`, `survey_submitted`.

### Thresholds

Stack conditions:

* `count >= N`
* `within Xd` (rolling window)
* Filter by tag, category, or other event attributes.

***

## Reward distribution

Attach rewards that distribute when the achievement unlocks:

* Points, XP (instant addition to balance)
* Badge (shown on profile)
* Asset reward (adds to wallet)
* Entry reward (adds entries to a pending giveaway)

Multiple rewards per achievement are supported — a single unlock can grant a badge plus 500 points plus 3 entries.

***

## Achievements as actions

The **Complete-Achievement action** (#729) inverts the relationship: a challenge requires members to have already unlocked an achievement before it can be started.

This gates progression — useful for multi-stage programs like tutorials or certification paths. See [Achievements as Actions](/admin-guide/achievements/achievements-as-actions).

***

## Tiered achievements

Design a series of escalating milestones:

```text theme={null}
Bronze -> Silver -> Gold -> Platinum
 5 done    20 done   50 done   100 done
```

Implementation:

1. Create four achievements, each with identical criteria shape but different thresholds.
2. Link Silver -> Bronze via a Complete-Achievement action in the next challenge (or on the achievement's own gating rules).
3. Members unlock them sequentially as they accumulate.

***

## Multi-language support

Achievements inherit your community's language config. Edit translations per locale; the achievement's title, description, and badge alt-text all translate. The language-switch bug in the achievement module was fixed in #845 — you can safely toggle between locales in the editor without losing your draft.

See [Language Management](/admin-guide/settings/language-management).

***

## Scope decisions

<CardGroup cols={2}>
  <Card title="Community-scoped" icon="users">
    Default. Only counts events inside that community. Good for community-specific milestones ("Top 5 contributors in the Paris region").
  </Card>

  <Card title="Org-scoped" icon="building">
    Counts events across every community in the org. Good for brand-wide milestones ("100 total check-ins across all our stores").
  </Card>
</CardGroup>

Scope is set at creation and **immutable** afterwards. Re-create the achievement if you need to change scope.

***

## Best practices

<Tip>
  Start with 3-5 achievements for a new community. More than that and members can't hold the full picture in their head.
</Tip>

<Tip>
  Pair each achievement with a **visible reward** (badge + points + something spendable). Achievements without visible rewards feel hollow.
</Tip>

<Warning>
  Achievements with thresholds that take months to hit (e.g. `count >= 1000`) look like broken progress bars. Use tiered achievements instead so every 10-20% of progress unlocks something.
</Warning>