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

# Gamification

> Engage customers with impact badges, milestones, and sustainability achievements.

The Gamification module provides hooks to drive customer engagement by rewarding sustainable behavior with badges, milestones, and progress tracking.

## Customer impact profile

```graphql theme={null}
query {
  customerImpactProfile(customerId: "cust_123") {
    totalCo2Saved
    totalOrders
    badges {
      id
      name
      description
      icon
      earnedAt
      tier
    }
    milestones {
      id
      name
      target
      current
      percentage
      isCompleted
    }
    ranking {
      position
      percentile
      description
    }
  }
}
```

**Response:**

```json theme={null}
{
  "data": {
    "customerImpactProfile": {
      "totalCo2Saved": 248.5,
      "totalOrders": 15,
      "badges": [
        {
          "id": "badge_first_green",
          "name": "First Green Purchase",
          "description": "Made your first eco-friendly purchase",
          "icon": "seedling",
          "earnedAt": "2025-03-15T10:30:00Z",
          "tier": "BRONZE"
        },
        {
          "id": "badge_tree_saver",
          "name": "Tree Saver",
          "description": "Saved the equivalent of 10 trees",
          "icon": "tree",
          "earnedAt": "2025-06-22T14:15:00Z",
          "tier": "SILVER"
        }
      ],
      "milestones": [
        {
          "id": "milestone_500kg",
          "name": "500 kg CO2 Saved",
          "target": 500,
          "current": 248.5,
          "percentage": 49.7,
          "isCompleted": false
        }
      ],
      "ranking": {
        "position": 142,
        "percentile": 15,
        "description": "Top 15% of sustainable shoppers"
      }
    }
  }
}
```

## Badge types

| Badge                    | Trigger                                   | Tiers                |
| ------------------------ | ----------------------------------------- | -------------------- |
| **First Green Purchase** | First order with below-average CO2        | Bronze               |
| **Tree Saver**           | Saved equivalent of 10/50/100 trees       | Bronze, Silver, Gold |
| **Chain Champion**       | Ordered from 5 verified supply chains     | Silver               |
| **Circular Hero**        | 10 orders with >50% recycled content      | Gold                 |
| **Carbon Neutral**       | Offset all order emissions in a month     | Platinum             |
| **Streak Keeper**        | 3/6/12 consecutive months of green orders | Bronze, Silver, Gold |

## Milestone tracking

Milestones represent long-term goals that customers progress toward over time:

```graphql theme={null}
query {
  customerMilestones(customerId: "cust_123") {
    active {
      name
      current
      target
      unit
      percentage
    }
    completed {
      name
      completedAt
    }
  }
}
```

## Leaderboard

```graphql theme={null}
query {
  impactLeaderboard(
    period: MONTHLY
    limit: 10
  ) {
    entries {
      rank
      customerId
      displayName
      co2Saved
      badgeCount
    }
    currentUserPosition {
      rank
      percentile
    }
  }
}
```

## Use cases

* **Customer accounts**: Display impact profile with badges and progress bars
* **Post-purchase**: Show newly earned badges on order confirmation
* **Email campaigns**: Include milestone progress in marketing emails
* **Social sharing**: Generate shareable impact cards for social media