How-to guideCarbon Measurement

Enrich transactions synchronously

Send anonymised transactions to the Connect Earth API and receive CO2e estimates and equivalents back in the same response.

Synchronous integration is the simplest way to integrate with the Carbon Measurement API: your back end sends anonymised transaction data and receives a CO2e estimate and equivalents back in the same response. Connect Earth stores nothing, so there is no data to keep in sync — you decide when to enrich and whether to keep the results.

How it works

There are two ways to time the enrichment.

Enrich when the user views transactions

Enrich just in time: when a user opens their transactions, your back end sends them to the API and returns the enriched results to the front end. You can optionally cache or store the enriched results in your own database so repeat views don't call the API again.

Enrich as transactions occur

Enrich each transaction once, at the moment it is created — for example, as part of processing a card payment. The enriched transaction is stored in your own database, and the front end is always served from your store without waiting on an API call.

Enriching as transactions occur means each transaction is sent to the API exactly once and your app stays fast, at the cost of storing the results yourself. Enriching on view needs no storage to get started, but repeat views make repeat API calls unless you cache.

Before you start

You will need:

• An API key, created in the developer console.
• Anonymised transaction data — for each transaction, the amount, currency, category (such as an MCC), and the country the transaction took place in. Never send personal data; Connect Earth only needs the fields required to estimate emissions.

Enrich transactions

1. Send transactions at your chosen moment — as each transaction occurs, or when the user views them. Send a single transaction to POST /transaction, or several at once with POST /transaction/bulk; both return results in the same response. See the Carbon Measurement API reference for the full request and response schemas.
2. Handle the response. Each transaction comes back with a CO2e estimate in kilograms and an equivalents array of relatable comparisons (for example, kilometres driven in an average car). Each equivalent has a stable key, a numeric value, and a templated text string — see carbon equivalents for how to render and localise them.
3. Display the results in your application. Show the CO2e estimate and an equivalent alongside each transaction. The UI/UX best practices guide covers language and framing that help users engage with the numbers rather than feel judged by them.

Get insights

Enrichment can also power summary views: send a set of transactions to POST /charts/pie and receive a breakdown of emissions by category in the same response. Because Connect Earth stores nothing, every insights request must re-send the underlying transactions — if you want insights over longer periods without re-sending data each time, the asynchronous pattern, where Connect Earth stores anonymised transactions for later querying, is a better fit.

Next steps

• Personalise estimates with user habits.
• Surface tips and recommendations based on spending patterns.
• Explore the full Carbon Measurement API reference.