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

# Badges & Achievements

> Create automatic badges that reward students for reaching milestones

## Overview

Badges are automatic achievements that reward students for reaching milestones. The system checks every student against your active badges **once per hour**, and any newly-eligible students are awarded automatically.

<img src="https://mintcdn.com/joshuamakes/G5j-M0tSaQs4mL9T/images/advanced/badges-settings.png?fit=max&auto=format&n=G5j-M0tSaQs4mL9T&q=85&s=7037527f28784986cdfa41f37f3424fa" alt="Classroom settings badges section with badge definitions and configuration" width="1600" height="1000" data-path="images/advanced/badges-settings.png" />

<Info>
  Automatic badge processing runs hourly. After a student crosses a threshold, they typically receive the badge within an hour — you don't need to wait until the next day.
</Info>

## Badge Types

<Tabs>
  <Tab title="Achievement Badges">
    Reward specific accomplishments. Pick a **trigger type** and a **target value**:

    * **Points Earned** — lifetime currency earned
    * **Currency Spent** — lifetime currency spent
    * **Transaction Count** — number of transactions
    * **Purchase Count** — number of rewards redeemed
    * **Jobs Held** — number of distinct jobs held
    * **Badges Earned** — number of badges already collected
    * **Auction Wins** — number of auctions won
    * **Bills Paid** — number of bill payments made
    * **Job Days** — days completed in a job
  </Tab>

  <Tab title="Milestone Badges">
    Celebrate reaching a threshold. Pick a **milestone type** and a **milestone amount**:

    * **Points Milestone** — current balance reaches the amount
    * **Savings Milestone** — savings balance reaches the amount
    * **Weekly Earnings** — earned the amount in a single week
    * **Monthly Earnings** — earned the amount in a single month
  </Tab>

  <Tab title="Special Badges">
    Manually awarded by you — no automatic criteria. Use these for things the system can't detect:

    * Exceptional test scores
    * Special project completion
    * Above-and-beyond behavior
    * Teacher's choice recognition
    * Student of the month
  </Tab>
</Tabs>

## Creating a Badge

<Steps>
  <Step title="Navigate to Badge Settings">
    Go to **Settings** → **Classroom Settings** → **Badges**
  </Step>

  <Step title="Click Create New Badge">
    The badge wizard opens. You can also click **Load Defaults** to populate your classroom with a starter set of badges based on your currency.
  </Step>

  <Step title="Configure Badge Details">
    * **Name**: Clear, motivating name (e.g., "Money Master", "Savings Star")
    * **Description**: What the student accomplished
    * **Icon**: Pick an icon from the categorized icon picker (trophies, animals, food, etc.)
    * **Color**: Choose a color for the badge background
    * **Badge Type**: Achievement, Milestone, or Special
    * **Bonus Reward**: Optional bonus currency awarded when the badge is earned
  </Step>

  <Step title="Set Criteria">
    For **Achievement** badges, pick a trigger type and target value (e.g., `role_days = 5`).

    For **Milestone** badges, pick a milestone type and milestone amount (e.g., `points_milestone = 500`).

    **Special** badges have no criteria — they're manual-only.
  </Step>

  <Step title="Save and Activate">
    The badge starts checking eligibility on the next hourly processing cycle. Students who already meet the criteria will be awarded within the next hour.
  </Step>
</Steps>

## Critical: Understanding Currency Amounts

<Warning>
  **Important for Dollar-Based Currencies**: When setting badge criteria for currency amounts, enter the amount **as you see it displayed** in the app!
</Warning>

<Tabs>
  <Tab title="✅ Using Currency (Dollars)">
    If your classroom uses **dollars with decimals**:

    * To award badge at **\$200**: Enter `200.00`
    * To award badge at **\$50**: Enter `50.00`
    * To award badge at **\$1000**: Enter `1000.00`

    The system automatically converts to cents internally, but you should enter the dollar amount students see.

    <Check>Matches displayed balances like "\$200.00"</Check>
  </Tab>

  <Tab title="✅ Using Points">
    If your classroom uses **whole number points**:

    * To award badge at **5000 points**: Enter `5000`
    * To award badge at **1000 points**: Enter `1000`
    * To award badge at **100 points**: Enter `100`

    No conversion needed - enter exactly what students see.

    <Check>Matches displayed balances like "5000 points"</Check>
  </Tab>

  <Tab title="⚠️ Common Mistake">
    **Problem**: Badge awards to everyone immediately

    **Cause**: Entered cents instead of dollars

    **Example**: You wanted \$200 badge but entered `200` in a dollar-based classroom

    * System interpreted as \$2.00 (200 cents)
    * Everyone with \$2+ qualified immediately

    **Fix**: Edit badge and change to `200.00`

    <Warning>
      If badges are awarding too easily, check that your amounts match your currency format!
    </Warning>
  </Tab>
</Tabs>

## How Automatic Awards Work

<Steps>
  <Step title="Hourly Check">
    Every hour, the system checks all active badges against all students in classrooms with badges enabled.
  </Step>

  <Step title="Criteria Evaluation">
    For each student, the system checks if they meet the badge requirements.
  </Step>

  <Step title="Duplicate Prevention">
    Students who already have the badge are skipped — no duplicates are awarded.
  </Step>

  <Step title="Award Badges">
    Eligible students receive the badge and any bonus currency.
  </Step>

  <Step title="Notification">
    Students see new badges on their dashboard immediately. You also receive a notification summarizing how many badges were auto-awarded.
  </Step>
