> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clevis.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Corrections

> Recalculate before release without destroying what you already answered

Payroll gets reviewed before it gets paid. When the review sends something back, you
recalculate — and the question is what happens to the number you already produced.

In Clevis, **nothing**. The earlier calculation is never modified. The new one records
which calculation it replaces.

## The calculate → review → recalculate flow

<Steps>
  <Step title="Calculate">
    `POST /v1/payroll/calculate` returns a calculation with an `id`.
  </Step>

  <Step title="Review">
    Your team, or your customer, finds something wrong — a missing bonus, a wrong risk
    class, an overtime bucket that was not loaded.
  </Step>

  <Step title="Recalculate, pointing at the original">
    Send the corrected request with `options.supersedes` set to the original `id`.
  </Step>
</Steps>

```json theme={null}
{
  "country": "CO",
  "scheme": "ordinario",
  "year": 2026,
  "period": {
    "type": "monthly",
    "start_date": "2026-09-01",
    "end_date": "2026-09-30",
    "days": 30
  },
  "employee": {
    "id": "emp_001",
    "daily_salary": 100000,
    "monthly_salary": 3000000,
    "risk_class_rate": 0.04350
  },
  "employer": { "id": "employer_001" },
  "options": {
    "supersedes": "01HX9B2KM3V4W5X6Y7Z8A9B0CD"
  }
}
```

The response is a new calculation with a new `id`, and `record.supersedes_id` pointing at
the original.

## What this guarantees

* **The original is untouched.** It keeps its amounts, its audit trail and its
  `content_digest`. If someone asks eight months from now what you first answered, the
  answer still exists.
* **The listing marks it.** A superseded calculation is flagged `is_superseded` in
  `GET /v1/payroll/calculations`, so you can filter it out of a current view without
  deleting it.
* **A correction is a new record, always.** Immutability here is enforced by database
  permission, not by convention: the application role has no `UPDATE` and no `DELETE` on
  calculations.

## Validation

`options.supersedes` must point at a calculation for the **same employee, the same
employer and the same period**. Anything else is rejected with `422 SUPERSEDES_MISMATCH`.

The point is that a correction corrects *something specific*. A chain that jumps employees
or periods is not a correction, it is a mistake.

<Note>
  `supersedes` takes an id up to 64 characters and must reference a calculation belonging to
  your own client. An id you cannot see returns `404 CALCULATION_NOT_FOUND`.
</Note>

## Chains

A correction can itself be corrected: point the third calculation at the second. Each link
records only its immediate predecessor, so the chain is walkable in either direction and
no record in it is ever rewritten.

## What this is not

<Warning>
  **There are no workflow states.** No draft, no approved, no released. `supersedes` and
  [`metadata`](/calculations/provenance#labelling-calculations-with-metadata) cover the need without committing the API to a state machine nobody has specified.

  If you need approval states, model them in your own system and use `metadata` to carry
  your identifiers.
</Warning>