Service Charges

The Service Charges module is the primary mechanism for collecting annual and periodic service charge contributions from leaseholders. It provides a structured workflow: create a budget, get it approved, generate per-unit demands based on apportionment, and dispatch those demands to leaseholders.

Access the module from Dashboard → Service Charges.

---

Workflow Overview

Create Budget → Approve Budget → Generate Demands → Dispatch Demands → Track Payments

1. Create a Budget — Define the total expenditure for a block for a given period, broken down into itemised line items.
2. Approve the Budget — Lock the budget and enable demand generation.
3. Generate Demands — The system calculates each leaseholder's share using their apportionment basis points and creates individual demand records.
4. Dispatch Demands — Bulk-select draft demands and mark them as dispatched. Payment details and managing agent branding are included in each demand record.
5. Track Payments — Update demand statuses (paid, partially paid, overdue) and monitor collection via the stats cards.

---

Stats Cards

At the top of the Service Charges page, four summary cards are shown:

Card	Description
Total Demanded	Sum of all demand amounts across all units
Collected	Total amount paid so far
Outstanding	Remaining balance across all active demands
Overdue	Count of demands past their due date with an unpaid balance

All figures can be filtered by block using the block selector.

---

Budgets

Creating a Budget

1. Click New Budget from the Service Charges page.
2. Select a Block from your portfolio.
3. Enter a Period Label (e.g. 2024/25).
4. Set the Period Start and Period End dates.
5. Choose an Installment Schedule:
   • Annual — one demand per unit per period
   • Half-Yearly — two demands per unit per period
   • Quarterly — four demands per unit per period
6. Add one or more Budget Line Items, each with:
   • Description (e.g. Buildings Insurance, Lift Maintenance)
   • Amount in pence (integers only — no decimal amounts)
   • Optional nominal code for accounting categorisation (e.g. 4010)
7. Click Create Budget.

The budget is saved in draft status. The total is calculated from the sum of all line items.

Approving a Budget

Open a budget in draft status and click Approve Budget. Once approved, the budget status changes to approved and demands can be generated. Approved budgets cannot be edited.

Budget Statuses

Status	Meaning
Draft	Budget is being prepared — not yet ready for demand generation
Approved	Budget is finalised — demands can be generated
Superseded	Replaced by a more recent budget for the same period

---

Demands

Generating Demands

From an approved budget's detail page, click Generate Demands. The system will:

• Iterate over every unit in the block.
• Calculate each leaseholder's share using their apportionmentBasisPoints. If basis points are not configured for a unit, the total budget is split equally across all units.
• Create one demand per unit per installment (e.g. two demands per unit for a half-yearly schedule).
• Copy the itemised budget breakdown into each demand as a line-item snapshot.
• Generate unique reference numbers (e.g. SC-2024-001) and payment references for each demand.

Demand Statuses

Status	Meaning
Draft	Generated but not yet sent to the leaseholder
Dispatched	Marked as sent to the leaseholder
Partially Paid	Some payment received, balance outstanding
Paid	Fully settled
Overdue	Past due date with an outstanding balance
Cancelled	Voided — no payment expected

Bulk Dispatch

In the Demands tab:

1. Use the checkboxes to select one or more demands in Draft status. The header checkbox selects all draft demands at once.
2. Click Dispatch (n) to mark the selected demands as dispatched.

Only draft demands can be selected for dispatch. The dispatch timestamp is recorded on each demand.

Demand Detail View

Click View on any demand row to open its detail view. This includes:

• Reference number and installment position (e.g. 1 of 2)
• Leaseholder name and contact details (snapshotted at time of demand generation)
• Amount due, amount paid, and outstanding balance
• Due date and payment reference
• Block address
• Itemised breakdown of each budget line item and its apportioned amount
• Bank payment details from the associated client money account (account name, sort code, account number, bank name)
• Managing agent name and contact details
• Dispatch timestamp and method (if dispatched)

---

Apportionment

Demand amounts are calculated using each unit's apportionmentBasisPoints. Basis points are configured per unit under Units & Leaseholders.

• Total basis points across all units in a block should sum to 10,000 (representing 100%).
• A unit with 1,500 basis points receives 15% of the total budget demand.
• If no basis points are configured, the budget is divided equally across all units in the block.

All amounts are stored and processed as integers in pence. No floating-point arithmetic is used at any stage.

---

Data & Compliance

• All service charge data is scoped to your organisation (org_id) and enforced by row-level security — no data is visible across organisations.
• All create, approve, generate, dispatch, and status-update actions are written to the audit log.
• Amounts are stored as pence integers per the Ledger Transaction Entry — Amount Field pinned specification.
• Nominal codes on budget line items support standard chart-of-accounts categorisation per the Ledger Transaction Entry — Transaction Type and Nominal Code Field pinned specification.
• Leaseholder name and email are snapshotted onto each demand at generation time, preserving a point-in-time record regardless of future contact detail changes.