</Steps>

## Manual Badge Awards

Award any badge to any student at any time — useful for **Special** badges or to recognize an achievement before the next hourly check.

<Steps>
  <Step title="Open Badge Settings">
    Navigate to **Settings** → **Classroom Settings** → **Badges**
  </Step>

  <Step title="Find the Badge">
    Click the **Award** button on the badge card.
  </Step>

  <Step title="Select Students">
    Pick a classroom and one or more students to receive the badge.
  </Step>

  <Step title="Confirm Award">
    The badge and any bonus currency are immediately granted, with a transaction logged in each student's history.
  </Step>
</Steps>

<Tip>
  Manual awards are perfect for special achievements that don't fit automatic criteria - exceptional test scores, unique contributions, or going above and beyond!
</Tip>

## Badge Management

### Editing Badges

* Change criteria thresholds as your economy evolves
* Update descriptions or imagery
* Adjust bonus point amounts
* Enable/disable without deleting

### Revoking Badges

<Warning>
  Badge revocation should be rare, but is available for:

  * Incorrectly awarded badges (system error)
  * Student behavior warranting removal
  * Duplicate awards that shouldn't exist
</Warning>

To revoke: Student profile → Badges tab → Click badge → **Revoke**

## Best Practices

<AccordionGroup>
  <Accordion title="Start with 3-5 Badges" icon="flag-checkered">
    Don't overwhelm students with too many badges initially. Start simple:

    * One low-tier badge (easy to earn)
    * One medium-tier badge (1-2 weeks effort)
    * One high-tier badge (long-term goal)

    Add more as students understand the system.
  </Accordion>

  <Accordion title="Create Progressive Tiers" icon="stairs">
    Multiple levels for the same achievement type:

    * "Saver Bronze" - Save \$100
    * "Saver Silver" - Save \$250
    * "Saver Gold" - Save \$500

    Students love working toward the next tier!
  </Accordion>

  <Accordion title="Test Your Amounts" icon="flask">
    Before activating:

    * Check sample student balances
    * Verify your amount matches expected format
    * Start with higher thresholds if unsure
    * Adjust down if no one earns it
  </Accordion>

  <Accordion title="Celebrate Badge Awards" icon="party-popper">
    * Announce new badge recipients to class
    * Display badges on classroom board
    * Let students share their achievements
    * Creates social motivation to earn more
  </Accordion>

  <Accordion title="Include Bonus Points" icon="coins">
    Add 10-50 bonus points to badges for extra motivation:

    * Makes earning the badge feel extra rewarding
    * Provides currency boost for savings goals
    * Creates anticipation for badge processing
  </Accordion>
</AccordionGroup>

## Default Badge Templates

When creating a new badge, you can load from templates:

<CardGroup cols={2}>
  <Card title="First Earner" icon="seedling">
    First transaction - awarded immediately to get students excited
  </Card>

  <Card title="Saver Tier 1" icon="piggy-bank">
    Save \$100 - teaches delayed gratification
  </Card>

  <Card title="Big Spender" icon="cart-shopping">
    Redeem 5 rewards - encourages using the economy
  </Card>

  <Card title="Job Well Done" icon="briefcase">
    Complete job for 7 consecutive days - rewards responsibility
  </Card>

  <Card title="Century Club" icon="100">
    Earn \$100 in total (lifetime) - achievable medium-term goal
  </Card>

  <Card title="Millionaire" icon="gem">
    Earn \$1000 in total - prestigious long-term achievement
  </Card>
</CardGroup>

<Tip>
  Templates are fully customizable - use them as starting points and adjust thresholds for your classroom economy!
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Badge Awarding to Everyone" icon="triangle-exclamation">
    **Problem**: Badge awarded to entire class immediately

    **Cause**: Threshold too low or currency format mismatch

    **Solution**:

    1. Check student balances to see typical amounts
    2. Edit badge criteria to much higher amount
    3. Test with "dry run" if available
    4. Consider revoking incorrect awards and re-issuing
  </Accordion>

  <Accordion title="Badge Not Awarding Anyone" icon="hourglass">
    **Problem**: No students receiving the badge after several days

    **Cause**: Threshold too high or criteria unclear

    **Solution**:

    1. Review highest student balances/achievements
    2. Lower threshold to achievable level
    3. Ensure badge is enabled and active
    4. Check that badge criteria type matches your goal
  </Accordion>

  <Accordion title="Duplicate Badges" icon="clone">
    **Problem**: Student received the same badge multiple times

    **Cause**: System error (very rare)

    **Solution**:

    1. Report to support - may indicate a database issue
    2. Manually revoke duplicate awards
    3. System has built-in duplicate prevention, so this shouldn't happen
  </Accordion>
</AccordionGroup>

## Badge Analytics

Track badge effectiveness:

* **Award Rate**: How often badges are earned
* **Time to Earn**: Average days from classroom start to badge
* **Engagement Impact**: Do badges increase earning behavior?
* **Popular Badges**: Which are most coveted by students

## Related Topics

<CardGroup cols={2}>
  <Card title="Classroom Jobs" icon="briefcase" href="/advanced/jobs">
    Combine jobs with badges for achievement tracking
  </Card>

  <Card title="Analytics" icon="chart-line" href="/advanced/analytics">
    View badge earning patterns and trends
  </Card>
</CardGroup>