Buy carbon offsets and removals directly through the CarbonGuru API

I

I

The CarbonGuru API now buys carbon offsets and removals for your account. Your server sends an amount, CarbonGuru charges the card saved in your account and buys the carbon from the provider, and the response states what was bought. Until now the API priced carbon and built a cart, and a person finished the checkout.

What is new

  • Direct purchases. POST /v1/offsets/purchases buys offsets or removals by kilograms or by a dollar budget, one time or monthly. Offsets are charged through PayPal and removals through Stripe, each to a card saved in your account.
  • Monthly purchases you manage from your code. A monthly purchase charges the first month now and renews every month. List, pause, resume and cancel monthly purchases through the API.
  • Several items in one purchase. Send up to 100 items, either analysed items by their CarbonGuru id or amounts with a name. Each item becomes its own line on one order.
  • A named product. A purchase, a quote or a cart line can name any product from /v1/offset-products, by its catalog id or its numeric id. Without one, your account’s default product is used. /v1/offsets/defaults reads those defaults, and changes them once API purchasing is on.
  • Purchase events. Webhooks tell your server when a purchase is paid (order.offset), when its charge is declined (charge.failed) and when its certificate is issued (certificate.issued).

A purchase for 12.4 kg of carbon removal from the Frontier 2028 portfolio, with a key that has the carbon:commerce permission:

curl -X POST https://carbonguru.io/v1/offsets/purchases \
  -H "Authorization: Bearer $CARBONGURU_API_KEY" \
  -H "Idempotency-Key: order-1042-removal" \
  -H "Content-Type: application/json" \
  -d '{"type": "removal", "carbon_kg": 12.4, "product_id": "climsku_frontier_offtake_portfolio_2028"}'

The response names the product and states the kilograms you asked for, the kilograms bought, the amount charged and the purchase’s state. GET /v1/offsets/purchases/{id} reads the purchase again later. A request sent twice with the same idempotency key buys once.

Kilograms and tonnes

CNaught offsets and the Frontier removal portfolios are sold by the kilogram. Individual removal suppliers, such as Vaulted Deep, Charm Industrial, CREW, Planetary and NuLife, are sold by the tonne. Every product in the catalog now states its unit, and every quote states what a purchase of that amount would buy.

A purchase rounds up once, to the product’s next whole unit. Offsetting 7.97 kg on a product sold by the kilogram buys 8 kg. Removing 5 kg on a product sold by the tonne buys one tonne, 1000 kg. A product sold by the tonne is bought by amount rather than by a dollar budget. The provider receives exactly the quantity you paid for. Whenever an amount was rounded up, your order page and email say so and state the amount you asked for.

The website follows the same rules. The cart states a purchase sold by the tonne in tonnes, and adding such a removal from its product page buys one tonne.

Your confirmation waits for the carbon

The email that says your order is complete now goes out only after the offset or removal has been bought from the provider. If a provider order has to be retried, the email waits and sends once the carbon is bought. This applies to every offset and removal order, from the website, the API or an AI agent.

AI agents get the same

An AI agent connected to CarbonGuru through MCP can quote a named product with get_offset_quote and see its unit and what the amount would buy, and add_to_offset_cart adds a named product to your offset cart.

Switching it on

API purchasing is off until you switch it on. In the API section of your account, accept the API terms and switch on API purchasing. Save a card under Payment methods for each kind of carbon you buy. An API key never switches purchasing on, accepts terms or saves a card: those happen only in your account. Test keys cannot buy, and a purchase is a final sale.

Pricing

An API purchase costs what the same order costs on the website. Every price comes from a quote for a stated amount, and POST /v1/offsets/quote returns one before you buy.

Get started

Switch on API purchasing in the API section of your account. The API overview covers what the API does, the API reference documents every call, and the API terms cover purchases.

Recent Posts

Categories