# Request Retirement {% hint style="success" %} Thallo removes the necessity for you to manually manage your carbon credit inventory, the Thallo system will take care of this for you. {% endhint %} {% hint style="danger" %} 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. {% endhint %} {% hint style="warning" %} Retirement requests cannot be undone. {% endhint %} ## Example cURL Request ```sh 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](/api-endpoints/market.md) endpoint to ensure the price on the sell order has not changed since you read the data from the [Market](/api-endpoints/market.md). | | 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]\() 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) | {% tabs %} {% tab title="200: OK Returns the id of the retirement request that the credits have been added to" %} {% tabs %} {% tab title="Example" %} ```json { "retirement_request_id": "00mesxcknwjtz05lez", "external_id_already_processed": false } ``` {% endtab %} {% tab title="Schema" %} ```typescript { retirement_request_id: string external_id_already_processed: boolean } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="401: Unauthorized Your API key is unrecognized or inactive" %} {% tabs %} {% tab title="Example" %} ```json { "statusCode": 401, "message": "Unauthorized" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="403: User does not have `API User` role." %} {% tabs %} {% tab title="Example" %} ```json { "error": "Forbidden", "message": "Permission denied according to assigned roles.", "statusCode": 403 } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string error: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="422: Unprocessable Entity There was a problem processing the request" %} {% tabs %} {% tab title="Example" %} ```json { "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" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number timestamp: string url: string error: string message: string | string[] } ``` {% endtab %} {% endtabs %} {% endtab %} {% tab title="500: Server error An unexpected error has occurred on the server." %} {% tabs %} {% tab title="Example" %} ```json { "statusCode": 500, "message": "Internal server error" } ``` {% endtab %} {% tab title="Schema" %} ```typescript { statusCode: number message: string } ``` {% endtab %} {% endtabs %} {% endtab %} {% endtabs %} ### 422: Unprocessable Entity `error` types
Value from APIDescription
FRAC_QUANT_INVALID_NUMBERquantity_grams is not a valid number
FRAC_QUANT_LESS_THAN_EQ_ZEROquantity_grams must be greater than zero
SELL_ORDER_MISSING_EXP_PRICEIf sell_order_id is provided you must provide expected_price_cents
SELL_ORDER_EXP_PRICE_INVALID_NUMBERexpected_price_cents is not a valid number
SELL_ORDER_EXP_PRICE_LESS_THAN_EQ_ZEROexpected_price_cents must be greater than zero
VINTAGE_ID_NOT_EXISTSvintage_id not found
MISSING_SELL_ORDER_IDNot 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_PRICEexpected_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_EXISTSsell_order_id does not exist
SELL_ORDER_NOT_LIVEsell_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_LOWsell_order_id does not contain enough credits
VINTAGE_SUPPLIED_DIFF_SELL_ORDER_VINTAGEThe vintage_id does not match the vintage on the specified sell_order_id
PURCHASE_OWN_CREDITSThe sell_order_id relates to a sell order that you own. You cannot buy credits that you already own.
MISSING_RETIREE_IDThe external_retiree_id Should be supplied when should_retire_external_customer is set to true
MISSING_RETIREE_DETAILSThe 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: ```typescript { 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: ```json { "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" } ``` 2. 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`. 3. The purchase is added to your monthly invoice and the credit is added to your CaaS inventory. 4. 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. 5. The retirement request id for this vintage for this month is returned. 6. You make a new retirement request for the same vintage: ```json { "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" } ``` 7. 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. 8. `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](/api-endpoints/market.md) 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](https://docs.thallo.io/) 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.market.thallo.io/api-endpoints/caas/requestretirement.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.