Correcting mistakes

A correction is an addition. Nothing recorded is ever edited or deleted: what was reported wrong stays readable, a further fact withdraws it, and every figure is derived again from the record that now stands. An audit reads the mistake, the withdrawal, and who recorded each. Two instruments cover everything, and which one applies is decided by what was wrong:

What was wrong	Use	Covered on
A recorded fact, a cancellation, an acceleration, a write-off, a rollover, a return, a cession	Retraction, by event identifier	This page
Reported money: the transfer bounced, the amount was mistyped, the report was a duplicate	Reversal, by the payment’s reference	Payments, and a summary below
A client’s label	Correction, the Platform’s one `PATCH`	Clients

Retraction

A retraction withdraws one recorded fact, totally: no amount, no scope, no partial version of the fact survives. The body carries on, the day the fact was found to be an error, and the account every act gives of itself. On Loans, an agreement recorded in error was cancelled under cancel-0001. The follow-up found the error’s error: the cancellation itself had been recorded on the wrong loan. The cancellation is a fact, so it is retracted, by the identifier the loan’s events[] carries:

Retract the cancellation

BODY='{
  "on": "2026-03-05",
  "reference": "retract-0001",
  "actor": "ops-0007",
  "basis": "the cancellation was recorded on the wrong loan"
}'

curl -X POST "https://api.capcells.com/v1/tenants/$TENANT_ID/loans/$LOAN_ID/events/$EVENT_ID/retraction" \
  -H "Authorization: $(capcells_sign "$CAPCELLS_API_KEY" POST "/v1/tenants/$TENANT_ID/loans/$LOAN_ID/events/$EVENT_ID/retraction" "$BODY")" \
  -H "Content-Type: application/json" \
  -d "$BODY"

201

{
  "id": "c68c7355-0598-4cf4-a69a-b6b4ea10a5c4",
  "tenant_id": "t-0001",
  "state": "active",
  "created_at": "2026-08-31T10:22:54.882408Z",
  "rolled_over": 0,
  "events": [
    { "id": "a5ff8602-8b4d-4284-a666-cb32e96264c8", "kind": "issued",
      "occurred_on": "2026-03-02", "recorded_at": "2026-08-31T10:22:54.882408Z" },
    {
      "id": "f320eedd-93ea-4db2-8292-53df58ab9473",
      "kind": "cancelled",
      "occurred_on": "2026-03-03",
      "recorded_at": "2026-08-31T10:22:54.894711Z",
      "retraction": {
        "on": "2026-03-05",
        "recorded_at": "2026-08-31T11:13:11.330357Z",
        "act": {
          "reference": "retract-0001",
          "actor": "ops-0007",
          "basis": "the cancellation was recorded on the wrong loan"
        }
      },
      "act": {
        "reference": "cancel-0001",
        "actor": "ops-0007",
        "basis": "agreed in error: wrong client selected at the desk"
      }
    }
  ],
  "anomalies": []
}

The loan reads active again in the same answer, and the record keeps everything: the cancellation, its act, and the retraction block naming who withdrew it, when, and why. A withdrawn fact contributes to nothing. Every derivation runs as if it had never been recorded, and stays readable forever. A retraction is an act like the others: an identical retry answers 200, its reference reused for anything different is 409 reference_reused, and withdrawing what is already withdrawn is a conflict naming the event:

409

{
  "error": "loan: the fact is already retracted: f320eedd-93ea-4db2-8292-53df58ab9473",
  "code": "already_retracted"
}

What cannot be

Fact	Why	Use instead
The issuance	A loan is not corrected out of existence, the record that an agreement was made is the one fact everything else hangs from	Cancellation, which records that the disbursement never happened
A derived fact, the `settled` event	No row carries it, so it has no identifier and no retraction can name it	Reverse the receipt that produced it
Anything on a ceded loan except the cession	From the cut-off the loan is not yours to correct	Retract the cession first; every correction is then available again

The first is refused naming the cure:

422

{
  "error": "loan: that fact cannot be retracted: a5ff8602-8b4d-4284-a666-cb32e96264c8 is the issuance of c68c7355-0598-4cf4-a69a-b6b4ea10a5c4: cancel the loan instead, which records that the disbursement never happened",
  "code": "not_retractable"
}

Reversal

Money reported in error is corrected on the payment itself, not on the loan’s events: a reversal under the payment’s own reference, stating actor, basis and one of three reasons, chargeback, returned_transfer, operator_error. The payment stays readable, marked reversed, and every allocation it produced is derived again without it, so a loan it had closed reads open. Payments carries the route, the body and the worked reversal in full.

What is recomputed

Nothing, and that is the design. There is nothing to recompute, because nothing derived is stored. State, arrears, payoff figures and schedules are computed from the recorded facts on every read, so a correction does not trigger a recalculation. It changes what the next read derives from.

After	What the next read answers
Retracting a cancellation	The state its remaining facts produce, `active` above, `written_off` where one still stands underneath
Retracting an acceleration	Only what missed its own due date stands overdue; everything the call had made overdue is derived again as if it had not been made
Retracting a write-off	The charging resumes as if it had never stopped, because the stopping was derived from the fact now withdrawn
Reversing a receipt	Everything the money had settled stands owed again, `closed_on` gone where it had discharged the loan

One consequence is worth designing for. Facts recorded while the withdrawn fact stood are not re-examined. Where a sequence of corrections leaves the record contradicting itself, the fold resolves it by precedence and reports the pair in anomalies[] rather than refusing the read. Loans carries the states, the precedence and the anomaly channel.

Getting started

Authentication

Lending

Risk

Markets

Correcting mistakes

Retraction

What cannot be

Reversal

What is recomputed

​Retraction

​What cannot be

​Reversal

​What is recomputed

Retraction

What cannot be

Reversal

What is recomputed