Retirements

Retirements

List retirements

Callable by any access token regardless of permissions. This endpoint returns all retirements, both on platform and off - if a retirement has not been claimed by a KYBd organization the only data shown is the amount and the project and a pdf can not be generated.

List retirements

get

This endpoint returns all retirements, both on platform and off - if a retirement has not been claimed by a KYBd organization the only data shown is the amount and the project and a pdf can not be generated.

Query parameters

skipnumberRequired

The amount of items to skip

Example: 10

firstnumberRequired

The number of elements to return

Example: 0

Header parameters

x-icr-api-versionstringOptional

API version

Default: 2023-06-16

Responses

200Success

application/json

get

/retirements/list

HTTPcURLJavaScriptPython

GET /retirements/list?skip=1&first=1 HTTP/1.1
Host: api.carbonregistry.com
Accept: */*

200Success

{
  "retirements": [
    {
      "createdAt": "2026-02-24T21:20:51.735Z",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "isClaimed": true,
      "reason": "Reached retirement age",
      "comment": "Congratulations on your retirement!",
      "beneficiary": "John Doe",
      "organizationId": "123e4567-e89b-12d3-a456-426614174000",
      "organizationOwner": {
        "total": 100,
        "currentPage": 1,
        "pageCount": 10,
        "nextPage": 2,
        "prevPage": 0
      },
      "serialization": "ICR-ISL-354-78040-14-R-0-2021",
      "vintage": "2020",
      "amount": 1000,
      "project": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "fullName": "Project 1",
        "url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
        "publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
        "num": "713"
      }
    }
  ]
}

cURL

curl -X 'GET' \
  'https://api.carbonregistry.com/retirements/list' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"\
  -H 'x-icr-api-version: 2023-06-16'

Typescript

Get retirement

Callable by any access token regardless of permissions. This endpoint returns the data connected to a particular retirement.

Callable by any access token regardless of permissions.

Get retirement

get

This endpoint returns a json object with the retirement information.

Query parameters

idstringRequired

The ICR id of the retirement.

Example: 2

Header parameters

x-icr-api-versionstringOptional

API version

Default: 2023-06-16

Responses

200Success

application/json

createdAtstring · date-timeRequired

The date of when this retirement was made

idstringRequired

The ID of the retirement

Example: 123e4567-e89b-12d3-a456-426614174000

isClaimedbooleanOptional

Whether this retirement has been claimed - is false if the retirement happened permissionlessly on blockchain and owner has not claimed the retirement on ICR

reasonstringOptional

The reason for the retirement

Example: Reached retirement age

commentstringOptional

A comment about the retirement

Example: Congratulations on your retirement!

beneficiarystringOptional

The name of the retiree

Example: John Doe

organizationIdstringRequired

The ID of the organization associated with the retirement

Example: 123e4567-e89b-12d3-a456-426614174000

serializationstringOptional

The serialization of the carbon credits associated with the retirement

Example: ICR-ISL-354-78040-14-R-0-2021

vintagestringOptional

The vintage year of the carbon credits associated with the retirement

Example: 2020

amountnumberRequired

The amount of the retirement

Example: 1000

get

/retirements

HTTPcURLJavaScriptPython

GET /retirements?id=text HTTP/1.1
Host: api.carbonregistry.com
Accept: */*

200Success

{
  "createdAt": "2026-02-24T21:20:51.735Z",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "isClaimed": true,
  "reason": "Reached retirement age",
  "comment": "Congratulations on your retirement!",
  "beneficiary": "John Doe",
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "organizationOwner": {
    "total": 100,
    "currentPage": 1,
    "pageCount": 10,
    "nextPage": 2,
    "prevPage": 0
  },
  "serialization": "ICR-ISL-354-78040-14-R-0-2021",
  "vintage": "2020",
  "amount": 1000,
  "project": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "fullName": "Project 1",
    "url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
    "publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
    "num": "713"
  }
}

Get retirement pdf

Given an id of the retirement this is an endpoint that downloads the certificate.

Callable by any access token regardless of permissions.

Get retirement pdf

get

This endpoint returns a specificretirement as a pdf

Path parameters

retirementIdstringRequired

