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

# Read the book

> A Client's Loans on a date, in one read: each Loan's standing, and what the Client holds across them.

Every Loan the Client holds, on the date you name, in one answer. Each Loan carries its [listing row](/api-reference/loans/list) — what was paid, the settled and remaining Periods, the penalty rate, whether it owes and to whom. A Loan open on the date also carries what [the payment options](/api-reference/clients/payment-options) and [the delinquency read](/api-reference/loans/delinquency) answer for it, field for field.

Beside the Loans, the book states what the Client holds **across** them, per currency: what is late, the earliest instalment ahead, the Periods to come and the Periods paid by month, and how many Loans are open and closed.

**One read, one derivation.** The whole answer comes from one pass over the Client's Receipts up to the date — the same pass that settles a Receipt. No figure in it can differ from the per-Loan reads for the same date. It costs what one schedule read costs, and it replaces a listing plus an options read plus a schedule, delinquency and Loan read per credit.

<Note>
  **The payoff is absent unless you ask for it, and nothing is ever recorded.** The figure the book serves is the one [a recorded payoff quote](/api-reference/loans/record-payoff-quote) for the same Loan and date holds. When you relay it to a borrower as the figure to pay, record it there.
</Note>

**A validator on every read.** A book read answers with an `ETag`, with the payoff or without it; send it back in `If-None-Match` and an unchanged book on the same date is answered `304` with no body, before anything is derived — as on [the payment options](/api-reference/clients/payment-options).

## Path parameters

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

<ParamField path="client_id" type="string" required>
  The Client whose book this is.
</ParamField>

## Query parameters

<ParamField query="on" type="string" required>
  The civil date every figure stands for. Required and never defaulted; absent is `422` — there is no today the Platform can supply.
</ParamField>

<ParamField query="schedules" type="string" default="none">
  Which Loans carry their schedule as the Receipts left it on the date.

  | Value | Carries a schedule |
  | - | - |
  | `none` | No Loan. |
  | `active` | Each Loan open on the date. |
  | `all` | Each Loan the date reaches. |
</ParamField>

<ParamField query="include" type="string">
  `payoff` adds each open Loan's payoff figure and what discharges every open Loan, and records nothing. Anything else is `400` `invalid_query`.
</ParamField>

## Response

<ResponseField name="on" type="string" required>
  The date every figure is true of.
</ResponseField>

<ResponseField name="loans" type="array" required>
  Every Loan the Client holds, whatever its state.

  <Expandable title="loan">
    <ResponseField name="(the listing row)" type="object" required>
      Every field of [a listing row](/api-reference/loans/list): `id`, `state`, `paid`, `totals.payments`, `settled_periods`, `remaining_periods`, `penalty_rate`, `owes`, `owed_to` and the rest. `paid` and the Period counts are as of the date.
    </ResponseField>

    <ResponseField name="overdue, late, instalment, any_other_amount, suspension" type="object">
      The payment options' figures for this Loan, with their meanings unchanged: `late` is absent when the Loan is not late — a Loan whose clock a suspension stopped is not — `overdue` holds the instalment due on the date, and `suspension` names the suspension in force.
    </ResponseField>

    <ResponseField name="payoff" type="object">
      Present only with `include=payoff`.
    </ResponseField>

    <ResponseField name="arrears" type="object">
      The delinquency read's answer: `worst_days_past_due`, and each Period overdue with its onset, days, base, penalty, late fee and the tax on each.
    </ResponseField>

    <ResponseField name="schedule" type="array">
      The schedule as the Receipts left it, where `schedules` selected this Loan.
    </ResponseField>
  </Expandable>

  Every dated figure is absent on a Loan that is not open on the date: a closed or cancelled Loan, one whose anchor falls after the date, and a ceded Loan from its cut-off. A Loan the Platform cannot describe carries the reason in `anomalies` and takes no other Loan with it.
</ResponseField>

<ResponseField name="currencies" type="array" required>
  What the Client holds across Loans, one entry per currency. Nothing is summed across currencies.

  | Field | What it is |
  | - | - |
  | `open_loans` | Loans open on the date. A written-off Loan is open: it can still be paid. |
  | `closed_loans` | Loans the Receipts discharged by the date. |
  | `payoff` | What discharges every open Loan, and how many. Only with `include=payoff`. |
  | `late` | What is late across the open Loans, with the count of Periods and of Loans. A zero where nothing is. |
  | `next_instalment` | The earliest instalment ahead: Loan, Period, due date and what it owes. |
  | `to_come` | Periods still to come, grouped by the month they fall due, each month with its total and count. |
  | `paid` | Periods settled, grouped by the month they were settled in, each month with its total and count. |
  | `anomalies` | Why a figure across Loans is absent. |

  **Late means what delinquency means:** a Period past its tolerance end and not settled. An instalment falling due on the date is collectable, not late — it is in `next_instalment`, not in `late`.

  A figure across Loans is **absent rather than short** where a Loan that would count towards it could not be described. The counts stand.
