HomeProjectsCreditsTransactionsInsights

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
GET /retirements/list HTTP/1.1
Host: api.carbonregistry.com
Accept: */*
200Success
{
  "retirements": [
    {
      "createdAt": "2025-07-24T11:12:53.063Z",
      "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 -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'

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
GET /retirements HTTP/1.1
Host: api.carbonregistry.com
Accept: */*
200Success
{
  "createdAt": "2025-07-24T11:12:53.063Z",
  "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
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
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-07-24T11:12:53.063Z",
  "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"
  }
}

PreviousProjectsNextWarehouse

Last updated