POST /v1/offset-by-tonne — Offset CO₂ by Tonne and Generate a Certificate

Allows an organization to offset CO₂ emissions by specifying the number of tonnes.
Each tonne corresponds to 20 planted trees.
If you set vcs: true, an additional 10 tree credits per tonne are deducted to attach a VCS-certified offset to the same operation.
Both deductions come from your balance, but only the tree planting appears on the public certificate.

Base URL

https://api.bloomy.earth

Endpoint

/v1/offset-by-tonne

Authentication & Headers

Authentication uses HTTP Basic Auth with your Bloomy Earth API credentials. You must use your Bloomy Earth platform username and application password.

You can find and manage these credentials in your Bloomy Earth dashboard, in the Integration API section:
👉 https://www.bloomy.earth/dashboard/#bloomy-integration-api

Headers

Header Value Required Description
Authorization Basic BASE64(username:pwd) Yes Basic Auth using your Bloomy Earth username and application password.
Accept application/json Optional Specifies that the response should be in JSON format.
Content-Type application/json Yes Specifies that the request body is sent in JSON format.

Request Body Parameters (JSON)

Example body (no VCS):

{
  "tonnes": 1
}

Example body (with VCS):

{
  "tonnes": 1,
  "vcs": true
}

JSON Body Parameter details

Field Type Required Description
tonnes number Yes Number of tonnes to offset. Must be greater than 0.
vcs boolean Optional If true, deducts +10 tree credits per tonne to attach a VCS-certified offset (not shown on the public certificate). Default: false.

Example Request

Offset with VCS certification:

curl -X POST "https://api.bloomy.earth/v1/offset-by-tonne" \
  -u YOUR_BLOOMY_USERNAME:YOUR_APPLICATION_PASSWORD \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "tonnes": 1,
    "vcs": true
  }'

JSON Response (200)

{
  "success": true,
  "certificateId": 859231,
  "certificateLink": "https://www.bloomy.earth/certificate/859231",
  "treesPlanted": 20,
  "creditBalance": 480,
  "creditsUsed": 30,
  "isVcsCertified": true,
  "projectInfo": {
    "name": "Lake Victoria Agroforestry Project in Kenya",
    "country": "Kenya",
    "location": "VQ27+Q7C Kisumu, Kenya",
    "quantity": 20,
    "carbonOffsetKg": 1000,
    "reforestedAreaHa": 0.02
  }
}

Response fields

Field Type Description
success boolean True on success.
certificateId integer Unique numeric identifier of the generated certificate.
certificateLink string (URL) Public URL of the planting certificate.
treesPlanted integer Number of trees planted (20 per tonne).
creditBalance integer Remaining tree credit balance after deduction(s).
creditsUsed integer Total tree credits deducted for this offset operation (trees + optional VCS credits if added).
isVcsCertified boolean True if VCS-certified offset credits were also used.
projectInfo.name string Project name.
projectInfo.country string Country where the project is located.
projectInfo.location string Project GPS/location string.
projectInfo.quantity integer Number of trees attributed to this project.
projectInfo.carbonOffsetKg number Estimated CO₂ offset in kilograms.
projectInfo.reforestedAreaHa number Estimated reforested surface area in hectares.

Errors

If the request is missing required data or contains invalid parameters, the API returns a JSON object with an error code and a short message.

HTTP Code Error Message When
400 invalid_request Valid tonnes are required. Missing/invalid input parameters.
401 unauthorized Authentication required. The Authorization header was missing or invalid.
403 forbidden Authentication failed. Provided credentials are invalid or lack permissions.
402 insufficient_credits Not enough Tree Credits. Balance is too low to cover trees (and optional VCS credits).
404 project_not_found The selected project is unavailable. The fixed project reference is missing/unavailable.
500 server_error Internal server error. Unexpected error while processing the request.

Error format:

{
  "error": "forbidden",
  "message": "Authentication failed."
}

Notes

  • Each tonne = 20 trees shown on the certificate.
  • If vcs: true, we deduct 10 more tree credits per tonne to attach a VCS-certified offset; this is not displayed on the public certificate.
  • When vcs: true is used, the Bloomy Earth planting certificate appears instantly to confirm your trees have been planted, while the VCS-certified certificate — issued by an external verification body — requires a few days of validation. It will be sent to you by email within 15 days and will automatically appear in your Impact Dashboard once available.
Made with ProductLift