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 Equivalency Engine converts raw numbers like “12.4 kg CO2e” into relatable, everyday comparisons that resonate with consumers. Think of it as Uber-style communication for sustainability data.

​
How it works

Every calculation result can include an equivalency field that automatically translates the score into one or more human-friendly comparisons. 
query {
  product(id: "prod_abc123") {
    impactScore {
      co2Equivalent
      equivalencies {
        category
        description
        value
        icon
        locale
      }
    }
  }
}
Response: 
{
  "data": {
    "product": {
      "impactScore": {
        "co2Equivalent": 12.4,
        "equivalencies": [
          {
            "category": "TRANSPORT",
            "description": "Driving a car",
            "value": "48 km",
            "icon": "car",
            "locale": "en"
          },
          {
            "category": "HOUSEHOLD",
            "description": "Washing machine cycles",
            "value": "10 washes",
            "icon": "washing-machine",
            "locale": "en"
          },
          {
            "category": "NATURE",
            "description": "Tree absorption time",
            "value": "1.2 years",
            "icon": "tree",
            "locale": "en"
          }
        ]
      }
    }
  }
}

​
Equivalency categories

CategoryExamples
TRANSPORTCar kilometers, flight hours, train rides
HOUSEHOLDWashing cycles, smartphone charges, showers
NATURETrees planted, park area, ocean CO2 absorption
FOODBeef meals, cups of coffee, bread loaves
ENERGYLightbulb hours, home heating days
TIMEAverage person’s daily footprint days

​
Localization

Equivalencies support multiple locales. Pass the locale parameter to receive culturally relevant comparisons: 
mutation {
  calculateImpact(input: {
    productId: "prod_abc123"
    quantity: 1
    locale: "nl"
  }) {
    equivalencies {
      description
      value
      locale
    }
  }
}
Dutch response: "10 wasbeurten" instead of "10 washes".

​
Savings equivalencies

When comparing products or running scenarios, the engine also generates savings equivalencies: 
{
  "savingsEquivalency": {
    "description": "By choosing this product, you save the equivalent of",
    "value": "3 days of home heating",
    "icon": "house",
    "comparedTo": "Standard alternative"
  }
}

​
Personalization

For logged-in customers, the engine can generate personalized messages: 
{
  "personalEquivalency": {
    "description": "Your most eco-friendly purchase this month",
    "cumulativeImpact": "You've saved 48 kg CO2e this year",
    "ranking": "Top 15% of buyers"
  }
}

​
Use cases

  • Product detail pages: Show relatable impact alongside the price
  • Shopping cart: Display cumulative cart impact in everyday terms
  • Order confirmation: Reinforce the customer’s positive choice
  • Marketing: Generate shareable impact statements