> ## 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 a merchant's book

> What was issued under one merchant over a period, and what was taken back, with the period's totals per currency.

A Loan may name the merchant it financed a purchase at, by your own `merchant_ref` on [the issuance](/api-reference/loans/issue). This read answers, for that merchant and a period: every sale that bound inside the period — on its anchor, or on its confirmation's date where it was issued with a hold — with its principal and its state; and every return, cancellation, rescission, void and withdrawal recorded on such a Loan with its date inside the period, with its figure. Beside the entries, the whole period's totals per currency — on every page.

**A hold is no sale until it is confirmed.** As a card authorisation is settled only once captured, a Loan issued with a hold enters the book on the day it is confirmed. One that expired or was voided unconfirmed never bound and is on no merchant's book. A confirmation after a period never reaches back into it, so a period you settled stays settled.

**Settlement is your ledger.** What you owe the merchant is the principal issued, less the commission your agreement states and that commission's tax, less what was taken back, plus or minus any subsidy you agreed. The Platform holds no commission, no agreement and no merchant: it serves every figure the settlement starts from, and the subtraction your agreement states is yours.

| Entry | `amount` |
| - | - |
| `issued` | The principal. |
| `returned` | What the goods were worth. |
| `cancelled`, `rescinded`, `voided`, `withdrawn` | The principal the act undid: the principal less every return in force on the Loan, so a sale partly returned and then undone is never taken back twice. |

A retracted fact is off the book. The Platform keeps no register of merchants, so a `merchant_ref` no Loan names is an empty book, not a `404`.

## Path parameters

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

<ParamField path="merchant_ref" type="string" required>
  The merchant, as your Loans name it. Letters, digits, hyphen and underscore, 1 to 64; anything else is `400` `invalid_query`.
</ParamField>

## Query parameters

<ParamField query="from" type="string" required>
  The period's first day, included. Required and never defaulted — there is no today the Platform can supply.
</ParamField>

<ParamField query="to" type="string" required>
  The period's last day, included, on or after `from`.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  How many entries to serve, between 1 and 200.
</ParamField>

<ParamField query="cursor" type="string">
  Where to resume, returned verbatim from the previous page.
</ParamField>

A missing, malformed or inverted `from` or `to`, and any other parameter, is `400` `invalid_query`.

## Response

<ResponseField name="merchant_ref" type="string" required>
  The merchant, echoed.
</ResponseField>

<ResponseField name="from" type="string" required>
  The period's first day.
</ResponseField>

<ResponseField name="to" type="string" required>
  The period's last day.
</ResponseField>

<ResponseField name="entries" type="array" required>
  The page's facts, by day and then by the fact's identifier.

  <Expandable title="entry">
    <ResponseField name="id" type="string" required>
      The recorded fact: the issuance's own, or the act's.
    </ResponseField>

    <ResponseField name="kind" type="string" required>
      `issued`, `returned`, `cancelled`, `rescinded`, `voided` or `withdrawn`.
    </ResponseField>

    <ResponseField name="on" type="string" required>
      The anchor for an issuance, or the confirmation's date for one issued with a hold; the act's own date otherwise.
    </ResponseField>

    <ResponseField name="loan_id" type="string" required>
      The Loan the fact is about.
    </ResponseField>

    <ResponseField name="reference" type="string" required>
      The Loan's reference.
    </ResponseField>

    <ResponseField name="client_id" type="string" required>
      The Client the Loan names.
    </ResponseField>

    <ResponseField name="amount" type="object" required>
      The fact's figure, per the table above.
    </ResponseField>

    <ResponseField name="state" type="string">
      On an issuance only: the Loan's state exactly as [the listing](/api-reference/loans/list) reads it.
    </ResponseField>

    <ResponseField name="anomalies" type="array">
      On an issuance only, where the listing's row would carry any.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="totals" type="array" required>
  The whole period, one row per currency, ordered by code. Each row states `issued`, `returned`, `cancelled`, `rescinded`, `voided` and `withdrawn` as `{count, amount}` — a kind the period holds none of is a stated zero, so you subtract without checking whether a field is there.
</ResponseField>

<ResponseField name="cursor" type="string">
  Present while more entries exist; absent at the end.
</ResponseField>

<RequestExample>
  ```bash theme={null}
  curl "https://api.capcells.com/v1/tenants/$TENANT_ID/merchants/store-0042/book?from=2026-09-01&to=2026-09-30" \
    -H "Authorization: $(capcells_sign "$CAPCELLS_API_KEY" GET "/v1/tenants/$TENANT_ID/merchants/store-0042/book?from=2026-09-01&to=2026-09-30")"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "merchant_ref": "store-0042",
    "from": "2026-09-01",
    "to": "2026-09-30",
    "entries": [
      {
        "id": "aac1e3d3-0c27-4790-99f7-636f494b64a5",
        "kind": "issued",
        "on": "2026-09-02",
        "loan_id": "2241c66e-1163-4d4c-9a78-aa2d29912201",
        "reference": "sale-1001",
        "client_id": "c-0001",
        "amount": { "minor_units": 500000, "currency": "MXN" },
        "state": "active"
      },
      {
        "id": "64d0cefa-d65f-4806-858d-6510a69ba988",
        "kind": "issued",
        "on": "2026-09-05",
        "loan_id": "3439988a-fd7d-4d6a-9fac-44d7bb0415fc",
        "reference": "sale-1002",
        "client_id": "c-0002",
        "amount": { "minor_units": 300000, "currency": "MXN" },
        "state": "active"
      },
      {
        "id": "95c44c3c-cf39-44eb-bf95-40c599006dc6",
        "kind": "returned",
        "on": "2026-09-12",
        "loan_id": "2241c66e-1163-4d4c-9a78-aa2d29912201",
        "reference": "sale-1001",
        "client_id": "c-0001",
        "amount": { "minor_units": 100000, "currency": "MXN" }
      }
    ],
    "totals": [
      {
        "currency": "MXN",
        "issued": { "count": 2, "amount": { "minor_units": 800000, "currency": "MXN" } },
        "returned": { "count": 1, "amount": { "minor_units": 100000, "currency": "MXN" } },
        "cancelled": { "count": 0, "amount": { "minor_units": 0, "currency": "MXN" } },
        "rescinded": { "count": 0, "amount": { "minor_units": 0, "currency": "MXN" } },
        "voided": { "count": 0, "amount": { "minor_units": 0, "currency": "MXN" } },
        "withdrawn": { "count": 0, "amount": { "minor_units": 0, "currency": "MXN" } }
      }
    ]
  }
  ```
</ResponseExample>


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