Categorising and calculating spend-based emissions

Introduction

One of CarbonAPI's main features is the ability to categorise arbitrary expense lines, have them categorised into an emissions category.

For example, consider the following expense line item:

Date: 05/05/2019
Supplier: Air New Zealand
Description: Company retreat flights
Subtotal: 499.00
Currency: NZD

There are a few steps required to turn this into an emissions estimate:

1. Understand the context of the expense
2. Match the expense to an emission category, for example I_FLIGHTS_AIR_TRAVEL
3. Search for an appropriate emission factor, taking into account reporting needs
4. Apply inflationary and potentially FX calculations
5. Multiply the input subtotal by the resulting emission factor.

CarbonAPI handles all of these for you. Let's try with a practical example.

Step-by-step guide

First, we need to sign up for CarbonAPI. You can do this and get free evaluation credits by heading to the Account Portal and signing up.

For this guide, we'll use polling to check for the results of our call, but to reduce overhead, we strongly reccomend using our Webhooks approach, which allows you to be notified once processing has completed.

Now, you can either review our API Reference, or drop in our TypeScript SDK, which will allow you to get started quickly.

Okay, so we're ready to start making calls. Let's make some some expenses to get started with:

import { CarbonAPIClient } from "@carbonapi/typescript-sdk";

// Initialize the client with your API key
const client = new CarbonAPIClient({
  apiKey: "your-api-key-here", // Get this from the Account Portal
});

// Create a batch of transactions
const { batchIds } = await client.createTransactionBatch({
  transactions: [
    {
      id: "123", // Important - we'll use this later to match our response to your transaction.
      date: "2025-05-13T03:52:52Z",
      tax: 10,
      total: 100,
      subtotal: 90,
      description: "Purchase of new laptop",
      supplierName: "Mighty Ape",
      sourceAccount: "Office Expenses",
      currency: "NZD",
    },
  ],
  countryCode: "NZ",
});

Important See the Create Transaction Batch for the full type requirements, but the most important thing to note here is that the id parameter must be unique within a batch, as this is what is used to match up to results later.

Okay, so we have now created a categorisation job. At the time of writing, only an asynchronous approach is supported, but we plan to add sync calls in the future.

Now, let's poll for changes in the batch. As mentioned, this is not the preferred approach, we strongly suggest using Webhook calls to reduce the complexity of your application, this is just for demo purposes.

Note, this is queue-based service. Your request will be processed as soon as possible, but you may need to wait for a few minutes when we're busy. Again, a good reason to use Webhooks!

const poll = setInterval(() => {
  // Remember don't do this in production!
  const batchId = transactionBatchResponse.batchIds[0];

  const transactionBatch = await client.getTransactionBatch(batchId);

  if (transactionBatch.status === "Completed") {
    console.log(transactionBatch.transactions); // This will contain your categories and emissions information.
    clearInterval(poll); // Don't forget to do this.
  }
}, 10_000); // Call every 10 seconds.

Understanding the results

Let's take a look an example expense result:

{
  "id": "11111111-1111-1111-1111-111111111111",
  "code": "I_FLIGHTS_AIR_TRAVEL",
  "confidence": 95.82,
  "potentialFactors": [
    {
      "code": "string",
      "similarity": 0
    }
  ],
  "co2e": 114.5,
  "emissionFactor": {
    "name": "Flights and Air Travel",
    "source": "CarbonAPI Example Factor Source",
    "sourceUrl": "https://www.carbonapi.io"
  }
}

We automatically perform FX calculations and CPI adjustments on the data you pass us. In the future we'll also include these in the response for even greater auditability.

Output types

id - This is the ID you sent in the createTransactionBatch call. Use this to match back up on your end.

code - The code from our taxonomy that represents our prediction of which emission category this expense belongs in, or UNKNOWN if we cannot predict a category. See potentialFactors for the closest matches in our database.

potentialFactors - If the result was UNKNOWN, we'll tell you about the factors we considered. Useful for UIs.

co2e - The assessed carbon dioxide equivalents in kilograms of carbon dioxide equivalent calculated for this expense, using the emission factor below.

emissionFactor - The emission factor we selected for calculation.