Set up CarbonGuru Offsetting with Stripe Billing

Sell plans through Stripe Billing and Stripe’s hosted Checkout? Show a real carbon footprint beside each plan on your pricing page and on Checkout, the customer portal and invoices — and offset every paid subscription automatically. Your checkout, your billing and your Stripe account stay exactly as they are; CarbonGuru never holds a Stripe key.

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 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 four human steps. Add the CarbonGuru connector — https://carbonguru.io/mcp — to your agent, sign in with your CarbonGuru account, and give it the API key from step 3 as a secret. The tools it uses:

  • get_embedded_offsetting_status — the 12-step checklist; call it first.
  • get_activation_readiness — what is still blocked on you, with a link for each.
  • update_display_settings — step 4, including checkout_display.
  • list_store_catalog, set_product_active — steps 6 and 7 (rows are pushed with the API call in step 6).
  • report_store_order — step 11, a test or a backfill.
  • set_settlement_mode, set_automatic_offsetting — step 12, the switch only when you say so.

Paste this into your agent after the four human steps:

Connect to the CarbonGuru MCP at https://carbonguru.io/mcp as me and set up embedded offsetting for my Stripe Billing plans. Start with get_embedded_offsetting_status. Turn on checkout_display. Push my plans as catalog rows (one per plan and term, Stripe price id as identifier) to https://carbonguru.io/api/v1/merchant/calculate with the API key I gave you, wait for footprints, then activate them all. Read each plan's display_text from /wp-json/cg/v1/merchant/products and append it to the matching product description in my Stripe account using my Stripe connector. Give my developer the pricing-page tile snippet and the invoice.paid POST recipe. Report my most recent paid invoice as a test and show me the preview. 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)

The order POST in step 10 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.

If your prices are not in US dollars

Embedded Offsetting supports USD in this version. Invoices in other currencies are received and recorded so you can see them, but they are not offset, and non-USD catalog rows are skipped and reported.

Getting help

Email support@carbonguru.io with your CarbonGuru account email and the step you are on. Hands-on time for the whole setup is about 45 minutes across the account owner, an agent and a developer; footprints compute in the background.