Quickstart

Make your first purchase with a test key, then go live.

1. Get access

Request API access on the developer page. Before we approve a request, the account needs two-factor authentication or a passkey. We email you once the account is active.

2. Create a test key

On the developer page, create a key in Test mode with Read and buy access. Copy it: we show it once.

Test keys spend a simulated $1,000 balance. Nothing is charged and no credits are retired, so you can build your integration safely.

3. Get a quote

A quote tells you what a purchase would buy and cost, without buying anything:

curl https://trimcarbon.com/api/v1/quotes \
  -H "Authorization: Bearer $TRIMCARBON_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kg": 100}'

4. Buy offsets

Send a unique Idempotency-Key with every purchase. If the request times out, retry it with the same key: you get the first purchase back instead of buying twice.

curl https://trimcarbon.com/api/v1/offsets \
  -H "Authorization: Bearer $TRIMCARBON_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"kg": 100, "reference": "fleet-2026-09"}'

POST/offsets

Authorization

AuthorizationBearer token · headerrequired

An API key from the developer page: tc_live_… for real purchases, tc_test_… for tests. Keep it on your server.

Header parameters

Idempotency-Keystringrequired

A unique value per purchase, such as a UUID. Retrying with the same key and body returns the first purchase (with Idempotent-Replayed: true) instead of buying again. The same key with a different body is refused with 409.

min length 1 · max length 255

Request body

requiredapplication/json

Exactly one of kg (whole kg, up to 1,000,000) and amount_cents, and an optional reference.

One of:

object

kgintegerrequired

kg of CO₂ to offset.

min 1 · max 1000000

referencestring

Your own label, such as a trip or invoice ID. Returned as you sent it; never public, never sent to the credit supplier.

min length 1 · max length 200

object

amount_centsintegerrequired

US cents to spend. Buys the most whole kg whose charge fits in this amount.

min 1 · max 5000000

referencestring

Your own label, such as a trip or invoice ID. Returned as you sent it; never public, never sent to the credit supplier.

min length 1 · max length 200

Examples

{
  "kg": 1000,
  "reference": "fleet-2026-09"
}

{
  "amount_cents": 5000
}

Responses

201

The purchase (or, on a retry, the first one).

objectstringrequired

idstringrequired

livemodebooleanrequired

False for test keys: nothing was charged or retired.

statusstringrequired

processing until the credits are bought and retired; placed once they are; refunded if we could not place the order and returned the charge to your balance.

Allowed:processingplacedrefunded

kgintegerrequired

kg of CO₂ offset.

amount_centsintegerrequired

What the purchase took from your balance.

currencystringrequired

rate_millicents_per_kgintegerrequired

Your rate in thousandths of a cent per kg: 4000 is $0.04/kg ($40 per tonne).

requestedobjectrequired

What you asked for: kg, or an amount to spend.

Show properties

kginteger | nullrequired

Show properties

Any of:

integer

integer

null

null

amount_centsinteger | nullrequired

Show properties

Any of:

integer

integer

null

null

referencestring | nullrequired

certificate_urlstring<uri> | nullrequired

The public certificate on trimcarbon.com, once the order is placed. Null for test offsets.

createdstring<date-time>required

placedstring<date-time> | nullrequired

Show properties

Any of:

string<date-time>

string<date-time>

null

null

400

Bad JSON, or a missing or invalid Idempotency-Key.

errorobjectrequired

Show properties

typestringrequired

Allowed:authentication_errorpermission_errorinvalid_request_errorrate_limit_errorapi_error

codestringrequired

messagestringrequired

paramstring

The request field that is wrong.

balance_centsinteger

With insufficient_balance: your balance now.

required_centsinteger

With insufficient_balance: what the purchase costs.

401

Missing, unknown or revoked API key.

errorobjectrequired

Show properties

typestringrequired

Allowed:authentication_errorpermission_errorinvalid_request_errorrate_limit_errorapi_error

codestringrequired

messagestringrequired

paramstring

The request field that is wrong.

balance_centsinteger

With insufficient_balance: your balance now.

required_centsinteger

With insufficient_balance: what the purchase costs.

402

insufficient_balance: the balance doesn’t cover the purchase. The error has balance_cents and required_cents.

errorobjectrequired

Show properties

typestringrequired

Allowed:authentication_errorpermission_errorinvalid_request_errorrate_limit_errorapi_error

codestringrequired

messagestringrequired

paramstring

The request field that is wrong.

balance_centsinteger

With insufficient_balance: your balance now.

required_centsinteger

With insufficient_balance: what the purchase costs.

403

api_access_inactive (the account is suspended or not approved) or insufficient_permissions (a read-only key).

errorobjectrequired

Show properties

typestringrequired

Allowed:authentication_errorpermission_errorinvalid_request_errorrate_limit_errorapi_error

codestringrequired

messagestringrequired

paramstring

The request field that is wrong.

