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

HTTPcURLJavaScriptPython

GET /retirements/list HTTP/1.1
Host: api.carbonregistry.com
Accept: */*

200Success

{
  "retirements": [
    {
      "createdAt": "2025-06-19T15:05:09.265Z",
      "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

get

HTTPcURLJavaScriptPython

GET /retirements HTTP/1.1
Host: api.carbonregistry.com
Accept: */*

200Success

{
  "createdAt": "2025-06-19T15:05:09.265Z",
  "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

HTTPcURLJavaScriptPython

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

200

File content

No 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

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

signedDataall ofRequired

The signed retirement data object.

Responses

200Success

application/json

post

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": "2025-06-19T15:05:09.265Z",
  "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"
  }
}