Skip to main content
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:
Penalties sits under Collections, not under recurring charges, because it is debt-recovery configuration rather than billing configuration.

​
Policies

A policy answers four questions: 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.

​
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:
1

Seed a penalty service type

One per organisation, mapped to the right income account.
2

Create the policies

Start with one policy at the branch scope. Resist per-unit policies until you have a reason.
3

Set the service type on each policy

Without it, assessments compute but cannot post.
4

Run in shadow

Review the assessments the engine produces before letting it post. Compare a sample against what you would have charged manually.
5

Enable the scheduled job

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