Carbon Footprint + Offset Checkout — Complete guide

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.

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.

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.

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.

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

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.