Request Retirement

Retire credits by the gram and automatically top-up inventory if required

Thallo removes the necessity for you to manually manage your carbon credit inventory, the Thallo system will take care of this for you.

Calling this endpoint with a sell_order_id can cause carbon credits to be purchased from the market. These purchases are final and will be added to your monthly invoice. Use caution when building your logic and ensure accidental purchases cannot happen.

Retirement requests cannot be undone.

Example cURL Request

curl --request POST 'https://${BASE_URL}/api/caas/request-retirement' \
--header 'Authorization: Bearer ${API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "quantity_grams": "20",
  "vintage_id": "004l7azww8l14bnxio",
  "sell_order_id": "006qhwycj9iruixah7",
  "expected_price_cents": "1023",
  "external_id": "a114f6ba-d7e4-40ad-aae2-8630bc2a7379",
  "should_retire_external_customer": true,
  "external_retiree_id": "7eece928-5a7a-4591-800a-4859635e4037",
  "external_retiree_name": "Alice Bob",
  "external_retiree_tax_id": "AB123456D",
  "external_retiree_location": "GB"
}'

Endpoint Specification

Retire credits by the gram and automatically top-up inventory if required

POST /api/caas/request-retirement

Earmark credits for retirement by the gram. Optionally include a sell_order_id and Thallo will automatically purchase the minimum amount of credits required to fulfil the retirement request, rounded up to the nearest whole tonne.

Headers

Name	Type	Description
Authorization*	string	Bearer API_KEY
Content-Type*	string	application/json

Name

Type

Description

Authorization*

string

Bearer API_KEY

Content-Type*

string

application/json

Request Body

Name Type Description

Name	Type	Description
vintage_id*	string	The vintage you would like to retire from. Vintages relate to a single project and so Thallo are able to determine the project you wish to retire from by the `vintage_id` alone. If there are adequate credits for this `vintage_id` in your CaaS inventory these credits will be used first. You can omit the `sell_order_id` and `expected_price_cents` parameters as they will be ignored because no purchase is required.
quantity_grams*	string	The amount of credits, in grams, that you'd like to retire.
external_id*	string	This value must be unique for every request. If a 200 is returned and param `external_id_already_processed` in response body is `false` the value specified in this field in request body can never be used again. This stops accidentally replaying the request multiple times. If the same value is used after a successful request has been sent, Thallo will return the retirement request id the original request was associated to, the `external_id_already_processed` property will be set to `true` so you are aware that no new purchase or retirement was created on this request - it was already processed on a previous request with the same `external_id`.
sell_order_id	string	Use the `sell_order_id`s from the Market endpoint to indicate which sell order to purchase from, if there are not enough credits in your inventory to fulfil the requirement request. The vintage the sell order relates to must match the `vintage_id` supplied in this request. WARNING: supplying this parameter can cause carbon credits to be purchased from the market. These purchases are final and will be added to your monthly invoice. Thallo will only purchase the minimum amount of credits required to fulfil the retirement request rounded up to a whole tonne.
expected_price_cents	string	This is an anti-slippage mechanism. Supply the price retrieved from the Market endpoint to ensure the price on the sell order has not changed since you read the data from the Market.
should_retire_external_customer	boolean	This indicates whether you want this retirement request to be made under your customer's name. If setting this to true, the `quantity_grams` must be a multiple of 1,000,000 (i.e. whole tonnes) and the following parameters must be supplied: `external_retiree_id`, `external_retiree_name`,`external_retiree_tax_id`, `external_retiree_location`. When `false`, you can still supply the external retiree details and they will be displayed in the CaaS Dashboard](https://market.thallo.io/dashboard) to indicate which of your users were included in which retirement request. if `true`, there will be an individual retirement request on the CaaS Dashboard for that specific request.
external_retiree_id	string	The identifier of the retiree in your internal systems. This may be used in future Thallo features to allow analytics to run against your retirement request calls. This will allow grouping by the `external_retiree_id` to give insight into how your individual customers are utilising the Thallo integration. If you do not wish to utilize this feature, you can set this to a non-blank string such as 'none'.
external_retiree_name	string	This is the name of your customer that will appear on the retirement certificate when `should_retire_external_customer` is set to `true`
external_retiree_tax_id	string	This is the Tax ID of your customer that is used during retirement
external_retiree_location	string	This is the ISO 3166-1 alpha-2 country codes (2 character country codes)

