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

# Shopify SDK

> Integrate Hey Chocolate sustainability data into your Shopify store.

The Shopify SDK provides Liquid snippets, theme app extensions, and cart integration for Shopify stores.

## Installation

Install via the Shopify App Store or add the script tag to your theme:

```html theme={null}
<script src="https://cdn.heychocolate.com/shopify/v1/heychocolate.js"></script>
<script>
  HeyChocolate.init({ apiKey: 'sk_live_your_key_here' });
</script>
```

## Product page integration

### Carbon badge

Add to your product template (`product.liquid` or theme block):

```liquid theme={null}
<div
  data-hc-carbon-badge
  data-product-id="{{ product.id }}"
  data-variant="detailed"
  data-theme="light"
></div>

<script>
  HeyChocolate.renderBadges();
</script>
```

### Impact score display

```liquid theme={null}
<div
  data-hc-impact-score
  data-product-id="{{ product.id }}"
  data-metrics="co2,mki,water"
  data-show-equivalency="true"
></div>
```

## Cart integration

Automatically calculate and display the cart's environmental impact:

```liquid theme={null}
<div
  data-hc-cart-impact
  data-session-id="{{ cart.token }}"
  data-shipping-country="{{ localization.country.iso_code }}"
></div>

<script>
  HeyChocolate.renderCartImpact();
</script>
```

The widget updates automatically when items are added or removed from the cart.

## Comparison widget

Add product comparisons to collection pages:

```liquid theme={null}
<div
  data-hc-comparison
  data-product-ids="{{ collection.products | map: 'id' | join: ',' }}"
  data-metrics="co2,mki"
  data-limit="4"
></div>
```

## Theme app extension

For Shopify 2.0 themes, use the Hey Chocolate theme app extension:

1. Install the Hey Chocolate app from the Shopify App Store
2. Go to **Online Store > Themes > Customize**
3. Add Hey Chocolate blocks to any section:
   * **Carbon Badge** — Product sustainability score
   * **Impact Calculator** — Interactive calculation widget
   * **Cart Impact** — Shopping cart carbon footprint
   * **Comparison Table** — Product comparison widget

## Webhook integration

Connect Shopify order webhooks to Hey Chocolate for automatic Scope 3 tracking:

```json theme={null}
{
  "topic": "orders/create",
  "address": "https://api.heychocolate.com/webhooks/shopify",
  "format": "json"
}
```

Every Shopify order automatically gets a carbon footprint calculation, contributing to your CSRD/ESG reports.

## Liquid variables

When using the app, the following variables are available in Liquid:

| Variable                                      | Description                  |
| --------------------------------------------- | ---------------------------- |
| `product.metafields.heychocolate.co2_score`   | CO2 equivalent in kg         |
| `product.metafields.heychocolate.mki_score`   | MKI score in EUR             |
| `product.metafields.heychocolate.equivalency` | Human-readable equivalency   |
| `product.metafields.heychocolate.dpp_url`     | Digital Product Passport URL |