Set up CarbonGuru Offsetting with Stripe

Bill through Stripe? Invoices, subscriptions, one-time products on hosted Checkout or Payment Links — an online store, a SaaS, or a business that sends Stripe invoices. Install the CarbonGuru app from Stripe and your products and plans are analyzed, a footprint line appears wherever Stripe shows them, and every paid invoice and Checkout order is offset automatically — billed to you, never to your customers. Six steps, about fifteen minutes of your time, no code.

1. Add CarbonGuru to your Stripe account

You

Click the button, sign in to Stripe if asked, and approve the permissions the app requests. They let CarbonGuru read your products and prices, receive your paid invoices and Checkout Sessions, and write one footprint line into a product description when you ask it to — nothing else.

Add CarbonGuru to Stripe

You can install into a sandbox or test mode first: everything below works the same, and every test order arrives as a preview that is never charged.

Three steps only you can do: installing the app, connecting your CarbonGuru account and saving a card, and switching automatic offsetting on — each is a legal or payment act. Everything else happens on its own or can be done by an AI agent (see Let your agent do it).

2. Connect your CarbonGuru account

You

Stripe sends you to carbonguru.io/merchant-connect. Sign in, or create an account on the Plus, Pro or Prime plan (Embedded Offsetting is included — nothing to add on; if you create the account now, return to the same link afterwards). Read and accept the Merchant Terms, choose carbon offsets or carbon removals and the portfolio they fund, and click Approve and connect. You are returned to your Stripe Dashboard.

Then open My account → Embedded offsetting once and save a payment method with the processor that bills your choice — PayPal for offsets, Stripe for removals. Nothing is charged until step 6. All purchases are final: retired carbon can’t be un-retired, so there are no refunds.

3. Your products and plans are analyzed on their own

Nobody — it happens

The moment you connect, CarbonGuru reads your Stripe products and prices and calculates one carbon footprint per price — one-time products and recurring plans alike; monthly and yearly plans are measured separately because they are priced differently. A handful of products takes a few minutes; the panel reports what was sent, analyzed and skipped. A price of zero has no amount to measure, so it is skipped and reported. Add a product or price later and click Re-import from Stripe in the panel — the import runs when you ask it to, never on its own.

4. Switch on your products and turn on checkout display

You or your agent

Every footprint arrives switched off. In the panel switch on the products and plans you sell — nothing displays and nothing is offset until a product is on.

A footprint belongs to a price, and a Stripe product’s description is one field shared by all of its prices, so the app writes a line only where it can be true: the product has a single price and a description of its own. A product sold at several prices, or with no description of its own, is left alone — the confirmation names those products before anything is written, and their footprints show in your panel, on your own pages and on each order receipt.

Then turn on “Show footprints at checkout”. The app appends one clearly marked line to the end of each switched-on product’s description, for example:

Carbon footprint 3.2 kg CO₂e

Stripe shows it wherever it shows the description: hosted Checkout, Payment Links, the customer portal, quotes and invoices. The line is kept current when a footprint is recomputed. Turn the setting off and every line is removed; you can also edit or delete a line yourself, and we will not put it back.

5. Watch a preview order

You

There is nothing to report: every paid invoice and completed Checkout Session reaches CarbonGuru through the app. Until step 6 each one appears in the panel as a preview — the products that matched, the kg, and no charge. Trigger one with a test Payment Link purchase, a test subscription or a Stripe test clock, or wait for a real order.

  • A one-time purchase on hosted Checkout or a Payment Link is offset once, when it is paid.
  • Each billing period is offset once: the first invoice and every renewal count; a mid-cycle plan change (an all-proration invoice) is skipped until the next renewal.
  • A $0 trial invoice matches its plan and is recorded for its price of zero — nothing is charged.
  • Sandbox and test-mode installs stay previews for good.

6. Turn on automatic offsetting

You, or your agent on your instruction

In the panel choose how we email you about purchases, choose Daily settlement — one charge to your card and one offset order a day across all of that day’s orders and renewals — and flip the switch. From then on every paid invoice and Checkout order is offset, and every purchase appears in your history with its receipt. You can pause any time.

The confirm dialog says it plainly: from now on every paid order is charged to your saved card and the carbon is retired. Retired carbon cannot be un-retired — there are no refunds.

What the app covers

Any Stripe account, not only online stores. The app sees an order wherever Stripe records a payment against your catalog:

  • Stripe Invoicing — every paid invoice, including ones you send by hand to clients.
  • Stripe Billing — the first invoice and every renewal of a subscription, each period once.
  • Hosted Checkout and Payment Links — one-time purchases and subscription sign-ups.