vintage_id*

string

The vintage you would like to retire from. Vintages relate to a single project and so Thallo are able to determine the project you wish to retire from by the vintage_id alone. If there are adequate credits for this vintage_id in your CaaS inventory these credits will be used first. You can omit the sell_order_id and expected_price_cents parameters as they will be ignored because no purchase is required.

quantity_grams*

string

The amount of credits, in grams, that you'd like to retire.

external_id*

string

This value must be unique for every request. If a 200 is returned and param external_id_already_processed in response body is false the value specified in this field in request body can never be used again. This stops accidentally replaying the request multiple times. If the same value is used after a successful request has been sent, Thallo will return the retirement request id the original request was associated to, the external_id_already_processed property will be set to true so you are aware that no new purchase or retirement was created on this request - it was already processed on a previous request with the same external_id.

sell_order_id

string

Use the sell_order_ids from the Market endpoint to indicate which sell order to purchase from, if there are not enough credits in your inventory to fulfil the requirement request. The vintage the sell order relates to must match the vintage_id supplied in this request. WARNING: supplying this parameter can cause carbon credits to be purchased from the market. These purchases are final and will be added to your monthly invoice. Thallo will only purchase the minimum amount of credits required to fulfil the retirement request rounded up to a whole tonne.

expected_price_cents

string

This is an anti-slippage mechanism. Supply the price retrieved from the Market endpoint to ensure the price on the sell order has not changed since you read the data from the Market.

should_retire_external_customer

boolean

This indicates whether you want this retirement request to be made under your customer's name. If setting this to true, the quantity_grams must be a multiple of 1,000,000 (i.e. whole tonnes) and the following parameters must be supplied: external_retiree_id, external_retiree_name,external_retiree_tax_id, external_retiree_location. When false, you can still supply the external retiree details and they will be displayed in the CaaS Dashboard](https://market.thallo.io/dashboard) to indicate which of your users were included in which retirement request. if true, there will be an individual retirement request on the CaaS Dashboard for that specific request.

external_retiree_id

string

The identifier of the retiree in your internal systems. This may be used in future Thallo features to allow analytics to run against your retirement request calls. This will allow grouping by the external_retiree_id to give insight into how your individual customers are utilising the Thallo integration. If you do not wish to utilize this feature, you can set this to a non-blank string such as 'none'.

external_retiree_name

string

This is the name of your customer that will appear on the retirement certificate when should_retire_external_customer is set to true

external_retiree_tax_id

string

This is the Tax ID of your customer that is used during retirement

external_retiree_location

string

This is the ISO 3166-1 alpha-2 country codes (2 character country codes)

{
    "retirement_request_id": "00mesxcknwjtz05lez",
    "external_id_already_processed": false
}

{
    retirement_request_id: string
    external_id_already_processed: boolean
}

{
    "statusCode": 401,
    "message": "Unauthorized"
}

{
    statusCode: number
    message: string
}

{
    "error": "Forbidden",
    "message": "Permission denied according to assigned roles.",
    "statusCode": 403
}

{
    statusCode: number
    message: string
    error: string
}

{
    "statusCode": 422,
    "timestamp": "2023-06-11T09:23:27.078Z",
    "url": "/api/caas/request-retirement",
    "error": "FRAC_QUANT_INVALID_NUMBER",
    "message": "quantity_grams value \"abc\" is not a valid number"
}

{
    statusCode: number
    timestamp: string
    url: string
    error: string
    message: string | string[]
}

{
    "statusCode": 500,
    "message": "Internal server error"
}

{
    statusCode: number
    message: string
}

422: Unprocessable Entity `error` types

Value from API Description

