Guide

Learn how to implement transaction categorisation with CarbonAPI

CarbonAPI gives developers the ability to embed carbon accounting functionality into their products and workflows. Simply submit transaction data to us, and we’ll categorise it into emissions categories, and return you an estimate of the carbon dioxide for each transaction, based on recognised emission factor databases for your jurisdiction.

PrerequisitesCopied!

A CarbonAPI API Key from the Developer Portal

LimitsCopied!

No more than 100 transactions may be supplied in each batch.

Transaction ModelCopied!

Also see the API reference.

Property	Type	Notes
id	string	An ID which you can use to keep track of the response.
date	string - ISO formatted DateTime	The date the transaction occured. Note, this must be formatted as ISO8601, or it will not be accepted.
subtotal	number	The amount of the transaction, without tax.
tax	number	The amount of tax applied to the transaction, if any
total	number	Amount + Tax
currency	string	A three letter currency code, representing the currency for the transaction, for example, AUD, GBP, NZD.
countryCode	string	A two-letter country code representing the country of the organisation receiving the transaction. We will use this to select the appropriate emission factor for the transaction, so make sure this is correct. For example: AU, NZ, GB, US.
description	string	The description of the transaction. For example: Purchase of office stationery.
supplierName	string	The name of the supplier. For example: Stationery World
sourceAccountName	string	The name of the account that the transaction is associated with. FOr example: Office Expenses

FlowCopied!

Format your transactions into the above format
Authenticate with the API
Create a transaction categorisation batch, and note the Batch ID from the CarbonAPI endpoint
Wait for a webhook with the transaction batch results

ExampleCopied!

The following example uses our TypeScript SDK. For other languages, see the API reference for code samples.

Initialise and create the batchCopied!

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

async function main() {
  // Initialize the client with your API key
  const client = new CarbonAPIClient({
    apiKey: "your-api-key-here",
  });

  try {
    // Example: Upload a batch of transactions
    const batchResponse = await client.createTransactionBatch({
      batchId: "123",
      transactions: [
        {
          id: "123",
          date: "2025-05-13T03:52:52Z",
          tax: 10,
          total: 100,
          subtotal: 90,
          currency: "GBP",
          countryCode: "GB",
          description: "Amazon.com",
          supplierName: "Amazon",
          sourceAccount: "Office Expenses",
        },
      ],
    });

    console.log("Batch ID:", batchResponse.batchId);

    // Example: Get batch status and documents
    const batchId = batchResponse.batchId;
    if (batchId) {
      const batchStatus = await client.getBatch(batchId);
      console.log("Batch Status:", batchStatus.status);
      console.log("Documents:", batchStatus.documents);
    }
  } catch (error) {
    console.error("Error:", error);
  }
}

main().catch(console.error);

Await results with the webhookCopied!

This example uses Express, but can be generalised to other frameworks.

Remember, it is important that you verify the webhook request to ensure it originated from CarbonAPI.


// Initialize the client with your API key and webhook secret
const client = new CarbonAPIClient({
  apiKey: "your-api-key-here",
  webhookSecret: "your-webhook-secret-here",
});

// Example webhook handler using Express
app.post("/webhook", async (req, res) => {
  try {
    // Verify and parse the webhook payload
    const event = await client.verifyWebhookRequest(req);

    // Handle different webhook event types
    switch (event.type) {
      case 'transaction.batch.completed':
        console.log(event.data);
      break;

      default:
        console.log("Unknown event type:", event.type);
    }

    res.status(200).json({ received: true });
  } catch (error) {
    console.error("Webhook verification failed:", error);
    res.status(400).json({ error: "Webhook verification failed" });
  }
});

// Start the server
const port = process.env.PORT || 3000;
app.listen(port, () => {
  console.log(`Webhook server listening on port ${port}`);
});