Three limits today:

  • Only lines backed by a Stripe product count. An invoice line typed in by hand, or a Checkout Session built with an ad hoc price, has no product to match and is skipped — the rest of the order is still offset. Set up what you sell as Stripe products and it is covered.
  • Your own currency. Prices are read in the currency you set them in, and orders in any currency are offset. CarbonGuru bills you in US dollars.
  • Checkout, Payment Links and Invoicing only. An integration that charges through raw PaymentIntents never reaches Stripe’s hosted surfaces and is not seen by the app; report those orders through the manual path instead.

Optional: a footprint tile beside each plan on your pricing page

Your developer

The app covers Stripe’s own pages. For your own pricing page, enter your site address and authorize an embed key in the panel (steps 2 and 3 there), then add the loader tag once and one tile per plan, keyed to the price whose amount is currently shown. If the page has a Monthly / Yearly toggle, swap the tile’s reference when it changes.

<script src="https://carbonguru.io/embed.js" data-cg-merchant="mk_live_…" data-cg-page="off" async></script> <div data-cg-ref="price_…"></div>

Tiles are keyed to the plan, not the page: nothing on the page is read or analyzed, and the tile sends us only your embed key and the plan reference — never anything a visitor types, and no cookies. About ten minutes.

Removing the app

Turn checkout display off first, so the app removes its lines while it still can, then uninstall it from your Stripe Dashboard (or disconnect from the panel). Uninstalling revokes our access and deletes the credential; your footprints and purchase history stay in your CarbonGuru account. If you uninstall before turning display off, the lines remain in your descriptions until you delete them — the panel tells you how many.

Not using the app?

Selling through Stripe without installing the app — a custom integration, or a platform the app does not reach — still works. These are the twelve manual steps the app replaces.

Show the manual steps

1. Create your CarbonGuru account and accept the merchant terms

You

Embedded Offsetting is included in the Plus, Pro and Prime plans — nothing to add on. Sign in or choose a plan, open My account → Embedded offsetting, and in step 1 read and accept the Merchant Terms and data-processing agreement. They cover billing your saved card for offsets.

Four steps only you can do: this one, your site address, issuing your keys, and saving a card — each is a legal or payment act. Everything else on this page an AI agent or your developer can do for you (see Let your agent do it).

2. Enter your site address

You

Step 2: your website’s address, for example example.com. It is where your pricing page lives and the only domain the footprint tiles answer to.

3. Authorize your keys

You

Step 3: click Authorize. Three credentials are issued — a public embed key (pre-filled into every snippet on the page), a webhook secret (not needed for Stripe) and an API key (sk_merchant_…). The API key is shown once: put it in your secrets manager and give it to your developer, or to your agent as a secret.

4. Choose what the footprint card shows

You or your agent

Step 4: the carbon footprint always shows; the offset or removal price, the climate-impact estimate, the category tooltip and your portfolio are off until you turn them on. Turn on “Show footprints at checkout and after the order is placed” — that is the switch for the line you will put on Stripe’s pages in step 8.

5. Choose offsets or removals, and save a card

You

Step 5: pick carbon offsets or carbon removals and the portfolio they fund. Step 6: save a payment method with the processor that bills your choice — PayPal for offsets, Stripe for removals. Nothing is charged until step 12.

All purchases are final — retired carbon can’t be un-retired, so there are no refunds.

6. Add your plans as footprints

You or your agent

A service sold as plans works like a product: one footprint per plan and billing term, because monthly and yearly are priced differently. In step 7 choose Upload your product catalog, download the template and fill one row per plan and term: the plan name, its price, USD, and in the sku column the Stripe price id (price_…, from Product catalog → the plan → the price). A short description of what the plan includes helps the analysis.

Upload, then wait for “Analyzed n of n” — a few minutes for a handful of plans. Free plans have no invoice and need no row.

From code or an agent instead of the upload — the same rows, one call:

POST https://carbonguru.io/api/v1/merchant/calculate Authorization: Bearer sk_merchant_… { "rows": [ { "product_name": "Standard (monthly)", "price": { "current_price": 120.00, "currency": "USD" }, "geographic_context": { "country_code": "US" }, "identifiers": ["price_…"], "description": "What the plan includes", "category": "software subscription / hosted SaaS" } ] }

7. Switch on your plans

You or your agent

Every footprint arrives switched off. In step 7c switch on the plans you sell. Nothing displays and nothing is offset until a plan is on.

8. Put the footprint on Stripe’s Checkout, portal and invoices

You, or your agent with your Stripe access

Stripe’s hosted Checkout page can’t run our card, but it prints each product’s description — and so do the customer portal and hosted invoices. Step 8 has a block, Footprint lines for your checkout, with one ready line per active plan, for example:

Carbon footprint 3.2 kg CO₂e

In your Stripe Dashboard, open each plan’s product and paste its line at the end of the product description. If one product carries both the monthly and the yearly price, paste both lines. From the next checkout on, the line shows under the plan. When a footprint is recomputed the line in step 8 changes and you re-paste it.