Value from API	Description
`FRAC_QUANT_INVALID_NUMBER`	`quantity_grams` is not a valid number
`FRAC_QUANT_LESS_THAN_EQ_ZERO`	`quantity_grams` must be greater than zero
`SELL_ORDER_MISSING_EXP_PRICE`	If `sell_order_id` is provided you must provide `expected_price_cents`
`SELL_ORDER_EXP_PRICE_INVALID_NUMBER`	`expected_price_cents` is not a valid number
`SELL_ORDER_EXP_PRICE_LESS_THAN_EQ_ZERO`	`expected_price_cents` must be greater than zero
`VINTAGE_ID_NOT_EXISTS`	`vintage_id` not found
`MISSING_SELL_ORDER_ID`	Not enough credits in inventory and `sell_order_id` was not specified so we are unable to purchase more. Please specify a `sell_order_id` to purchase from.
`PRICE_SUPPLIED_DIFF_CURRENT_PRICE`	`expected_price_cents` does not match the price on the `sell_order_id`. The price may have changed since the market data was last read. Please re-read the market data to get the up to date price for this sell order.
`SELL_ORDER_NOT_EXISTS`	`sell_order_id` does not exist
`SELL_ORDER_NOT_LIVE`	`sell_order_id` is no longer live. There are no credits remaining in this sell order or the sell order has been cancelled.
`SELL_ORDER_SUPPLY_TOO_LOW`	`sell_order_id` does not contain enough credits
`VINTAGE_SUPPLIED_DIFF_SELL_ORDER_VINTAGE`	The `vintage_id` does not match the vintage on the specified `sell_order_id`
`PURCHASE_OWN_CREDITS`	The `sell_order_id` relates to a sell order that you own. You cannot buy credits that you already own.
`MISSING_RETIREE_ID`	The `external_retiree_id` Should be supplied when `should_retire_external_customer` is set to true
`MISSING_RETIREE_DETAILS`	The `external_retiree_id`, `external_retiree_name`, `external_retiree_tax_id`, `external_retiree_location` should all be either defined or undefined when `should_retire_external_customer` is `false`. If `should_retire_external_customer` is `true`, all of these values should be defined

FRAC_QUANT_INVALID_NUMBER

quantity_grams is not a valid number

FRAC_QUANT_LESS_THAN_EQ_ZERO

quantity_grams must be greater than zero

SELL_ORDER_MISSING_EXP_PRICE

If sell_order_id is provided you must provide expected_price_cents

SELL_ORDER_EXP_PRICE_INVALID_NUMBER

expected_price_cents is not a valid number

SELL_ORDER_EXP_PRICE_LESS_THAN_EQ_ZERO

expected_price_cents must be greater than zero

VINTAGE_ID_NOT_EXISTS

vintage_id not found

MISSING_SELL_ORDER_ID

Not enough credits in inventory and sell_order_id was not specified so we are unable to purchase more. Please specify a sell_order_id to purchase from.

PRICE_SUPPLIED_DIFF_CURRENT_PRICE

expected_price_cents does not match the price on the sell_order_id. The price may have changed since the market data was last read. Please re-read the market data to get the up to date price for this sell order.

SELL_ORDER_NOT_EXISTS

sell_order_id does not exist

SELL_ORDER_NOT_LIVE

sell_order_id is no longer live. There are no credits remaining in this sell order or the sell order has been cancelled.

SELL_ORDER_SUPPLY_TOO_LOW

sell_order_id does not contain enough credits

VINTAGE_SUPPLIED_DIFF_SELL_ORDER_VINTAGE

The vintage_id does not match the vintage on the specified sell_order_id

PURCHASE_OWN_CREDITS

The sell_order_id relates to a sell order that you own. You cannot buy credits that you already own.

MISSING_RETIREE_ID

The external_retiree_id Should be supplied when should_retire_external_customer is set to true

MISSING_RETIREE_DETAILS

The external_retiree_id, external_retiree_name, external_retiree_tax_id, external_retiree_location should all be either defined or undefined when should_retire_external_customer is false. If should_retire_external_customer is true, all of these values should be defined

Location Codes:

