> ## 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.

# Equivalency Engine

> Translate abstract sustainability metrics into human-understandable comparisons.

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.

```graphql theme={null}
query {
  product(id: "prod_abc123") {
    impactScore {
      co2Equivalent
      equivalencies {
        category
        description
        value
        icon
        locale
      }
    }
  }
}
```

**Response:**

```json theme={null}
{
  "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

| Category    | Examples                                       |
| ----------- | ---------------------------------------------- |
| `TRANSPORT` | Car kilometers, flight hours, train rides      |
| `HOUSEHOLD` | Washing cycles, smartphone charges, showers    |
| `NATURE`    | Trees planted, park area, ocean CO2 absorption |
| `FOOD`      | Beef meals, cups of coffee, bread loaves       |
| `ENERGY`    | Lightbulb hours, home heating days             |
| `TIME`      | Average person's daily footprint days          |

## Localization

Equivalencies support multiple locales. Pass the `locale` parameter to receive culturally relevant comparisons:

```graphql theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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