---
title: "Create Retirement"
method: POST
path: "/retirements"
---

# Create Retirement

`POST /retirements`

Retire credits from specific batches, in whole or with splits. All credit batches must originate from the same supplier and be owned by the current organisation.

## Headers

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

## Request body

- CreateRetirementByBatchRequest
  - `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_batch_quantities` CreditBatchQuantity[], required — A list of credit batch IDs and kilogram amounts of each to retire.
    - `credit_batch_id` string, required
    - `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.

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

---

[API](https://skmtc.net/isometric/apis/isometric-registry-api.md) · [All operations](https://skmtc.net/isometric/apis/isometric-registry-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/isometric/isometric-registry-api/revisions/2e31eeb1cb99/schema)