Skip to main content

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.

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

​
Customer impact profile

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: 
{
  "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

BadgeTriggerTiers
First Green PurchaseFirst order with below-average CO2Bronze
Tree SaverSaved equivalent of 10/50/100 treesBronze, Silver, Gold
Chain ChampionOrdered from 5 verified supply chainsSilver
Circular Hero10 orders with >50% recycled contentGold
Carbon NeutralOffset all order emissions in a monthPlatinum
Streak Keeper3/6/12 consecutive months of green ordersBronze, Silver, Gold

​
Milestone tracking

Milestones represent long-term goals that customers progress toward over time: 
query {
  customerMilestones(customerId: "cust_123") {
    active {
      name
      current
      target
      unit
      percentage
    }
    completed {
      name
      completedAt
    }
  }
}

​
Leaderboard

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