Record a return

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"

{
  "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" }
    }
  ],
  …
}

{
  "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
    }
  ],
  …
}

{
  "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"
}

POST

tenants

{tenant_id}

loans

{loan_id}

return

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"

{
  "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" }
    }
  ],
  …
}

{
  "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
    }
  ],
  …
}

{
  "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"
}

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

string

required

The Tenancy acting.

string

required

The Loan. Another Tenancy’s and one that never existed are both 404.

Body

string

required

The civil day the goods went back, never defaulted.

object

required

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.

string

required

Your name for the act, in the one act namespace of the Tenancy.

string

required

Whoever acted, your own reference — the store’s desk, in the ordinary case.

string

required

Why, in your words. There is no reason field and no merchant field: what you want remembered goes here and in context.

object

Stored, echoed beside the fact, read by nothing.

Response

201 with the whole Loan: 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

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"

{
  "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" }
    }
  ],
  …
}

{
  "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
    }
  ],
  …
}

{
  "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"
}

API reference

Product configurations

Markets

Lookup keys

Clients

Merchants

Company profile

Credit policy

Credit decisions

Facilities

Loans

Loan actions

Receipts

Sources

Path parameters

Body

Response

Refusals

​Path parameters

​Body

​Response

​Refusals

Path parameters

Body

Response

Refusals