---
title: "Create Retirement From Oldest Credits"
method: POST
path: "/retirements/from_oldest_credits"
---

# Create Retirement From Oldest Credits

`POST /retirements/from_oldest_credits`

## Request

- Base URL: `https://api.isometric.com/registry/v0`
- URL: `https://api.isometric.com/registry/v0/retirements/from_oldest_credits`
- Auth: HTTP bearer

Retire oldest available credits from a given supplier. If vintage is specified, this will retire the oldest credits from that vintage only.

## Headers

- `x-client-secret` string, required: A secret token identifying the client connecting to the API

## Request body

- CreateRetirementOldestCreditsRequest
  - `owner_organisation_id` string, required: The ID of the organisation owns the credits to be retired. Typically this would be your own organisation ID.
  - `beneficiary_organisation_id` string, required: The ID of the organisation that the credits will be retired in the name of, this can be the same as `owner_organisation_id`.
  - `supplier_id` string, required: All credits in a retirement must originate from the same supplier.
  - `retirement_purposes` RetirementPurpose[], required
  - `notes` string, nullable, required: A publicly visible note stored with the credit retirement.
  - `credit_quantity_kg` integer, required: A representation of a credit quantity as an **integer kilogram amount**. Where **1 unit represents 0.001 credits** and 1 kilogram of CO₂e. This field can handle bigint values.
  - `vintage` integer, nullable: The year of the credits to be retired. If not provided, the oldest credits will be retired.
  - `order_id` string, nullable: Filter to only retire credits from a specific order. If not provided, credits from any order will be considered.

## Response `200`

Successful Response

- Retirement
  - `id` string, required
  - `retired_at` string, date-time, required
  - `purposes` RetirementPurpose[], required
  - `beneficiary` Organisation, required
    - `id` string, required
    - `name` string, required
    - `domain` string, nullable, required
  - `owner` Organisation, required
    - `id` string, required
    - `name` string, required
    - `domain` string, nullable, required
  - `credit_batch_size_total` CreditQuantity, required
    - `credits` number, required: A representation of the credit quantity as a fractional amount, to 3 decimal places. Where 1 unit represents 1 credit and 1 ton of CO₂e.
    - `credit_kgs` integer, required: A representation of the credit quantity as an integer kilogram amount. Where 1 unit represents 0.001 credits and 1 kilogram of CO₂e. This field can handle bigint values.
  - `url` string, required
  - `notes` string, nullable, required

## Other responses

- `422`: Validation Error

## Changes

- **2026-08-04** `f1623e0dc2e1`: 3 info
  - added the new optional request property `order_id`
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status
- **2025-10-06** `656267cf681c`: 3 breaking, 1 warning, 4 info
  - the `beneficiary/id` response property's maxLength was increased from `36` to `37` for the response status `200`
  - the `id` response property's maxLength was increased from `36` to `37` for the response status `200`
  - the `owner/id` response property's maxLength was increased from `36` to `37` for the response status `200`
  - added the new `insetting` enum value to the `purposes/items/` response property for the response status `200`
  - …4 more

[Operation history](https://skmtc.dev/isometric/apis/isometric-registry-api/changes/retirements/from_oldest_credits/post.md)

---

[API](https://skmtc.dev/isometric/apis/isometric-registry-api.md) - [All operations](https://skmtc.dev/isometric/apis/isometric-registry-api/llms.txt) - [OpenAPI document](https://skmtc.dev/isometric/apis/isometric-registry-api/revisions/385518aba17d?raw)