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

> Stop the loan's clock between two dates: no lateness, no penalty, no days past due inside the window, and the plan unchanged.

A suspension records that the Loan's clock stands still from `from` to `to`, both days included — while a store confirms a return, while a dispute is answered. Inside the window no Period becomes overdue, and a Period already overdue accrues no penalty and counts no day past due; after it, everything resumes. The plan does not move: due dates, interest and the schedule are what they were. [Delinquency](/lending/delinquency#suspension) carries the arithmetic.

The window is stated whole. Ending it sooner is [its own act](/api-reference/loans/suspension-end); withdrawing it as though it never was is [a retraction](/api-reference/loans/retraction).

## 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="from" type="string" required>
  The first day the clock stands still. Yours to state, never read from a clock; not before the Loan's anchor.
</ParamField>

<ParamField body="to" type="string" required>
  The last day it stands still, on or after `from`. Required — a clock stopped until further notice is a clock nobody restarts.
</ParamField>

<ParamField body="reference" type="string" required>
  Your name for the act, in the one act namespace of the Tenancy. A suspension and the return that follows it are two acts and take two references.
</ParamField>

<ParamField body="actor" type="string" required>
  Whoever acted, your own reference.
</ParamField>

<ParamField body="basis" type="string" required>
  Why, in your words.
</ParamField>

<ParamField body="context" type="object">
  Stored, echoed beside the fact, read by nothing.
</ParamField>

## Response

`201` with [the whole Loan](/api-reference/loans/read): `state` stays `active`, and the `suspended` event carries `to` beside its `occurred_on`. Retry `200`; a differing body under the recorded `reference` — another window included — `409` `reference_reused`.

From then on [the delinquency read](/api-reference/loans/delinquency), [the payment options](/api-reference/clients/payment-options) and [the book](/api-reference/clients/book) name the suspension in force on the date they are asked about, under `suspension`. Inside the window the payment options carry no `late`: what has fallen due stays in `overdue`.

## Refusals

| Condition | Status and code | What clears it |
| - | - | - |
| No `from` or no `to`, `to` before `from`, or `from` before the anchor | <Badge color="orange">422</Badge> `invalid_event` | State the window whole |
| A suspension in force overlaps the window | <Badge color="red">409</Badge> `suspension_in_force` | End or retract that suspension, or state a window after it |
| An acceleration in force falls inside the window | <Badge color="red">409</Badge> `acceleration_in_force` | Retract the acceleration, or state a window after it |
| The Loan is `written_off` or `ceded` | <Badge color="red">409</Badge> `write_off_in_force`, `cession_in_force` | Retract that fact |
| The Loan is `cancelled` | <Badge color="orange">422</Badge> `invalid_event` | Nothing — a Loan that never began has no clock to stop |

A window that follows one already recorded is a further suspension, not a conflict.

<RequestExample>
  ```bash Record a suspension theme={null}
  BODY='{
    "from": "2026-04-11",
    "to": "2026-04-25",
    "reference": "pause-0001",
    "actor": "ops-0007",
    "basis": "aclaración abierta; la tienda confirma la devolución",
    "context": { "case": "AC-2026-0418" }
  }'

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

<ResponseExample>
  ```json 201, the recorded event theme={null}
  {
    "state": "active",
    "events": [
      { "id": "…0001", "kind": "issued", "occurred_on": "2026-03-02", "recorded_at": "2026-10-14T11:27:14.548589Z" },
      {
        "id": "…0002",
        "kind": "suspended",
        "occurred_on": "2026-04-11",
        "recorded_at": "2026-10-14T11:27:14.679093Z",
        "act": {
          "reference": "pause-0001",
          "actor": "ops-0007",
          "basis": "aclaración abierta; la tienda confirma la devolución",
          "context": { "case": "AC-2026-0418" }
        },
        "to": "2026-04-25"
      }
    ],
    "anomalies": [],
    …
  }
  ```

  ```json 409 Overlapping theme={null}
  {
    "error": "loan: the loan carries a suspension in force over that date: … is suspended from 2026-04-11 to 2026-04-25 by …0002, and a window from 2026-04-20 to 2026-05-05 overlaps it -- end or retract that suspension first",
    "code": "suspension_in_force",
    "retry": "after_record"
  }
  ```
</ResponseExample>


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