Service Charge Payments & Arrears Tracking

The Payments & Arrears module provides end-to-end management of service charge demands, payment collection, and debt write-offs across your entire portfolio. It is accessible at /dashboard/arrears.

---

Overview

The dashboard gives you a real-time view of financial health across all blocks and leaseholder units. At a glance you can see:

• Total outstanding — aggregate unpaid balance across all active demands
• Units in arrears — number of units with at least one unpaid or overdue demand
• Critical (31+ days) — units overdue by more than 30 days (RAG: Red)
• Warning (1–30 days) — units overdue within the first 30 days (RAG: Amber)

RAG Status

Each unit in arrears is assigned a Red / Amber / Green status based on the age of its oldest overdue demand:

Status	Label	Criteria
🔴 Red	Critical	Oldest overdue demand is 31+ days past due
🟡 Amber	Warning	Oldest overdue demand is 1–30 days past due
🟢 Green	Current	No overdue demands

---

Dashboard Tabs

The dashboard has three tabs, all filterable by block.

Arrears Tab

Lists every unit with an outstanding balance, sorted by RAG status. Each row shows:

• Unit number and leaseholder name
• RAG badge and block name
• Number of outstanding demands
• Days overdue (oldest demand)
• Total outstanding balance

Click any row to open the unit payment history drilldown.

Demands Tab

A paginated table of all service charge demands across the portfolio. Columns:

Column	Description
Reference	Your internal reference (e.g. SC-2024-001)
Unit	Unit number and leaseholder name
Block	Block name
Type	Demand type
Status	Current lifecycle status
Amount	Total amount demanded
Paid	Amount received to date
Outstanding	Remaining unpaid balance
Due Date	Payment due date

Payments Tab

A paginated table of all recorded payments. Columns: date, unit, block, amount, method, payment reference, demand reference, and instalment flag.

---

Creating a Demand

1. Click New Demand in the top-right toolbar.
2. Select the Block, then the Unit (units are loaded dynamically per block).
3. Set the Demand Type:
   • Service Charge
   • Ground Rent
   • Insurance Recharge
   • Ad Hoc Charge
   • Reserve Fund
4. Enter the Amount (£), an optional Reference and Description.
5. Optionally set Period Start / End, Issued Date, and Due Date.
   • Leave Issued Date blank to save the demand as a draft.
6. Click Create Demand.

Demands saved without an issued date are in draft status and will not appear as overdue until issued.

---

Recording a Payment

Payments are recorded from the unit payment history drilldown (click any arrears row).

1. Find the demand you want to pay and click Pay.
2. Enter the Amount (capped at the outstanding balance), Payment Date, and Method:
   • Bank Transfer
   • Standing Order
   • Direct Debit
   • Cheque
   • Card
   • Cash
   • Calmony
   • Other
3. Optionally enter a Reference (bank ref, cheque number, etc.).
4. Tick This is a payment plan instalment if applicable.
5. Add optional Notes and click Record Payment.

After recording, the demand's paid total, outstanding balance, and status are automatically recalculated. The demand transitions to partially_paid or paid as appropriate.

Partial payments are supported. You can record multiple payments against a single demand over time.

---

Writing Off a Debt

Write-offs are available from the unit payment history drilldown for any demand with an outstanding balance.

1. Click Write Off on the relevant demand.
2. Enter the Amount to Write Off (defaults to the full outstanding balance; partial write-offs are supported).
3. Enter a Reason — this field is mandatory for audit compliance.
4. Click Confirm Write-Off.

Write-off records are immutable once created. The reason note is permanently attached to the audit trail.

After a write-off, the demand's outstanding balance is recalculated. A demand whose full balance is written off transitions to written_off status.

---

Unit Payment History Drilldown

Clicking a unit in the Arrears tab opens a detailed view for that leaseholder:

• Summary row — total demanded, total paid, total written off, and current outstanding
• Demands — all demands for the unit with their current status, amounts, and inline actions (Pay / Write Off)
• Payment History — chronological list of all recorded payments with date, method, and reference
• Write-Offs — list of all write-off records with date and reason

---

Demand Lifecycle

draft → issued → partially_paid → paid
                              ↘ overdue
                              ↘ written_off

Status	Meaning
draft	Demand created but not yet issued
issued	Formally issued; payment is due
partially_paid	At least one payment recorded; balance remains
paid	Fully paid; no outstanding balance
overdue	Past due date with outstanding balance
written_off	Remaining balance written off

---

Access Control

• All payment recording, demand creation, and write-off actions are admin-only.
• All data is isolated per organisation via row-level security (RLS) — agents can only see their own portfolio data.
• Every mutation (payment, write-off, demand creation) is logged to the audit trail.

---

Technical Notes

• All monetary values are stored as integers in pence to avoid floating-point precision issues. The UI converts to pounds (÷ 100) for display.
• Leaseholder names are snapshotted onto demand records at creation time to preserve the audit record even if contact details change later.
• Outstanding balance is calculated as: Outstanding = amountPence − paidPence − writtenOffPence.