Skip to main content

Recovery

The recovery metrics answer the question that justifies the product: what did the rule do for you? The answer is built on honest attribution — the system only calls something "recovered" if it was actually in recovery, and it tells you which step and channel last touched the debtor before the money came in.

What counts as recovery​

A recovery record is created at the moment a payment is confirmed, if the charge was in one of these situations:

  • Enrolled in a rule (rule) — an active or paused rule was working the charge.
  • Negotiated (agreement) — the charge was in an agreement.
  • Overdue without a rule (overdue_no_rule) — it was delinquent, even if outside a rule.

On-time payment, with no rule, does not count. That money would have come in anyway; adding it would inflate the number. This split by method (rule / agreement / overdue_no_rule) is what makes clear how much came from the rule's work and how much came from agreements or delinquency resolved by other means.

A partial payment also generates recovery, attributed to the amount actually paid in the partial settlement of the original charge (the remaining balance continues as a child charge and, if recovered later, generates its own record).

How attribution works​

Each recovery record stores the rule's telemetry up to the payment:

  • Last step and channel — attribution goes to the last step actually sent (sent, delivered, replied, or converted) before the payment, along with the channel used. It is a deliberately simple, verifiable last-touch model: no splitting credit across touches by heuristic.
  • Steps executed — how many steps the rule ran before converting (measures effort per recovery).
  • Days overdue at payment — calculated directly from the dates (payment − due date), without relying on counters updated once a day.
  • Amount recovered — the amount paid (or the charge's current amount at settlement).
  • Payment origin — kobana, PSP, CNAB, or manual.

Each payment generates at most one record per charge (idempotent): webhook redeliveries do not double the number.

The available metrics​

From these records, the system calculates for the period (by default, the last 6 months; configurable from 1 to 24):

  • Total recovered — amount and number of charges.
  • Recovery rate — recovered ÷ (recovered + portfolio overdue today). A conservative reading: the denominator includes everything still overdue right now.
  • Average delay at recovery — how many days overdue, on average, charges were when paid.
  • Average steps to recover — the rule's average effort per conversion.
  • Monthly series — amount and count recovered month by month.
  • By method — how much came from rules, from agreements, and from overdue charges without a rule.
  • By channel — how much each channel (email, SMS, WhatsApp) converted as the last touch.

These metrics are available through the API (GET /api/v1/metrics/recovery) to feed your own reports.

The dashboard card​

On the dashboard, the Recovered by the rule card shows the amount recovered in the current month and the count of overdue charges paid in the month. It sits next to Received this month on purpose: the first is the outcome of the collection work; the second is all the cash that came in. The difference between the two is what would have come in on its own.

The monthly series and the recovery rate also appear as a trend chart on the dashboard (amount recovered per month), powered by GET /api/v1/metrics/recovery — useful for seeing the evolution of recovery over time, not just the current month.