> ## 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.
# Penalties
> Configure late-fee policies and review the assessments they produce.
**Finance → Collections → Penalties → `/penalties`** Beta
Penalties are the platform's late-fee engine: a **policy** defines when a fee applies and how much
it is; an **assessment** is the record of that policy firing against a specific overdue invoice.
The module has two tabs:
| Tab | Route | Contents |
| ----------------------- | ------------------------ | ------------------------------------------------ |
| **Penalties** | `/penalties/policies` | The policies that define late fees. |
| **Penalty Assessments** | `/penalties/assessments` | Every fee the engine assessed, with its outcome. |
Penalties sits under **Collections**, not under recurring charges, because it is debt-recovery
configuration rather than billing configuration.
## Policies
A policy answers four questions:
| Question | Field |
| ---------------------------- | --------------------------------------------------------------- |
| **When does the fee apply?** | Grace period — how many days past due before a fee is assessed. |
| **What is it charged on?** | Apply-on basis: the invoice balance, or the total balance. |
| **How much is it?** | A fixed amount, or a percentage of the basis. |
| **How often?** | Once, or per cycle while the debt remains. |
Policies also carry:
* **Scope** — the organisation, branch, block or unit the policy applies to. Resolution follows the
standard scope chain, most specific wins.
* **Penalty service type** — the service type the resulting charge is billed under. This is what
maps the fee to an income account in the chart of accounts.
* **Active flag** — policies are deactivated, not deleted, so historical assessments keep their
context.
A policy with no penalty service type set cannot post. Seed a late-fee service type for the
organisation and set it on the policy before enabling the engine — see
[Chart of accounts](/guides/chart-of-accounts).
## Assessments
Each assessment records: the case or lease, the overdue invoice that triggered it, the basis
amount, the computed fee, the policy version used, the cycle key, and whether it posted.
Assessments are **idempotent by cycle**. Running the engine twice over the same period does not
double-charge — the cycle key prevents a second assessment for the same policy, invoice and cycle.
### From assessment to invoice
When the engine posts, it writes a real penalty invoice through the standard invoice writer, using
the policy's penalty service type. That means a late fee:
* appears on the tenant's statement like any other charge;
* flows into the general ledger through the normal posting path;
* is collectable, allocatable, adjustable and refundable like any other invoice.
Penalties default to **non-VAT** (KRA tax class D) unless the service type says otherwise.
## Enabling the engine
Penalties are switched on deliberately, in this order:
One per organisation, mapped to the right income account.
Start with one policy at the branch scope. Resist per-unit policies until you have a reason.
Without it, assessments compute but cannot post.
Review the assessments the engine produces before letting it post. Compare a sample against
what you would have charged manually.
An administrator enables the penalties job. Like every scheduled job on the platform it is
individually switchable and defaults to off outside production.
The penalties job runs under the platform's master scheduler switch **and** its own job flag. If
assessments are not appearing, check both before assuming a policy problem.
## Penalties as a collections ladder step
A [strategy](/guides/collections/strategies) can include an `apply_penalty` step. When that step is
confirmed, the penalty engine is invoked scoped to the case's lease, using the same policies and
the same idempotency. Collections does not compute or post the money itself — it asks the penalty
engine to.
Because the ladder step can require approval, an organisation can keep late fees discretionary
(officer proposes, manager approves) rather than automatic.
## Waiving a fee
A penalty that should not have been charged is handled like any other incorrect invoice: raise a
credit note against it, or use the fee-waiver action on the case, which routes to approvals. See
[Adjustments](/guides/adjustments).
Do not delete a penalty invoice to reverse it. Deleting removes the ledger record; a credit note
leaves an auditable trail of what was charged and what was forgiven.
## Legacy penalty settings
Two older configurations exist on the platform: penalty fields on branch settings, and
`penalty after days` / `penalty percentage` on individual charges. Neither drives this engine. Use
penalty **policies** for anything new, and do not extend the legacy fields.
## Troubleshooting
| Symptom | Check |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| No assessments at all | Is the penalties job enabled? Is the master scheduler on? Does any invoice actually exceed the grace period? |
| Assessments exist but no invoice was created | The policy has no penalty service type, or the service type has no account mapping. |
| Fee amount looks wrong | Check the apply-on basis. Charging on total balance rather than invoice balance produces much larger fees. |
| A tenant was charged twice | Confirm the two assessments are different cycles. Within one cycle, idempotency prevents duplicates. |