# Retirement

After calling the [Request Retirement](/api-endpoints/caas/requestretirement.md) endpoint the response will contain a `retirement_request_id` which you can use in this endpoint to get access to the retirement data including status, the retirement certificate etc.

## Example cURL Request

```sh
curl --request GET 'https://${BASE_URL}/api/retirement?id=00mj6hrvi6yaapj6nb' \
--header 'Authorization: Bearer ${API_KEY}'
```

## Endpoint Specification

## Get the retirement request for a specific id

<mark style="color:green;">`POST`</mark> `/api/retirement`

See the status and other information about a specific retirement request.

#### Query Parameters

| Name                                 | Type   | Description                                                  |
| ------------------------------------ | ------ | ------------------------------------------------------------ |
| id<mark style="color:red;">\*</mark> | string | The id of the retirement request you want information about. |

#### Headers

| Name                                            | Type   | Description     |
| ----------------------------------------------- | ------ | --------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer API\_KEY |

{% tabs %}
{% tab title="200: OK Returns the information relating to the retirement request if it exists" %}
`total_quantity` is the quantity of the retirement request in grams.

`retirement_request_items.quantity` is the quantity requested in an individual call to POST `api/caas/request-retirement` in grams.

There are 2 types of retirement request: `FRACTIONALISED` and `WHOLE`. For any requests made through the `api/caas/request-retirement` endpoint where the quantity is not whole tonnes, this type will be `FRACTIONALISED`.

The `status` can have one of the following values:

`OPEN` | `CLOSED` | `IN_PROGRESS` | `COMPLETE` | `NOTHING_TO_PROCESS`

See below for more information on `status`.

If the `id` supplied in the request does not match one of your retirement requests, the endpoint will throw a `422` error.

{% tabs %}
{% tab title="Example Retirement Response" %}

```json
{
    "id": "00mj6hrvi6yaapj6nb",
    "status": "COMPLETE",
    "total_quantity": "10000000",
    "type": "WHOLE",
    "project_id": "003tcfgf70xwtr1dbc",
    "vintage_id": "004o7rnsz29fptz9uo",
    "created_at": "2024-02-05T10:51:12.319Z",
    "retired_at": "2024-02-08T11:46:48.245Z",
    "retired_serial_numbers": ["123456789", "abc123456"],
    "thallo_proof_of_retirement_certificate_url": "https://example.com/certificate.png",
    "should_retire_external_customer": true,
    "all_invoices_settled": true,
    "retirement_request_items": [
        {
            "id": "00p6y5rap05wpwt7km",
            "quantity": "10000000",
            "created_at": "2024-02-05T10:51:12.319Z",
            "retiree_name": "Your Customer Ltd",
            "retiree_tax_id": "123456789",
            "retiree_country": "GB",
            "invoice_id": "00iy2jbppp8kwwg7vl",
            "trade_id": "00gr2tgn2wbq8barqs"
        }
    ]
}
```

{% endtab %}

{% tab title="Schema" %}

```typescript
Object<{
    id: string
    status: 'OPEN' | 'CLOSED' | 'IN_PROGRESS' | 'COMPLETE' | 'NOTHING_TO_PROCESS'
    total_quantity: string
    type: 'FRACTIONALISED' | 'WHOLE'
    project_id: string
    vintage_id: string
    created_at: string
    retired_at: string | undefined
    retired_serial_numbers: string[] | undefined
    thallo_proof_of_retirement_certificate_url: string | undefined
    should_retire_external_customer: boolean
    all_invoices_settled: boolean
    retirement_request_items: Array<{
        id: string
        quantity: string
        created_at: string
        retiree_name: string | undefined
        retiree_tax_id: string | undefined
        retiree_country: Locations | undefined
        invoice_id: string | undefined
        trade_id: string | undefined
    }>
}>
```

{% 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/retirement",
    "error": "VALIDATION_ERROR",
    "message": ["id must be a string", "id should not be empty"]
}
```

{% endtab %}

{% tab title="Example retirement not found" %}

```json
{
    "statusCode": 422,
    "timestamp": "2023-06-11T09:23:27.078Z",
    "url": "/api/retirement",
    "error": "NOT_FOUND",
    "message": "Retirement request not found with id 00mj6hrvi6yaapj6nh"
}
```

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

### 200: `status` Values

<table><thead><tr><th width="220">Status</th><th>Description</th></tr></thead><tbody><tr><td><code>OPEN</code></td><td>means that more credits can be added to this retirement request (this is only applicable for retirements where the `type` is `FRACTIONALISED`)</td></tr><tr><td><code>CLOSED</code></td><td>means that no additional credits can be added to this retirement request and it is pending settlement of one or more invoices before being set to <code>IN_PROGRESS</code>. This is not an end state.</td></tr><tr><td><code>IN_PROGRESS</code></td><td>means that the retirement is being processed on the underlying registry and more credits cannot be added to this retirement request.</td></tr><tr><td><code>COMPLETE</code></td><td>means that the retirement has been processed on the underlying registry and details such as <code>retired_at</code>, <code>retired_serials</code>, <code>thallo_proof_of_retirement_certificate_url</code> will be available.</td></tr><tr><td><code>NOTHING_TO_PROCESS</code></td><td>means that the retirement request will not be processed as it has been closed and the <code>total_quantity</code> is <code>0</code>. This happens in the unlikely event a retirement with a <code>type</code> of <code>FRACTIONALISED</code> contained less than 1 whole tonne.</td></tr></tbody></table>

### 422: Unprocessable Entity `error` types

<table><thead><tr><th width="200">`error`</th><th>Description</th></tr></thead><tbody><tr><td><code>VALIDATION_ERROR</code></td><td>One or more validation rules has failed. e.g. <code>id</code> must be a string</td></tr><tr><td><code>NOT_FOUND</code></td><td>Retirement request not found with id 00mj6hrvi6yaapj6nh</td></tr></tbody></table>


---

# 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/retirement.md?ask=<question>
```

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.