balance_centsinteger

With insufficient_balance: your balance now.

required_centsinteger

With insufficient_balance: what the purchase costs.

409

idempotency_key_reused: the key was used for a different request.

errorobjectrequired

Show properties

typestringrequired

Allowed:authentication_errorpermission_errorinvalid_request_errorrate_limit_errorapi_error

codestringrequired

messagestringrequired

paramstring

The request field that is wrong.

balance_centsinteger

With insufficient_balance: your balance now.

required_centsinteger

With insufficient_balance: what the purchase costs.

422

validation_error (with param) or amount_too_small.

errorobjectrequired

Show properties

typestringrequired

Allowed:authentication_errorpermission_errorinvalid_request_errorrate_limit_errorapi_error

codestringrequired

messagestringrequired

paramstring

The request field that is wrong.

balance_centsinteger

With insufficient_balance: your balance now.

required_centsinteger

With insufficient_balance: what the purchase costs.

429

rate_limited: wait for the Retry-After seconds.

errorobjectrequired

Show properties

typestringrequired

Allowed:authentication_errorpermission_errorinvalid_request_errorrate_limit_errorapi_error

codestringrequired

messagestringrequired

paramstring

The request field that is wrong.

balance_centsinteger

With insufficient_balance: your balance now.

required_centsinteger

With insufficient_balance: what the purchase costs.

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

Idempotency-Keyheader*A unique value per purchase, such as a UUID. Retrying with the same key and body returns the first purchase (with `Idempotent-Replayed: true`) instead of buying again. The same key with a different body is refused with 409.

Bodyapplication/json

Request body

Request

curl -X POST 'https://trimcarbon.com/api/v1/offsets' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Idempotency-Key: 7f8d0c6e-2b1a-4e9f-9d3c-5a6b7c8d9e0f' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "kg": 1000,
  "reference": "fleet-2026-09"
}'

import axios from "axios";

const response = await axios.request({
  method: "POST",
  url: "https://trimcarbon.com/api/v1/offsets",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Idempotency-Key": "7f8d0c6e-2b1a-4e9f-9d3c-5a6b7c8d9e0f",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  data: "{\n  \"kg\": 1000,\n  \"reference\": \"fleet-2026-09\"\n}"
});

import requests

response = requests.post(
    "https://trimcarbon.com/api/v1/offsets",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Idempotency-Key": "7f8d0c6e-2b1a-4e9f-9d3c-5a6b7c8d9e0f",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"kg\": 1000,\n  \"reference\": \"fleet-2026-09\"\n}",
)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://trimcarbon.com/api/v1/offsets',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer YOUR_TOKEN',
    'Idempotency-Key: 7f8d0c6e-2b1a-4e9f-9d3c-5a6b7c8d9e0f',
    'Accept: application/json',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => '{
  "kg": 1000,
  "reference": "fleet-2026-09"
}',
]);

$response = curl_exec($curl);

Response

{
  "object": "offset",
  "id": "off_8Hq2kP0aZr4mXc1vB7nT3yLw",
  "livemode": true,
  "status": "processing",
  "kg": 0,
  "amount_cents": 0,
  "currency": "usd",
  "rate_millicents_per_kg": 4000,
  "requested": {
    "kg": 0,
    "amount_cents": 0
  },
  "reference": "string",
  "certificate_url": "http://example.com",
  "created": "2026-10-08T14:03:12.000Z",
  "placed": "2026-10-08T14:03:12.000Z"
}

{
  "error": {
    "type": "authentication_error",
    "code": "insufficient_balance",
    "message": "string",
    "param": "string",
    "balance_cents": 0,
    "required_cents": 0
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "insufficient_balance",
    "message": "string",
    "param": "string",
    "balance_cents": 0,
    "required_cents": 0
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "insufficient_balance",
    "message": "string",
    "param": "string",
    "balance_cents": 0,
    "required_cents": 0
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "insufficient_balance",
    "message": "string",
    "param": "string",
    "balance_cents": 0,
    "required_cents": 0
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "insufficient_balance",
    "message": "string",
    "param": "string",
    "balance_cents": 0,
    "required_cents": 0
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "insufficient_balance",
    "message": "string",
    "param": "string",
    "balance_cents": 0,
    "required_cents": 0
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "insufficient_balance",
    "message": "string",
    "param": "string",
    "balance_cents": 0,
    "required_cents": 0
  }
}

5. Follow the order

The offset starts as processing. Poll it until it is placed:

curl https://trimcarbon.com/api/v1/offsets/off_8Hq2kP0aZr4mXc1vB7nT3yLw \
  -H "Authorization: Bearer $TRIMCARBON_KEY"

A test offset is placed after a few seconds. A live one usually takes minutes; then certificate_url links to its public certificate.

6. Go live

Top up your balance on the developer page.
Create a Live key, and store it as a secret on your server.
Swap the test key for the live key. Nothing else changes.