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

Request Body

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_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)

200: OK Returns the id of the retirement request that the credits have been added to

Example

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

Schema

{
    retirement_request_id: string
    external_id_already_processed: boolean
}

401: Unauthorized Your API key is unrecognized or inactive

Example

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

Schema

{
    statusCode: number
    message: string
}

403: User does not have `API User` role.

Example

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

Schema

{
    statusCode: number
    message: string
    error: string
}

422: Unprocessable Entity There was a problem processing the request

Example

{
    "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"
}

Schema

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

500: Server error An unexpected error has occurred on the server.

Example

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

Schema

{
    statusCode: number
    message: string
}

422: Unprocessable Entity error types

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

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:

1. 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"
}

1. 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.

2. The purchase is added to your monthly invoice and the credit is added to your CaaS inventory.

3. 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.

4. The retirement request id for this vintage for this month is returned.

5. 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"
}

1. 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.

2. 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.