Get a quote

What a purchase would buy and cost at your rate, and whether your balance covers it. Buys nothing.

POST/quotes

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.

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

200

The quote.

objectstringrequired

livemodebooleanrequired

False for test keys: nothing was charged or retired.

kgintegerrequired

amount_centsintegerrequired

What the purchase would cost.

currencystringrequired

rate_millicents_per_kgintegerrequired

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

available_centsintegerrequired

Your balance now.

sufficient_balancebooleanrequired

requires_reviewbooleanrequired

The purchase is larger than your account’s automatic limit: it would wait for our review before the credits are retired.

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.

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.

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

Bodyapplication/json

Request body

Request

curl -X POST 'https://trimcarbon.com/api/v1/quotes' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -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/quotes",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "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/quotes",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "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/quotes',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer YOUR_TOKEN',
    'Accept: application/json',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => '{
  "kg": 1000,
  "reference": "fleet-2026-09"
}',
]);

$response = curl_exec($curl);

Response

{
  "object": "quote",
  "livemode": true,
  "kg": 0,
  "amount_cents": 0,
  "currency": "usd",
  "rate_millicents_per_kg": 4000,
  "available_cents": 0,
  "sufficient_balance": true,
  "requires_review": true
}

{
  "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
  }
}