> ## 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 return
> Record that the purchase behind the loan went back, at what the goods were worth, and read where every part of it went.
A return records that goods behind the Loan went back to the store. It reduces principal — a return is not a payment and settles no component. The amount is required and is the one figure any act's body states: your report of what went back, which nothing on the Platform can derive.
State what the goods were worth, the whole price included. The Platform answers the split:
| Part of the value | What happens to it |
| - | - |
| Up to the principal outstanding on `on` | Unwound. The plan is recalculated with the term kept, or ends where the return reaches all of it; interest accrued to the date stands. |
| The principal of every matured period, where the value covers all of it | Unwound too: the Loan reads returned whole from `on`, still owing the periods' interest, fee, penalty and late fee to that date. Where the value does not cover it, the matured periods stand as they are. |
| The principal the Loan had received — instalments paid, principal settled early, the payment at the purchase — up to what is left | Owed back to the Client, named by the return in the [obligations](/api-reference/clients/obligations). |
| Anything beyond all of that | Your own refund to your borrower, outside the book: stated, never recorded. |
A return is admitted on a Loan issued under an `instalment` or a `bnpl` product, and refused on a `payday` one. Whether the money bought goods is your statement, made in the act: the Platform holds no merchant and no goods, and the `reference`, `actor` and `basis` of the act are what say what went back.
## Path parameters
The Tenancy acting.
The Loan. Another Tenancy's and one that never existed are both `404`.
## Body
The civil day the goods went back, never defaulted.
What the goods were worth: `{"minor_units": 37500, "currency": "MXN"}`. The whole price is fine; above the outstanding principal on that date only where the Loan has received principal or carries a matured period.
Your name for the act, in the one act namespace of the Tenancy.
Whoever acted, your own reference — the store's desk, in the ordinary case.
Why, in your words. There is no reason field and no merchant field: what you want remembered goes here and in `context`.
Stored, echoed beside the fact, read by nothing.
## Response
`201` with [the whole Loan](/api-reference/loans/read): the `returned` event carries the act and `amount`, what went back, the state stays `active`, and every figure derives with the principal reduced. The `amount` is on the `returned` event and on no other kind, and a retracted return keeps it. Retry `200`; a differing body under the recorded `reference`, `409` `reference_reused`.
The Loan carries `returns`, one entry per return in force, oldest first — derived on every read, so a Receipt reported later and value-dated before the return changes the split it reads with:
| Field | Meaning |
| - | - |
| `act`, `on`, `amount` | The return: its reference, its day, what you stated the goods were worth |
| `unwound_principal` | Principal the return took off what the Loan owed |
| `principal_owed_back` | Principal the Loan had received that the return gives back |
| `interest_owed_back` | What the repricing left settled above what the plan then charged — interest, with the fee and tax that ride it |
| `still_owed` | What discharging the Loan on `on` would take once the return applied, by charge |
| `beyond_the_loan` | Your own refund, outside the book |
| `returned_whole` | Whether the return covered all the principal the Loan still owed, matured periods included |
Your paper reads straight off it: "we cancelled your credit; what was charged to date is `still_owed`; we owe you back `principal_owed_back` plus `interest_owed_back`".
## Refusals
| Condition | Status and code | What clears it |
| - | - | - |
| The Loan was issued under a `payday` product, which finances no purchase | 422 `return_not_provided` | Nothing clears it: a pay day advance has nothing to send back |
| The amount exceeds the outstanding principal on the date, and the Loan has received no principal and carries no matured period | 409 `return_exceeds_principal` | Nothing beyond the principal could be unwound or owed back: record the return for the principal; the rest is your own refund to your borrower |
| The Loan is cancelled, ceded or written off | 409 / 422 | The refusal names the fact in force and its cure |
```bash Record a return theme={null}
BODY='{
"on": "2026-03-20",
"amount": { "minor_units": 37500, "currency": "MXN" },
"reference": "return-0001",
"actor": "store-014",
"basis": "cliente devolvio la mercancia en tienda"
}'
curl -X POST "https://api.capcells.com/v1/tenants/$TENANT_ID/loans/$LOAN_ID/return" \
-H "Authorization: $(capcells_sign "$CAPCELLS_API_KEY" POST "/v1/tenants/$TENANT_ID/loans/$LOAN_ID/return" "$BODY")" \
-H "Content-Type: application/json" \
-d "$BODY"
```
```json 201, the recorded event theme={null}
{
"state": "active",
"events": [
{ "id": "…0001", "kind": "issued", "occurred_on": "2026-03-02", "recorded_at": "2026-08-31T11:27:14.640671Z" },
{
"id": "…0002",
"kind": "returned",
"occurred_on": "2026-03-20",
"recorded_at": "2026-08-31T11:27:14.654819Z",
"act": {
"reference": "return-0001",
"actor": "store-014",
"basis": "cliente devolvio la mercancia en tienda"
},
"amount": { "minor_units": 37500, "currency": "MXN" }
}
],
…
}
```
```json 201, a whole return after the till payment theme={null}
{
"state": "active",
"returns": [
{
"act": "return-0002",
"on": "2026-08-20",
"amount": { "minor_units": 500000, "currency": "MXN" },
"unwound_principal": { "minor_units": 375000, "currency": "MXN" },
"principal_owed_back": { "minor_units": 125000, "currency": "MXN" },
"interest_owed_back": { "minor_units": 0, "currency": "MXN" },
"still_owed": {
"total": { "minor_units": 27247, "currency": "MXN" },
"charges": [
{ "charge": "fee", "amount": { "minor_units": 18750, "currency": "MXN" }, "tax": { "minor_units": 3000, "currency": "MXN" }, "total": { "minor_units": 21750, "currency": "MXN" } },
{ "charge": "interest", "amount": { "minor_units": 4739, "currency": "MXN" }, "tax": { "minor_units": 758, "currency": "MXN" }, "total": { "minor_units": 5497, "currency": "MXN" } }
]
},
"beyond_the_loan": { "minor_units": 0, "currency": "MXN" },
"returned_whole": true
}
],
…
}
```
```json 409 More than the loan theme={null}
{
"error": "loan: the return exceeds the outstanding principal on that date: a return of 5000.01 MXN against 0d7fe06d-1559-4bac-a56e-a9fcbbf7f494, whose principal outstanding on 2026-08-20 is 5000.00 MXN and which has received no principal and carries no matured period — what the goods were worth beyond it is the tenant's own refund to its borrower, settled where that money actually moves",
"code": "return_exceeds_principal"
}
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.