{
    ALAND_ISLANDS = 'AX',
    ALBANIA = 'AL',
    ALGERIA = 'DZ',
    AMERICAN_SAMOA = 'AS',
    ANDORRA = 'AD',
    ANGOLA = 'AO',
    AFGHANISTAN = 'AF',
    ANGUILLA = 'AI',
    ANTARCTICA = 'AQ',
    ANTIGUA_AND_BARBUDA = 'AG',
    ARGENTINA = 'AR',
    ARMENIA = 'AM',
    ARUBA = 'AW',
    AUSTRALIA = 'AU',
    AUSTRIA = 'AT',
    AZERBAIJAN = 'AZ',
    BAHRAIN = 'BH',
    BAHAMAS = 'BS',
    BANGLADESH = 'BD',
    BARBADOS = 'BB',
    BELARUS = 'BY',
    BELGIUM = 'BE',
    BELIZE = 'BZ',
    BENIN = 'BJ',
    BERMUDA = 'BM',
    BHUTAN = 'BT',
    BOLIVIA = 'BO',
    BONAIRE = 'BQ',
    BOSNIA_AND_HERZEGOVINA = 'BA',
    BOTSWANA = 'BW',
    BOUVET_ISLAND = 'BV',
    BRAZIL = 'BR',
    BRITISH_INDIAN_OCEAN_TERRITORY = 'IO',
    BRUNEI_DARUSSALAM = 'BN',
    BULGARIA = 'BG',
    BURKINA_FASO = 'BF',
    BURUNDI = 'BI',
    CAMBODIA = 'KH',
    CAMEROON = 'CM',
    CANADA = 'CA',
    CAPE_VERDE = 'CV',
    CAYMAN_ISLANDS = 'KY',
    CENTRAL_AFRICAN_REPUBLIC = 'CF',
    CHAD = 'TD',
    CHILE = 'CL',
    CHINA = 'CN',
    CHRISTMAS_ISLAND = 'CX',
    COCOS_ISLANDS = 'CC',
    COLOMBIA = 'CO',
    COMOROS = 'KM',
    CONGO = 'CG',
    DEMOCRATIC_REPUBLIC_OF_CONGO = 'CD',
    COOK_ISLANDS = 'CK',
    COSTA_RICA = 'CR',
    IVORY_COAST = 'CI',
    CROATIA = 'HR',
    CUBA = 'CU',
    CURACAO = 'CW',
    CYPRUS = 'CY',
    CZECH_REPUBLIC = 'CZ',
    DENMARK = 'DK',
    DJIBOUTI = 'DJ',
    DOMINICA = 'DM',
    DOMINICAN_REPUBLIC = 'DO',
    ECUADOR = 'EC',
    EGYPT = 'EG',
    EL_SALVADOR = 'SV',
    EQUATORIAL_GUINEA = 'GQ',
    ERITREA = 'ER',
    ESTONIA = 'EE',
    ETHIOPIA = 'ET',
    FALKLAND_ISLANDS = 'FK',
    FAROE_ISLANDS = 'FO',
    FIJI = 'FJ',
    FINLAND = 'FI',
    FRANCE = 'FR',
    FRENCH_GUIANA = 'GF',
    FRENCH_POLYNESIA = 'PF',
    FRENCH_SOUTHERN_TERRITORIES = 'TF',
    GABON = 'GA',
    GAMBIA = 'GM',
    GEORGIA = 'GE',
    GERMANY = 'DE',
    GHANA = 'GH',
    GIBRALTAR = 'GI',
    GREECE = 'GR',
    GREENLAND = 'GL',
    GRENADA = 'GD',
    GUADELOUPE = 'GP',
    GUAM = 'GU',
    GUATEMALA = 'GT',
    GUERNSEY = 'GG',
    GUINEA = 'GN',
    GUINEA_BISSAU = 'GW',
    GUYANA = 'GY',
    HAITI = 'HT',
    HEARD_ISLAND_AND_MCDONALD_ISLANDS = 'HM',
    HOLY_SEE = 'VA',
    HONDURAS = 'HN',
    HONG_KONG = 'HK',
    HUNGARY = 'HU',
    ICELAND = 'IS',
    INDIA = 'IN',
    INDONESIA = 'ID',
    IRAN = 'IR',
    IRAQ = 'IQ',
    IRELAND = 'IE',
    ISLE_OF_MAN = 'IM',
    ISRAEL = 'IL',
    ITALY = 'IT',
    JAMAICA = 'JM',
    JAPAN = 'JP',
    JERSEY = 'JE',
    JORDAN = 'JO',
    KAZAKHSTAN = 'KZ',
    KENYA = 'KE',
    KIRIBATI = 'KI',
    NORTH_KOREA = 'KP',
    SOUTH_KOREA = 'KR',
    KUWAIT = 'KW',
    KYRGYZSTAN = 'KG',
    LAO_PEOPLES_DEMOCRATIC_REPUBLIC = 'LA',
    LATVIA = 'LV',
    LEBANON = 'LB',
    LESOTHO = 'LS',
    LIBERIA = 'LR',
    LIBYA = 'LY',
    LIECHTENSTEIN = 'LI',
    LITHUANIA = 'LT',
    LUXEMBOURG = 'LU',
    MACAO = 'MO',
    MACEDONIA = 'MK',
    MADAGASCAR = 'MG',
    MALAWI = 'MW',
    MALAYSIA = 'MY',
    MALDIVES = 'MV',
    MALI = 'ML',
    MALTA = 'MT',
    MARSHALL_ISLANDS = 'MH',
    MARTINIQUE = 'MQ',
    MAURITANIA = 'MR',
    MAURITIUS = 'MU',
    MAYOTTE = 'YT',
    MEXICO = 'MX',
    MICRONESIA = 'FM',
    MOLDOVA = 'MD',
    MONACO = 'MC',
    MONGOLIA = 'MN',
    MONTENEGRO = 'ME',
    MONTSERRAT = 'MS',
    MOROCCO = 'MA',
    MOZAMBIQUE = 'MZ',
    MYANMAR = 'MM',
    NAMIBIA = 'NA',
    NAURU = 'NR',
    NEPAL = 'NP',
    NETHERLANDS = 'NL',
    NEW_CALEDONIA = 'NC',
    NEW_ZEALAND = 'NZ',
    NICARAGUA = 'NI',
    NIGER = 'NE',
    NIGERIA = 'NG',
    NIUE = 'NU',
    NORFOLK_ISLAND = 'NF',
    NORTHERN_MARIANA_ISLANDS = 'MP',
    NORWAY = 'NO',
    OMAN = 'OM',
    PAKISTAN = 'PK',
    PALAU = 'PW',
    PALESTINE = 'PS',
    PANAMA = 'PA',
    PAPUA_NEW_GUINEA = 'PG',
    PARAGUAY = 'PY',
    PERU = 'PE',
    PHILIPPINES = 'PH',
    PITCAIRN = 'PN',
    POLAND = 'PL',
    PORTUGAL = 'PT',
    PUERTO_RICO = 'PR',
    QATAR = 'QA',
    RÉUNION = 'RE',
    ROMANIA = 'RO',
    RUSSIAN_FEDERATION = 'RU',
    RWANDA = 'RW',
    SAINT_BARTHÉLEMY = 'BL',
    SAINT_HELENA = 'SH',
    SAINT_KITTS_AND_NEVIS = 'KN',
    SAINT_LUCIA = 'LC',
    SAINT_MARTIN = 'MF',
    SAINT_PIERRE_AND_MIQUELON = 'PM',
    SAINT_VINCENT_AND_THE_GRENADINES = 'VC',
    SAMOA = 'WS',
    SAN_MARINO = 'SM',
    SAO_TOME_AND_PRINCIPE = 'ST',
    SAUDI_ARABIA = 'SA',
    SENEGAL = 'SN',
    SERBIA = 'RS',
    SEYCHELLES = 'SC',
    SIERRA_LEONE = 'SL',
    SINGAPORE = 'SG',
    SINT_MAARTEN = 'SX',
    SLOVAKIA = 'SK',
    SLOVENIA = 'SI',
    SOLOMON_ISLANDS = 'SB',
    SOMALIA = 'SO',
    SOUTH_AFRICA = 'ZA',
    SOUTH_GEORGIA_AND_THE_SOUTH_SANDWICH_ISLANDS = 'GS',
    SOUTH_SUDAN = 'SS',
    SPAIN = 'ES',
    SRI_LANKA = 'LK',
    SUDAN = 'SD',
    SURINAME = 'SR',
    SVALBARD_AND_JAN_MAYEN = 'SJ',
    SWAZILAND = 'SZ',
    SWEDEN = 'SE',
    SWITZERLAND = 'CH',
    SYRIAN_ARAB_REPUBLIC = 'SY',
    TAIWAN = 'TW',
    TAJIKISTAN = 'TJ',
    TANZANIA = 'TZ',
    THAILAND = 'TH',
    TIMOR_LESTE = 'TL',
    TOGO = 'TG',
    TOKELAU = 'TK',
    TONGA = 'TO',
    TRINIDAD_AND_TOBAGO = 'TT',
    TUNISIA = 'TN',
    TURKEY = 'TR',
    TURKMENISTAN = 'TM',
    TURKS_AND_CAICOS_ISLANDS = 'TC',
    TUVALU = 'TV',
    UGANDA = 'UG',
    UKRAINE = 'UA',
    UNITED_ARAB_EMIRATES = 'AE',
    UNITED_KINGDOM = 'GB',
    UNITED_STATES = 'US',
    UNITED_STATES_MINOR_OUTLYING_ISLANDS = 'UM',
    URUGUAY = 'UY',
    UZBEKISTAN = 'UZ',
    VANUATU = 'VU',
    VENEZUELA = 'VE',
    VIET_NAM = 'VN',
    BRITISH_VIRGIN_ISLANDS = 'VG',
    U_S_VIRGIN_ISLANDS = 'VI',
    WALLIS_AND_FUTUNA = 'WF',
    WESTERN_SAHARA = 'EH',
    YEMEN = 'YE',
    ZAMBIA = 'ZM',
    ZIMBABWE = 'ZW',
}

