Démarrage rapide

Effectuez votre premier achat avec une clé de test, puis passez en mode réel.

1. Obtenir l’accès

Demandez l’accès à l’API sur la page Développeurs. Avant que nous approuvions une demande, le compte doit avoir activé l’authentification à deux facteurs ou une clé d’accès. Nous vous envoyons un e-mail dès que le compte est actif.

2. Créer une clé de test

Sur la page Développeurs, créez une clé en mode Test avec l’accès Lecture et achat. Copiez-la : nous ne l’affichons qu’une seule fois.

Les clés de test dépensent un solde simulé de 1 000 $. Rien n’est facturé et aucun crédit n’est retiré : vous pouvez donc développer votre intégration en toute sécurité.

3. Obtenir un devis

Un devis vous indique ce qu’un achat vous permettrait d’obtenir et combien il coûterait, sans rien acheter :

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

4. Acheter des compensations

Envoyez un en-tête Idempotency-Key unique avec chaque achat. Si la requête expire, renvoyez-la avec la même clé : vous récupérez le premier achat au lieu d’acheter deux fois.

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. Suivre la commande

La compensation commence à l’état processing. Interrogez-la régulièrement jusqu’à ce qu’elle passe à l’état placed :

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

Une compensation de test est passée au bout de quelques secondes. Une compensation réelle prend généralement quelques minutes ; ensuite, certificate_url renvoie vers son certificat public.

6. Passer en mode réel

Approvisionnez votre solde sur la page Développeurs.
Créez une clé en mode Réel et stockez-la comme secret sur votre serveur.
Remplacez la clé de test par la clé réelle. Rien d’autre ne change.