# Retirement

After calling the [Request Retirement](https://docs.market.thallo.io/api-endpoints/caas/requestretirement) 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>