Purchases

Thallo will purchase carbon credits from the specified sell_order_id when there are not enough credits remaining in your CaaS carbon credit inventory for the specified vintage_id.

This removes the necessity for you to manually manage your inventory, the Thallo system will take care of this for you.

This is an example flow of 2 retirement requests made against the same vintage_id:

Retirement request made with the following parameters:

{
    "quantity_grams": "20",
    "vintage_id": "004l7azww8l14bnxio",
    "sell_order_id": "006qhwycj9iruixah7",
    "expected_price_cents": "1023",
    "external_retiree_id": "7eece928-5a7a-4591-800a-4859635e4037",
    "external_id": "f9ff1e64-d578-4370-ae6b-e1e484b7108d"
}

You currently have zero credits for the project/vintage in your CaaS inventory and so Thallo will purchase one whole tonne from the specified sell_order_id.
The purchase is added to your monthly invoice and the credit is added to your CaaS inventory.
Now you have 1,000,000 grams for this vintage (1 tonne); 20 grams are added to your retirement request for this vintage for this month. Leaving you with 999,980 grams that can be used in future retirement requests for this vintage.
The retirement request id for this vintage for this month is returned.
You make a new retirement request for the same vintage:

{
    "quantity_grams": "42",
    "vintage_id": "004l7azww8l14bnxio",
    "sell_order_id": "006qhwycj9iruixah7",
    "expected_price_cents": "1023",
    "external_retiree_id": "7eece928-5a7a-4591-800a-4859635e4037",
    "external_id": "70b1443e-ce32-45e1-b0a3-4f1981921812"
}