</ResponseField>

## One identifier, one book

A book is one registered Client identifier's. The Platform never relates two identifiers, and no per-Client answer — this book, the options, the obligations, the credit bar — spans more than one. If you learn two identifiers are one person, relate them in your own records.

<RequestExample>
  ```bash Read theme={null}
  curl "https://api.capcells.com/v1/tenants/$TENANT_ID/clients/c-0001/book?on=2026-10-01" \
    -H "Authorization: $(capcells_sign "$CAPCELLS_API_KEY" GET "/v1/tenants/$TENANT_ID/clients/c-0001/book?on=2026-10-01")"
  ```

  ```bash With schedules and the payoff theme={null}
  QUERY="?on=2026-10-01&schedules=active&include=payoff"
  curl "https://api.capcells.com/v1/tenants/$TENANT_ID/clients/c-0001/book$QUERY" \
    -H "Authorization: $(capcells_sign "$CAPCELLS_API_KEY" GET "/v1/tenants/$TENANT_ID/clients/c-0001/book$QUERY")"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "client_id": "c-0001",
    "on": "2026-10-01",
    "loans": [
      {
        "id": "7771aef0-9e65-4a0a-a902-aab4e970d33f",
        "tenant_id": "t-0001",
        "client_id": "c-0001",
        "reference": "loan-0001",
        "configuration": { "id": "inst-000001", "version": 1 },
        "principal": { "minor_units": 500000, "currency": "MXN" },
        "term_periods": 6,
        "rate": "45.5",
        "fee": { "minor_units": 25000, "currency": "MXN" },
        "paid": { "minor_units": 90066, "currency": "MXN" },
        "totals": { "payments": { "minor_units": 540396, "currency": "MXN" } },
        "settled_periods": 1,
        "remaining_periods": 5,
        "penalty_rate": "36",
        "owes": true,
        "owed_to": "tenant",
        "anchor": "2026-08-10",
        "state": "active",
        "rolled_over": 0,
        "created_at": "2026-08-10T12:00:01Z",
        "anomalies": [],
        "overdue": { "total": { "minor_units": 0, "currency": "MXN" }, "charges": [] },
        "instalment": {
          "index": 2,
          "scheduled_on": "2026-10-10",
          "due_on": "2026-10-12",
          "owed": { "total": { "minor_units": 90066, "currency": "MXN" }, "charges": [ … ] },
          "actionable_from": "2026-10-12",
          "requires_overdue_settled": false,
          "settled_by": "instalment"
        },
        "any_other_amount": { "treatment": "reduces_principal", "description": "…" },
        "arrears": {
          "on": "2026-10-01",
          "worst_days_past_due": 0,
          "penalty": { "minor_units": 0, "currency": "MXN" },
          "late_fee": { "minor_units": 0, "currency": "MXN" },
          "tax": { "minor_units": 0, "currency": "MXN" },
          "total": { "minor_units": 0, "currency": "MXN" },
          "periods": []
        }
      }
    ],
    "currencies": [
      {
        "currency": "MXN",
        "open_loans": 1,
        "closed_loans": 0,
        "late": { "total": { "minor_units": 0, "currency": "MXN" }, "periods": 0, "loans": 0 },
        "next_instalment": {
          "loan_id": "7771aef0-9e65-4a0a-a902-aab4e970d33f",
          "reference": "loan-0001",
          "index": 2,
          "due_on": "2026-10-12",
          "owed": { "minor_units": 90066, "currency": "MXN" }
        },
        "to_come": [
          { "month": "2026-10", "total": { "minor_units": 90066, "currency": "MXN" }, "periods": 1 },
          { "month": "2026-11", "total": { "minor_units": 90066, "currency": "MXN" }, "periods": 1 }
        ],
        "paid": [
          { "month": "2026-09", "total": { "minor_units": 90066, "currency": "MXN" }, "periods": 1 }
        ],
        "anomalies": []
      }
    ]
  }
  ```
</ResponseExample>


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