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

> Carry the principal forward onto one more segment on unchanged terms, against the settlement the roll charges.

A rollover records the borrower settling the accrued cost of the Loan instead of repaying it: the principal carries forward onto one more segment, on unchanged terms, and the roll charges a **settlement** — the interest accrued to the date, the version's `rollover_fee`, and the tax on both. It exists on products whose version prices it; [Rolling a Pay Day Loan over](/lending/products) carries the mechanics, and [Lending in Mexico](/lending/mexico) what the operation costs in supervision.

<Warning>
  Recording a rollover does not collect the settlement. Report the money as [a Receipt](/api-reference/receipts/report) with the rollover date as its value date — left unreported, the settlement stands owed and goes overdue the day after.
</Warning>

## 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 borrower rolled, never defaulted. The segment anchors on it. The body carries nothing about the money: the fee and the limit are read from the Configuration version the Loan was issued under.
</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 roll's own answer — not the whole Loan:

<ResponseField name="loan_id" type="string" required>
  The Loan rolled.
</ResponseField>

<ResponseField name="rolled_over" type="integer" required>
  How many rollovers now stand in force, this one included — the number credit-risk staging turns on.
</ResponseField>

<ResponseField name="event" type="object" required>
  The `rolled_over` event as the Loan now carries it, its `segment` inside: the dates the principal carries onto.
</ResponseField>

<ResponseField name="settlement" type="object" required>
  What the roll charges, due on the roll date: `interest`, `fee`, `tax` and the derived `payment` — and no principal.
</ResponseField>

<ResponseField name="segment" type="object" required>
  The segment at its priced figures, its index continuing the Loan's schedule.
</ResponseField>

The Loan stays `active`, keeps its identifier, its terms and its disclosure figure. The issued plan is untouched; [the serviced Schedule](/api-reference/loans/schedule) is where the settlement and the segment appear.

## Refusals

| Condition | Status and code | What clears it |
| - | - | - |
| The date is at or before the latest rollover in force | <Badge color="red">409</Badge> `rollover_not_forward` | State a later date — segments only move forward |
| A Period stands overdue on the date | <Badge color="red">409</Badge> `overdue_on_rollover` | Settle the arrears — rolling an overdue Loan turns moratory exposure into fresh term |
| The count in force would exceed `rollover_limit` | <Badge color="red">409</Badge> `rollover_limit_reached` | Retract one, or issue under a version with a higher limit |
| The version states no `rollover_fee` | <Badge color="orange">422</Badge> `rollover_not_provided` | Issue under a version that prices the operation |
| A write-off stands in force | <Badge color="red">409</Badge> `write_off_in_force` | Retract the write-off — the same code every other act on a written-off Loan answers |
| The Loan owes nothing on the date | <Badge color="red">409</Badge> `nothing_to_roll_over` | Reverse the Receipt that settled it, if it was reported in error |
| An acceleration or a cession stands in force, or the Loan is cancelled | <Badge color="red">409</Badge> / <Badge color="orange">422</Badge> | The refusal names the fact and its cure |
| The segment the rollover would produce falls past [the jurisdiction's calendar](/lending/markets) | <Badge color="orange">422</Badge> `beyond_horizon` | Nothing on the Loan — the calendar is extended by a release, and the refusal names how far it reaches |

<RequestExample>
  ```bash Roll theme={null}
  BODY='{
    "on": "2026-03-16",
    "reference": "roll-0001",
    "actor": "ops-0007",
    "basis": "el cliente pidio prorroga en ventanilla"
  }'

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

<ResponseExample>
  ```json 201 theme={null}
  {
    "loan_id": "3439988a-fd7d-4d6a-9fac-44d7bb0415fc",
    "rolled_over": 1,
    "event": {
      "id": "95c44c3c-cf39-44eb-bf95-40c599006dc6",
      "kind": "rolled_over",
      "occurred_on": "2026-03-16",
      "recorded_at": "2026-08-31T11:27:14.570813Z",
      "segment": [
        { "index": 1, "scheduled_on": "2026-03-30", "due_on": "2026-03-30", "tolerance_end": "2026-03-30" }
      ],
      "act": {
        "reference": "roll-0001",
        "actor": "ops-0007",
        "basis": "el cliente pidio prorroga en ventanilla"
      }
    },
    "settlement": {
      "index": 2,
      "scheduled_on": "2026-03-16",
      "due_on": "2026-03-16",
      "principal": { "minor_units": 0, "currency": "MXN" },
      "interest": { "minor_units": 7000, "currency": "MXN" },
      "fee": { "minor_units": 10000, "currency": "MXN" },
      "tax": { "minor_units": 2720, "currency": "MXN" },
      "payment": { "minor_units": 19720, "currency": "MXN" }
    },
    "segment": [
      {
        "index": 3,
        "scheduled_on": "2026-03-30",
        "due_on": "2026-03-30",
        "principal": { "minor_units": 100000, "currency": "MXN" },
        "interest": { "minor_units": 7000, "currency": "MXN" },
        "fee": { "minor_units": 0, "currency": "MXN" },
        "tax": { "minor_units": 1120, "currency": "MXN" },
        "payment": { "minor_units": 108120, "currency": "MXN" }
      }
    ]
  }
  ```

  ```json 409 Not forward theme={null}
  {
    "error": "loan: a rollover must fall after the latest one still in force: 3439988a-fd7d-4d6a-9fac-44d7bb0415fc carries a rollover on 2026-03-16, and this one is stated for 2026-03-16",
    "code": "rollover_not_forward"
  }
  ```
</ResponseExample>


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