You currently have 999,980 grams in your Caas inventory for this vintage - enough to fulfil the retirement request so no purchase is required. The sell_order_id and expected_price_cents are effectively ignored.
42 grams are added to your retirement request for this vintage for this month. Leaving you with 999,938 grams that can be used in future retirement requests for this vintage.

Anti Slippage

It is possible that the price on the sell order changes between you reading the data from the Market and making the retirement request. By supplying the expected price this ensures you will pay the price you expect to pay for the credits. An error will be thrown if the expected price and the price on the sell order do not match.

Invoicing

All purchases are final and will be added to your monthly invoice.

Processing Retirement Requests

Retirement requests are processed once the invoice is settled for a given month. The retirements will then be processed by the Thallo Two-Way Bridge so the retirement is reflected on the blockchain as well as the underlying registry.

Due to limitations on the underlying registries, retirements can only be processed on whole tonnes. Any remaining grams will be rolled over to next month's retirement request for this project/vintage.

PreviousCarbon-as-a-Service NextInventory

Last updated 22 days ago

Example cURL Request

Endpoint Specification

Retire credits by the gram and automatically top-up inventory if required

Headers

Request Body

422: Unprocessable Entity error types

Location Codes:

Purchases

Anti Slippage

Invoicing

Processing Retirement Requests

422: Unprocessable Entity `error` types