CarbonGuru never holds a Stripe key: the paste is yours, or your agent’s using your own Stripe connector. From code, GET https://carbonguru.io/wp-json/cg/v1/merchant/products?identifiers[]=price_… with your API key returns each plan’s display_text.

9. Put a footprint tile beside each plan on your pricing page

Your developer

Step 8, Tiles for any page: the loader tag once, then one tile per plan, keyed to the price whose amount is currently shown. If your page has a Monthly / Yearly toggle, swap the tile’s reference when it changes.

<script src="https://carbonguru.io/embed.js" data-cg-merchant="mk_live_…" data-cg-page="off" async></script> <div data-cg-ref="price_…"></div>

Tiles are keyed to the plan, not the page: nothing on the page is read or analyzed, and the tile sends us only your embed key and the plan reference — never anything a visitor types, and no cookies. About ten minutes.

10. Report each paid invoice

Your developer

Step 9, Stripe Billing: in the webhook handler you already run for Stripe, on invoice.paid, post the invoice to us. Only invoices that start or renew a subscription, so each billing period is offset once:

if (event.type === 'invoice.paid') { const inv = event.data.object; if (!['subscription_create', 'subscription_cycle'].includes(inv.billing_reason ?? '')) return; await fetch('https://carbonguru.io/wp-json/cg/v1/merchant/order', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.CARBONGURU_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ order_ref: inv.id, currency: inv.currency, line_items: inv.lines.data.map((line) => ({ identifier: line.price?.id ?? line.pricing?.price_details?.price, quantity: line.quantity ?? 1, })), }), }); }
  • Post invoice.paid only, not invoice.payment_succeeded as well. A repeat of the same invoice id is ignored.
  • A $0 trial invoice still matches its plan and is offset for its price of zero — nothing is charged. Skip invoices with amount_paid === 0 if you would rather not record trials.
  • A mid-cycle plan change produces a subscription_update invoice with proration lines for both plans; the filter above leaves it out, so each period is offset once at the next renewal.
  • Test mode: post test-mode events only while automatic offsetting is off (step 12); they arrive as previews.
  • The endpoint answers 200 with a status body; 401 means the key is wrong; 422 names the field.

About fifteen minutes including deploy. An agent can also report an invoice for you with the report_store_order tool — useful for a test or a backfill, not as the everyday path.

11. Watch a preview order

You or your agent

Step 11: trigger a test-mode invoice.paid (a Stripe test clock, or a test subscription), or have your agent report a recent real invoice. It appears in the panel as a preview: the plan that matched, the kg, and no charge. If nothing appears within a few minutes, the usual causes are the wrong API key or an identifier that isn’t a sku from step 6.

12. Turn on automatic offsetting

You, or your agent on your instruction

Step 10: choose how we email you about purchases. Step 12: choose Daily settlement — one charge to your card and one offset order a day across all of that day’s orders and renewals — and flip the switch. From then on every paid invoice you report is offset, and every purchase appears in your history with its receipt. You can pause any time.

The confirm dialog says it plainly: from now on every paid order you send us is charged to your saved card and the carbon is retired. Retired carbon cannot be un-retired — there are no refunds.

Let your agent do it

Any AI agent you sign in with can do everything above except the three human steps. Add the CarbonGuru connector — https://carbonguru.io/mcp — to your agent and sign in with your CarbonGuru account. No API key is needed on the app path. The tools it uses:

  • get_embedded_offsetting_status — the checklist; call it first.
  • get_activation_readiness — what is still blocked on you, with a link for each.
  • list_store_catalog, set_product_active — step 4, switching plans on.
  • update_display_settings — step 4, checkout_display.
  • set_settlement_mode, set_automatic_offsetting — step 6, the switch only when you say so.

Paste this into your agent after you have installed the app and connected your account:

Connect to the CarbonGuru MCP at https://carbonguru.io/mcp as me. My Stripe account is connected through the CarbonGuru app. Start with get_embedded_offsetting_status. Wait until my plans are analyzed, then activate them all and turn on checkout_display. Set settlement to daily. Tell me what is still blocked on me. Do not turn automatic offsetting on until I say so.

Show the offset receipt in your own emails (optional)

On the manual path below, the order POST answers with a token. The public receipt for that invoice is https://carbonguru.io/offset-receipt/<token> — it reads “pending” until the order is offset, then shows the retirement. Store the token against the invoice and include the link in the renewal email you already send.

Currencies

Prices are read in the currency you set them in, and orders in any currency are offset. CarbonGuru’s own prices are in US dollars, so what you pay CarbonGuru is charged in USD.

Getting help

Email support@carbonguru.io with your CarbonGuru account email and the step you are on. Hands-on time with the app is about fifteen minutes; on the manual path about 45 minutes across the account owner, an agent and a developer. Footprints compute in the background.