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

# Restructure a loan

> Replace the unpaid remainder by a stated schedule. The clock restarts on it.

A restructuring replaces the Loan's unpaid remainder, from `on`, by a stated schedule. The Loan reads `restructured` until it closes.

* **The remainder** is what ending the Loan on `on` would cost: every matured period still owed with its penalty and late fee to the day, the elapsed interest, the fee the market holds owed, and the unmatured principal.
* **The schedule** re-amortises the remainder's principal over `term_periods` periods on the Loan's own cadence from `on`, at the Loan's rate or a stated one inside the version's corridor, with the version's `restructuring_fee` spread across them.
* **The unpaid charges are carried, not capitalised.** The interest, fee, penalty and late fee the remainder holds, each with its tax, are spread over the new periods in equal shares and appear on each as `carried`. They are inside the payment and bear nothing: no interest is charged on them and no penalty accrues on them. Charging interest on unpaid interest is anatocismo, and the Platform never does it.
* **The replaced periods** stay with what was paid of them and read settled from `on`. The arrears from the next day are the new schedule's alone; money from `on` pays the new schedule.

The disclosure figure does not move.

## 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 day the schedule takes over.
</ParamField>

<ParamField body="term_periods" type="integer" required>
  How many periods. One the version sells.
</ParamField>

<ParamField body="rate" type="string">
  Annual, as a decimal percentage, inside the version's corridor. Absent keeps the Loan's own.
</ParamField>

<ParamField body="fee" type="object">
  The version's `restructuring_fee`, restated. The fee is always the version's, stated or not; a different fee, or any fee under a version that declares none, is `422` `term_refused`.
</ParamField>

<ParamField body="reference" type="string" required>
  Your name for the act, in the one act namespace of the Tenancy.
</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` reads `restructured`; the event carries the new periods as `segment`, and `rate` and `fee` where stated. Retry `200`.

## Refusals

| Condition | Status and code | What clears it |
| - | - | - |
| A term the version does not sell, or a rate outside its corridor | <Badge color="orange">422</Badge> `term_refused` | State one it admits |
| An acceleration stands | <Badge color="red">409</Badge> `acceleration_in_force` | Retract it |
| A suspension stands over `on` | <Badge color="red">409</Badge> `suspension_in_force` | End or retract it |
| The Loan owes nothing, or a fact stands after `on` | <Badge color="orange">422</Badge> `invalid_event` | Nothing, or state a later day |

A second restructuring replaces the first's remainder. They are retracted last in, first out.

<RequestExample>
  ```bash Restructure a loan theme={null}
  BODY='{
    "on": "2026-10-20",
    "term_periods": 8,
    "rate": "30",
    "reference": "plan-0001",
    "actor": "collections-0002",
    "basis": "payment plan agreed"
  }'

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


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