Skip to main content
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

1

Calculate

POST /v1/payroll/calculate returns a calculation with an id.
2

Review

Your team, or your customer, finds something wrong — a missing bonus, a wrong risk class, an overtime bucket that was not loaded.
3

Recalculate, pointing at the original

Send the corrected request with options.supersedes set to the original id.
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.
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.

​
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

There are no workflow states. No draft, no approved, no released. supersedes and 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.