# Carbon Footprint + Offset Checkout — Complete guide

> Installation Carbon Footprint + Offset Checkout is a standard WooCommerce plugin, installable like any other extension. Download the df-carbon-offset.zip file from the DataFirefly product page. In your WordPress admin, go…

- Page: <https://www.datafirefly.com/en/documentation/carbon-footprint-offset-checkout/>
- Language: en
- Last updated: 2026-07-01
- Other languages: [fr](https://www.datafirefly.com/documentation/carbon-footprint-offset-checkout/index.md), [es](https://www.datafirefly.com/es/documentation/carbon-footprint-offset-checkout/index.md), [de](https://www.datafirefly.com/de/documentation/carbon-footprint-offset-checkout/index.md), [it](https://www.datafirefly.com/it/documentation/carbon-footprint-offset-checkout/index.md), [pl](https://www.datafirefly.com/pl/documentation/carbon-footprint-offset-checkout/index.md), [nl](https://www.datafirefly.com/nl/documentation/carbon-footprint-offset-checkout/index.md), [pt](https://www.datafirefly.com/pt/documentation/carbon-footprint-offset-checkout/index.md)
- Index: <https://www.datafirefly.com/en/documentation/llms.txt>

## Installation

Carbon Footprint + Offset Checkout is a standard WooCommerce plugin, installable like any other extension.

1. Download the `df-carbon-offset.zip` file from the DataFirefly product page.
2. In your WordPress admin, go to **Plugins → Add New → Upload Plugin**.
3. Select the ZIP file, click **Install Now**, then **Activate**.
4. A new **Carbon Footprint** menu entry appears in the WooCommerce sidebar.

**Requirements:** WordPress 6.0+, WooCommerce 7.0+, PHP 7.4 minimum (PHP 8.1+ recommended). The plugin explicitly declares HPOS and Cart/Checkout Blocks compatibility — no warning appears in WooCommerce Status.

On activation, two SQL tables are created automatically: `{prefix}dfcarbon_factors` (emission factors) and `{prefix}dfcarbon_log` (offset log). The ADEME database is seeded immediately with about 25 pre-loaded factors.

## Initial configuration

The plugin works **zero-config** out of the box: ADEME factors are loaded, the badge is displayed on every product page, offset appears at checkout. But a few initial tweaks will give you far more accurate numbers.

### General settings

Go to **Carbon Footprint → Settings**. Four parameter blocks:

- **Climatiq API** — optional. Leave empty for 100% local operation on ADEME factors.
- **Offset** — enable the checkout block, price per ton (default €25/t, typical market €15–30/t), displayed partner (Gold Standard by default), customer description.
- **Transport** — enable the transport component, average distance in km (default 500 km), transport emission factor (default: road transport).
- **Display** — badge position on the product page (5 available hooks), style (card, pill, minimal), color, hook priority.

### Category → factor mapping

This is the most impactful step. Go to **Carbon Footprint → Mapping**. For each WooCommerce product category, select the most relevant emission factor from the ADEME database.

Without mapping, all your products use the `general` factor (4.50 kgCO₂e/kg), which is very approximate. Careful mapping moves you from _"rough order of magnitude"_ to _"credible estimate for reporting"_.

### Enabling the Climatiq API (optional)

Climatiq is a database of over 80,000 emission factors, more granular than the ADEME Base Empreinte on certain sectors (detailed electronics, cosmetics by component, food by supply chain). If you have a key:

1. Create an account on `climatiq.io` (free tier available for moderate usage).
2. Paste the API key into **Carbon Footprint → Settings → Climatiq API**.
3. Click **Test connection** to validate.

Once enabled, the Climatiq API is used at priority 2 (after any manual product override) and ahead of the ADEME mapping. Each result is cached for one week — no page-rendering overhead.

## How footprint calculation works

### Calculation priorities

For each product, the plugin determines the footprint via four sources, in this strict priority order:

1. **Manual product override** — if you entered a value in the "Carbon" tab of the product page (meta `_dfcarbon_kgco2e`), that value is used. It short-circuits all other sources.
2. **Climatiq API** — if an API key is configured and the product has a queryable weight or category.
3. **ADEME factor via mapping** — the factor assigned to the product category, applied to the weight.
4. **General fallback** — the `general` factor (4.50 kgCO₂e/kg) applied to the weight, or a flat value if no weight is set.

The result is cached via the WordPress object cache (group `dfcarbon_product`) and automatically invalidated on any product or mapping change.

### Transport component

If enabled, the transport component is added to the material footprint:

```
total_footprint = material_footprint + (weight_kg × distance_km × transport_factor_tkm)
```

The default road transport factor is 0.105 kgCO₂e per tonne-kilometer (ADEME source, average heavy truck). You can change the transport factor in the settings, or switch to another factor (maritime, air, etc.) if you add one to the database.

The transport component only covers **downstream transport** (warehouse to customer). The ADEME material factor already includes production and upstream transport.

## Included ADEME emission factors

The plugin ships with about 25 pre-loaded factors from the **ADEME Base Empreinte** (France). Main sectors covered:

- **Textile** — standard garment, cotton, wool, synthetic, footwear
- **Electronics** — smartphone, laptop, small appliances, large appliances
- **Food** — beef, pork, poultry, fish, dairy, dry groceries
- **Cosmetics** — body care, makeup, fragrance
- **Home** — wood furniture, metal furniture, home textiles
- **Paper** — book, magazine, cardboard packaging
- **Sport** — sports equipment, sportswear
- **Jewelry** — costume jewelry, silver, gold
- **Transport** — road transport, maritime transport
- **Fallback** — `general` (4.50 kgCO₂e/kg)

You can view, edit, delete or add your own factors from **Carbon Footprint → Factors**. Each factor has: a unique slug, a label, a value in kgCO₂e/unit, a unit (kg by default), a source (ADEME, Climatiq, custom…) and a year.

A **Reload ADEME defaults** button restores the original database _without overwriting your custom entries_: only missing ADEME slugs are re-inserted.

## The product badge

### Available styles

Three renderings to choose from (in **Settings → Display → Badge style**):

- **Card (full)** — full block with footprint, source, two educational equivalents (car km, tree years) and the offset price.
- **Inline pill** — compact "🌱 5.2 kg CO₂e" badge next to the price.
- **Minimal text** — just the value, no frame.

### Positions

The badge hooks into one of the standard WooCommerce actions:

- `after_price` — right after the price (default)
- `before_add_to_cart` — before the add-to-cart button
- `after_add_to_cart` — after the add-to-cart button
- `before_meta` — before product metadata
- `after_summary` — after the full product summary

If none of these positions fits your theme, use the `[dfcarbon_badge]` shortcode directly in a template or a page builder (Elementor, Divi, Gutenberg…).

### Hiding on specific products

In the **Carbon** tab of each product page, tick _"Hide badge"_. The footprint calculation stays active (still useful for reports and checkout), but the public display disappears. Handy for digital products, gift cards or services.

## Checkout offset

At checkout, the plugin inserts a block between the order summary and the payment method. This block contains:

- The estimated cart footprint (sum of all item footprints × their quantities)
- The matching offset cost (footprint × price per ton)
- An optional checkbox "Yes, I add €X to offset the impact of my order"
- A configurable descriptive text mentioning the partner (Gold Standard, Verra…)

When the customer ticks the box, a **dynamic WooCommerce fee** is added to the total via the `woocommerce_cart_calculate_fees` hook. The state is stored in the WooCommerce session (`dfcarbon_offset_active`), then persisted on the order via metas `_dfcarbon_cart_kgco2e`, `_dfcarbon_offset_active`, `_dfcarbon_offset_amount` and `_dfcarbon_offset_provider`.

**Important:** the plugin **collects** the offset from your customers — it does **not** automatically purchase carbon credits for you. This is deliberate, to leave you in control of timing, channel and partner (Gold Standard, Verra, Ecologi, MyClimate…). The dashboard shows the total to redeem at each payment cycle with your partner.

## Dashboard and reports

The **Carbon Footprint → Dashboard** menu displays global indicators:

- Total number of offset orders
- Cumulative CO₂ footprint measured on orders
- CO₂ footprint effectively offset
- Total amount invested in offsets

The **Carbon Footprint → Reports** menu details every offset order: date, order number, order footprint, offset kg, amount, partner. This table feeds directly into your CSRD non-financial report or any ESG audit request.

A footprint snapshot is also kept per order line (meta `_dfcarbon_line_kgco2e`): displayed values do not change retroactively when you later edit an ADEME factor.

## Available shortcodes

Three public shortcodes to embed elements anywhere on your site:

```
[dfcarbon_badge id="123" style="card"]
```

Displays the carbon badge for a specific product. `id` is required, `style` is optional (`card` by default, `pill`, `minimal`).

```
[dfcarbon_cart_summary]
```

Displays the current cart footprint and offset cost. Useful in a custom "My cart" page or a side cart.

```
[dfcarbon_stats]
```

Public block with aggregated statistics: offset tons, orders, invested amount. Perfect for a "Our climate commitment" page.

## Hooks & filters for developers

The plugin exposes a main filter to fully override the footprint calculation:

```
add_filter( 'dfcarbon_product_footprint', function( $footprint, $product_id, $context ) {
    // $footprint is an array: ['kg' => 5.2, 'source' => 'ademe', 'breakdown' => [...]]
    // Return a modified array to override
    return $footprint;
}, 10, 3 );
```

Other useful hooks:

- `dfcarbon_daily_sync` — daily WP-Cron action (purges Climatiq transients)
- `dfcarbon_before_offset_fee` — action before adding the offset fee
- `dfcarbon_offset_purchased` — action fired when persisting to an order

The plugin uses the PHP namespace `DataFirefly\CarbonOffset`. To add a factor programmatically from a mu-plugin or a child theme, import the `Database` class:

```
use DataFirefly\CarbonOffset\Database;

Database::upsert_factor( [
    'slug'   => 'my-factor',
    'label'  => 'My specific sector',
    'value'  => 2.35,
    'unit'   => 'kg',
    'source' => 'Custom',
    'year'   => 2026,
] );
```

## Multilingual (Polylang / WPML)

The plugin is compatible with Polylang Pro and WPML. The 5 shipped languages (FR, EN, ES, DE, IT) are in the `languages/` folder with pre-compiled `.po` and `.mo` files.

To adjust a translation:

1. Install Loco Translate (free plugin) or use Poedit locally.
2. Open the `df-carbon-offset-fr_FR.po` catalog.
3. Edit the entries.
4. Recompile to `.mo` — automatic in Loco Translate.

To add a language not shipped by default (Portuguese, Dutch…), duplicate an existing `.po`, rename it to the correct locale (`df-carbon-offset-pt_PT.po`, `df-carbon-offset-nl_NL.po`…), translate and compile.

## Uninstall

The plugin cleans up thoroughly on uninstall via `uninstall.php`:

- Drop tables `dfcarbon_factors` and `dfcarbon_log`
- Delete options `dfcarbon_settings` and `dfcarbon_db_version`
- Delete postmeta `_dfcarbon_*` from all products and orders
- Unschedule the `dfcarbon_daily_sync` cron
- Purge Climatiq transients

Uninstall is **destructive**: the past offset log is deleted. If you need to keep it for a CSRD audit, export the `Reports` table before uninstalling.

## FAQ

### Can I force a specific factor on a product without changing its category?

Yes. In the Carbon tab of the product page, select a factor from the "Emission factor" dropdown. It overrides the category mapping for that product only.

### What if my product has no weight?

The calculation uses a flat value for weightless products (treated as "unit"). You can also use the manual override to enter the value directly in kg CO₂e.

### Does the plugin work with variable products?

Yes. The footprint is calculated at the parent product level (via its weight and category), which is consistent for most cases. For per-variation control, use the `dfcarbon_product_footprint` filter.

### How do I handle downloadable (digital) products?

For a purely digital product (ebook, online course, software license), tick "Hide badge" and let the calculation fall back on the general factor (impact will be minimal if the product has no weight). Alternative: use the manual override with a small value (typically 0.01 to 0.1 kg CO₂e for an ebook).

### Can I exclude a product from checkout offset?

Offset applies to the cart as a whole, not product by product. To fully exclude a product from the calculation, use the `dfcarbon_product_footprint` filter and return an array with `['kg' => 0]`.

### Does the plugin make API calls on every page view?

No. Every product footprint is cached via the WordPress object cache. Climatiq API calls (if enabled) are themselves transient-cached for one week. A product page triggers no external call.

### Compatible with caches (WP Rocket, Litespeed, W3TC)?

Yes, fully. The badge is rendered server-side. The dynamic part (checkout offset checkbox) is handled via AJAX and does not affect the product page cache.