Retirement

Get retirement data by id

After calling the Request Retirement 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

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

POST /api/retirement

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

Query Parameters

Name	Type	Description
id*	string	The id of the retirement request you want information about.

Headers

Name	Type	Description
Authorization*	string	Bearer API_KEY

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.

Example Retirement Response

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

Schema

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

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

Example retirement not found

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

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
}

200: status Values

Status	Description
OPEN	means that more credits can be added to this retirement request (this is only applicable for retirements where the `type` is `FRACTIONALISED`)
CLOSED	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 IN_PROGRESS. This is not an end state.
IN_PROGRESS	means that the retirement is being processed on the underlying registry and more credits cannot be added to this retirement request.
COMPLETE	means that the retirement has been processed on the underlying registry and details such as retired_at, retired_serials, thallo_proof_of_retirement_certificate_url will be available.
NOTHING_TO_PROCESS	means that the retirement request will not be processed as it has been closed and the total_quantity is 0. This happens in the unlikely event a retirement with a type of FRACTIONALISED contained less than 1 whole tonne.

422: Unprocessable Entity error types

`error`	Description
VALIDATION_ERROR	One or more validation rules has failed. e.g. id must be a string
NOT_FOUND	Retirement request not found with id 00mj6hrvi6yaapj6nh