Header parameters

x-icr-api-versionstringOptional

API version

Default: 2023-06-16

Responses

200

File content

application/octet-stream

get

/retirements/{retirementId}/pdf

HTTPcURLJavaScriptPython

GET /retirements/{retirementId}/pdf HTTP/1.1
Host: api.carbonregistry.com
Accept: */*

200

File content

Finalize a retirement

Callable by any access token regardless of permissions. This endpoint finalizes a given retirement certificate by setting the beneficiary, reason and comment for the certificate to become finalized. This is mainly for retirements that happened off platform - onchain. See here for more info.

Finalize retirement certificate

post

This endpoint can be used by owners of an onchain retirement to finalize their retirement certificate - a certificate is only available for finalization if the retirement was made onchain and the beneficiary is missing.

Header parameters

x-icr-api-versionstringOptional

API version

Default: 2023-06-16

Body

application/json

signerstringRequired

The signer address.

Example: 0xA0022c05501007281acAE55B94AdE4Fc3dd59ec3

signaturestringRequired

The signature. This a standard signature created by signing the data as a string in the following format - with double ";;" between each field - "beneficiary;;comment;;reason;;projectAddress;;tokenId" for info on how to sign strings see -> https://docs.ethers.org/v6/cookbook/signing/#cookbook-signing-messages

Example: 0xf76145d74ff1a3e70ca51e44063b6a90cf5e5d82e11941d3691e9dee197d124f748b6fcd8d3ecc7a45e08fe698be6f9e24685b5d8e270612e727380ede19c3321c

Responses

200Success

application/json

createdAtstring · date-timeRequired

The date of when this retirement was made

idstringRequired

The ID of the retirement

Example: 123e4567-e89b-12d3-a456-426614174000

isClaimedbooleanOptional

Whether this retirement has been claimed - is false if the retirement happened permissionlessly on blockchain and owner has not claimed the retirement on ICR

reasonstringOptional

The reason for the retirement

Example: Reached retirement age

commentstringOptional

A comment about the retirement

Example: Congratulations on your retirement!

beneficiarystringOptional

The name of the retiree

Example: John Doe

organizationIdstringRequired

The ID of the organization associated with the retirement

Example: 123e4567-e89b-12d3-a456-426614174000

serializationstringOptional

The serialization of the carbon credits associated with the retirement

Example: ICR-ISL-354-78040-14-R-0-2021

vintagestringOptional

The vintage year of the carbon credits associated with the retirement

Example: 2020

amountnumberRequired

The amount of the retirement

Example: 1000

post

/retirements/finalize

HTTPcURLJavaScriptPython

POST /retirements/finalize HTTP/1.1
Host: api.carbonregistry.com
Content-Type: application/json
Accept: */*
Content-Length: 398

{
  "signer": "0xA0022c05501007281acAE55B94AdE4Fc3dd59ec3",
  "signature": "0xf76145d74ff1a3e70ca51e44063b6a90cf5e5d82e11941d3691e9dee197d124f748b6fcd8d3ecc7a45e08fe698be6f9e24685b5d8e270612e727380ede19c3321c",
  "signedData": {
    "comment": "This retirement is for a sustainability project.",
    "reason": "Corsia",
    "tokenId": "47",
    "projectAddress": "0x49a88d0dd5f316556794877940d515d1a9b2c3c3",
    "beneficiary": "Jane Doe"
  }
}

200Success

{
  "createdAt": "2026-02-24T21:20:51.735Z",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "isClaimed": true,
  "reason": "Reached retirement age",
  "comment": "Congratulations on your retirement!",
  "beneficiary": "John Doe",
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "organizationOwner": {
    "total": 100,
    "currentPage": 1,
    "pageCount": 10,
    "nextPage": 2,
    "prevPage": 0
  },
  "serialization": "ICR-ISL-354-78040-14-R-0-2021",
  "vintage": "2020",
  "amount": 1000,
  "project": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "fullName": "Project 1",
    "url": "https://api.carbonregistry.com/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
    "publicUrl": "https://carbonregistry.com/explore/projects/47abd663-fb35-4b2e-ad08-c347e761649e",
    "num": "713"
  }
}