Inicio rápido

Haga su primera compra con una clave de prueba y luego pase a producción.

1. Obtenga acceso

Solicite acceso a la API en la página Desarrolladores. Antes de aprobar una solicitud, la cuenta necesita autenticación de dos factores o una llave de acceso. Le enviaremos un correo electrónico cuando la cuenta esté activa.

2. Cree una clave de prueba

En la página Desarrolladores, cree una clave en modo Prueba con acceso de Lectura y compra. Cópiela: solo la mostramos una vez.

Las claves de prueba gastan un saldo simulado de 1000 US$. No se cobra nada y no se retiran créditos, así que puede crear su integración de forma segura.

3. Obtenga una cotización

Una cotización le indica qué obtendría con una compra y cuánto costaría, sin comprar nada:

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

4. Compre compensaciones

Envíe una Idempotency-Key única con cada compra. Si se agota el tiempo de espera de la solicitud, reinténtela con la misma clave: recibirá la primera compra en lugar de comprar dos veces.

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. Haga seguimiento del pedido

La compensación comienza en estado processing. Consúltela periódicamente hasta que esté en placed:

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

Una compensación de prueba se realiza al cabo de unos segundos. Una real suele tardar unos minutos; después, certificate_url enlaza a su certificado público.

6. Pase a producción

Recargue su saldo en la página Desarrolladores.
Cree una clave Real y guárdela como secreto en su servidor.
Reemplace la clave de prueba por la clave real. No cambia nada más.