Schnellstart

Tätigen Sie Ihren ersten Kauf mit einem Testschlüssel und wechseln Sie dann in den Echtbetrieb.

1. Zugang erhalten

Beantragen Sie API-Zugang auf der Entwicklerseite. Bevor wir einen Antrag genehmigen, muss das Konto die Zwei-Faktor-Authentifizierung oder einen Passkey nutzen. Wir senden Ihnen eine E-Mail, sobald das Konto aktiv ist.

2. Testschlüssel erstellen

Erstellen Sie auf der Entwicklerseite einen Schlüssel im Modus Test mit dem Zugriff Lesen und kaufen. Kopieren Sie ihn sofort, denn wir zeigen ihn nur einmal an.

Testschlüssel verbrauchen ein simuliertes Guthaben von 1.000 $. Es wird nichts abgerechnet und es werden keine CO₂-Zertifikate stillgelegt. So können Sie Ihre Integration gefahrlos entwickeln.

3. Angebot einholen

Ein Angebot zeigt Ihnen, was ein Kauf umfassen und kosten würde, ohne dass etwas gekauft wird:

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

4. Kompensationen kaufen

Senden Sie bei jedem Kauf einen eindeutigen Idempotency-Key mit. Wenn bei der Anfrage eine Zeitüberschreitung auftritt, wiederholen Sie sie mit demselben Schlüssel. Sie erhalten dann den ersten Kauf als Antwort, statt doppelt zu kaufen.

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. Bestellung verfolgen

Eine Kompensation hat zunächst den Status processing. Fragen Sie sie regelmäßig ab, bis sie den Status placed hat:

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

Eine Testkompensation erreicht den Status placed nach wenigen Sekunden. Bei einer echten Kompensation dauert das meist einige Minuten. Danach verweist certificate_url auf ihr öffentliches TrimCarbon-Zertifikat.

6. Echtbetrieb starten

Laden Sie Ihr Guthaben auf der Entwicklerseite auf.
Erstellen Sie einen Schlüssel im Modus Echt und speichern Sie ihn als Secret auf Ihrem Server.
Ersetzen Sie den Testschlüssel durch den echten Schlüssel. Sonst ändert sich nichts.