Penalties

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:

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.

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.

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.

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