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

# Record a cancellation

> Record that the agreement never began. The loan reports cancelled, keeps its record, and answers the whole read back.

A cancellation asserts the Loan never began — signed in error, or never disbursed. Recording answers `201` with the Loan as it now reads; an identical retry answers `200`; a differing request under the recorded `reference` is `409` `reference_reused`. [Cancelling a Loan](/lending/loans) carries the semantics in full.

## Path parameters

<ParamField path="tenant_id" type="string" required>
  The Tenancy acting.
</ParamField>

<ParamField path="loan_id" type="string" required>
  The Loan. Another Tenancy's and one that never existed are both `404`.
</ParamField>

## Body

<ParamField body="on" type="string" required>
  The civil day the fact is about, never defaulted. Not before the `anchor`: a cancellation cannot predate the agreement it cancels.
</ParamField>

<ParamField body="reference" type="string" required>
  Your name for the act. One namespace per Tenancy across all nine acts — a reference that named a cancellation cannot later name a write-off. A refused act spends no reference.
</ParamField>

<ParamField body="actor" type="string" required>
  Your own reference for whoever acted, at most 1024 bytes, never blank. Never derived from the credential.
</ParamField>

<ParamField body="basis" type="string" required>
  What they wrote down about why — free text, at most 1024 bytes, never blank. The Platform imposes no vocabulary of reasons.
</ParamField>

<ParamField body="context" type="object">
  Your key-value object, stored and echoed beside the fact on every read, read by nothing.
</ParamField>

## Response

`201` with [the whole Loan](/api-reference/loans/read): `state` reads `cancelled`, the `cancelled` event carries the act, and the plan stays readable — nothing recorded is removed. A cancellation is withdrawn by [retracting it](/api-reference/loans/retraction).

## Refusals

| Condition | Status and code | What clears it |
| - | - | - |
| A cancellation already stands | <Badge color="red">409</Badge> `already_cancelled` | Nothing — the retry that answers `200` is the one under the recorded `reference` |
| An acceleration stands in force | <Badge color="red">409</Badge> `acceleration_in_force` | Retract the acceleration |
| A write-off stands in force | <Badge color="red">409</Badge> `write_off_in_force` | Retract the write-off |
| A cession stands in force | <Badge color="red">409</Badge> `cession_in_force` | Retract the cession |
| Money has reached the Loan | <Badge color="red">409</Badge> `receipt_allocated` | Reverse those Receipts, if they were reported in error |
| The date falls before the `anchor` | <Badge color="orange">422</Badge> `invalid_event` | State a day on or after the anchor |

<RequestExample>
  ```bash Cancel theme={null}
  BODY='{
    "on": "2026-03-03",
    "reference": "cancel-0001",
    "actor": "ops-0007",
    "basis": "agreed in error: wrong client selected at the desk"
  }'

  curl -X POST "https://api.capcells.com/v1/tenants/$TENANT_ID/loans/$LOAN_ID/cancellation" \
    -H "Authorization: $(capcells_sign "$CAPCELLS_API_KEY" POST "/v1/tenants/$TENANT_ID/loans/$LOAN_ID/cancellation" "$BODY")" \
    -H "Content-Type: application/json" \
    -d "$BODY"
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "c68c7355-0598-4cf4-a69a-b6b4ea10a5c4",
    "state": "cancelled",
    "events": [
      { "id": "…0001", "kind": "issued", "occurred_on": "2026-03-02", "recorded_at": "2026-08-31T10:22:54.882408Z" },
      {
        "id": "…0002",
        "kind": "cancelled",
        "occurred_on": "2026-03-03",
        "recorded_at": "2026-08-31T10:22:54.894711Z",
        "act": {
          "reference": "cancel-0001",
          "actor": "ops-0007",
          "basis": "agreed in error: wrong client selected at the desk"
        }
      }
    ],
    "anomalies": [],
    …
  }
  ```

  ```json 409 Money reached it theme={null}
  {
    "error": "loan: the loan has had a receipt allocated to it: 537644fc-188d-4d2f-bc6c-db8128ad5828 has received money, so it began whatever was intended — reverse the receipts first if they were reported in error",
    "code": "receipt_allocated"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.