> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nyumbazetu.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Collection strategies
> Build the dunning ladder — the ordered steps that decide what happens to an arrears case, and when.
**Finance → Collections → Strategies → `/collections/strategies`** Beta
A **strategy** (dunning ladder) is the recovery policy expressed as an ordered list of steps. It is
what makes collections repeatable: the same debt, at the same age, in the same band, gets the same
treatment regardless of which officer picks it up.
## Anatomy of a strategy
A strategy is org-scoped, named, and versioned by activation — you activate a new version rather
than editing history under in-flight cases.
Each **step** carries:
| Field | Purpose |
| --------------------------- | --------------------------------------------------------------------- |
| **Order** | Position in the ladder. |
| **Trigger after days** | Delay measured from case open, or from the previous step. |
| **Action type** | What the step does (see below). |
| **Template** | The message template rendered for reminder and letter steps. |
| **Band range** | Minimum and maximum collectability band the step applies to. |
| **Requires approval** | Whether the step routes to the approvals inbox before it can execute. |
| **Pause on active promise** | Whether an active Promise to Pay suspends this step. Default: yes. |
### Action types
| Action | What it does |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sms_reminder` | Renders a template and queues an SMS; delivery status flows back from the communications ledger. |
| `email_reminder` | The same, by email. |
| `demand_letter` | Generates a formal notice — template body plus a computed arrears schedule — as a PDF, delivered by email with optional SMS notification, tracked through issue, delivery and acknowledgement. Requires approval. |
| `iot_disconnect_link` | Hands the lease to IoT arrears enforcement. Collections never drives valves itself; the IoT engine keeps its own warn → disconnect invariants and the case mirrors its events read-only. |
| `apply_penalty` | Invokes the [penalty engine](/guides/collections/penalties) for the case's lease. The fee posts through the penalty writer as a real invoice — collections itself writes no money. |
| `handover_flag` | Marks the case handed over behind an approval and generates the handover pack: statement, communications log, interaction log and promise history. |
| `agent_task` | A workqueue item — "call this tenant" — with a due date. |
| `field_visit_task` | A workqueue item to visit the unit. The visit is recorded as an interaction. |
### Strategy-level guards
| Guard | Effect |
| ------------------------- | -------------------------------------------------------------------------------------- |
| **Max contacts per week** | Caps total contact frequency across *all* channels, counted from the interactions log. |
| **Permitted channels** | Which channels this strategy may use at all. |
| **Exit conditions** | When a case leaves the ladder. |
## Default ladder (built-in)
Until someone authors a strategy, the engine is not idle — it falls back to a built-in ladder, so a
new organisation gets sensible shadow-mode recommendations from day one with no setup. The
Strategies page shows it read-only, along with whether your organisation is running it today.
| Step | Timing | Action | Pauses on an active promise |
| ---- | ------------------------------ | -------------------------------- | --------------------------- |
| 1 | When the case opens | `sms_reminder` | Yes |
| 2 | 7 days after the previous step | `email_reminder` | Yes |
| 3 | 7 days after the previous step | `agent_task` (call the resident) | No |
Guards: **max 2 contacts per week**, no band restrictions, no approval steps.
It is deliberately conservative — reminders and one human task, nothing else. There is no demand
letter, no penalty and no IoT enforcement step in the fallback: those only ever fire from a
strategy an administrator authored and activated. You cannot edit the default ladder; create a
strategy and assign it at the scope you want, and it takes over from the fallback there.
Case policy snapshots apply to the fallback too — a case opened under the default ladder carries
these steps on its snapshot, so a later product change to the built-in ladder never rewrites
in-flight cases.
## Choosing the ladder by band
Bands are the reason a strategy is not one-size-fits-all. The engine scores every case 0–100 on
arrears age, debt-to-rent, payment recency and regularity, kept vs. broken promises, contact
responsiveness and trend, then files it in a band. Bands are computed and refreshed as the case
moves — there is nowhere to create one by hand, and a case with no history starts at **C**.
| Band | Score | Meaning | Treatment |
| ----- | ------ | ------------------- | ------------------------------------------------------ |
| **A** | 80–100 | Very likely to pay | Light touch — a reminder is usually enough. |
| **B** | 60–79 | Likely to pay | Standard reminders, no pressure needed yet. |
| **C** | 40–59 | Uncertain | Follow up actively. Default band when history is thin. |
| **D** | 20–39 | Unlikely to pay | Escalate — calls, field visits, demand letters. |
| **E** | 0–19 | Least likely to pay | Full ladder through handover. |
In short:
* **A / B (likely to pay)** — light touch. A reminder and an offer to arrange payment. Escalating a
reliable payer over a one-month slip costs you the relationship and gains nothing.
* **C** — the standard ladder.
* **D / E (unlikely to pay)** — escalate faster and further: demand letter, enforcement link,
handover. These cases also float to the top of the worklist because priority weights low scores
heavily.
A step only fires for cases inside its band window — **from** the best band you want it to reach
**to** the worst. Leaving both ends on *Any* runs the step for every case.
## Which strategy applies where
Strategies are structured records, but *which* strategy applies to a given lease is a **setting**,
resolved through the standard scope chain:
```
lease → unit → block → branch → organisation → platform default
```
The most specific scope wins. This is how you run a strict ladder on one scheme and a gentler one
on another without maintaining two configurations of everything else.
Other collections settings resolved the same way:
| Setting | Controls |
| ------------------- | --------------------------------------------------------------------------------------------- |
| Minimum balance | The smallest debt that opens a case. |
| Minimum age in days | How overdue debt must be before it enters. |
| Debt scope | All debt, rent only, or utilities only. |
| Exit hysteresis | How far below the threshold a balance must fall before the case closes, so cases do not flap. |
| Enforcement mode | Shadow (stage only) or autonomous, per branch. |
| Score weights | The weighting of each scoring feature — tunable without a deployment. |
## Policy snapshots
When a case opens, the resolved strategy and thresholds are **copied onto the case**. Changing a
strategy therefore affects new cases and does not retroactively rewrite what an in-flight case was
promised. If you genuinely want an open case moved onto the new policy, use the explicit
re-baseline action — it is audited.
## Building a strategy
On paper: what happens on day 5, day 15, day 30, day 60. Ladders built directly in the UI tend
to acquire steps nobody can justify.
**Strategies → Add.** Name it for the population it serves ("Residential — standard", "SME
commercial"), not for the current month.
Set the trigger delay, action, template and band range for each. Mark severe steps as requiring
approval.
Contact cap and permitted channels. This is the control that stops a tenant receiving four
messages in a day from three different steps.
Every reminder and letter step needs a published template. See
[Templates & broadcasts](/guides/message-templates).
Set the strategy setting at the scope you want it to apply to.
For at least one full cycle, review what the engine *would* have sent before you let anything
go out.
Do not point a live strategy at an unpublished or untested template. The confirm drawer shows a
rendered preview for exactly this reason — read it once per template before the first real send.
## Assignment rules
Alongside the ladder, assignment rules decide who owns a case: manual, round-robin, by branch or
property, or by balance band. Managers get workload views so a queue is not silently piling up on
one person.