Skip to main content

Service-Charge Ledger

Per-property, per-year statements of building service charges, recorded by the PM from the management company's bill and rendered as a readable breakdown with year-on-year deltas. Built for the owner-transparency story (acutely so for foreign landlords in Gulf towers, but AU strata levies fit the same model).

Model​

  • service_charge_statements — one row per (property, year), unique.
  • service_charge_lines — the category breakdown (SECURITY | CLEANING | LIFT_MAINTENANCE | COMMON_UTILITIES | RESERVE_FUND | MANAGEMENT_FEE | INSURANCE | LANDSCAPING | PEST_CONTROL | OTHER), free-text label, amount_cents, note. RLS-bound like everything else (migration V35).
  • Amounts are integer cents; the UI renders them in the agency's display currency (AUD | QAR).

Year-on-year comparison​

Computed at read time (GetServiceChargeLedger), never stored:

  • Comparison is by category, not label — "Security (main contract)" 2027 compares against "Security" 2026 even after the management company renames its line items. Multiple lines in one category are summed.
  • changePct per line + per total; null when there's no prior year.
  • unusualIncrease flags any category up more than 15% year-on-year.

API​

GET    /api/v1/service-charges?propertyId={id}         # ledger, newest year first
PUT    /api/v1/service-charges                          # upsert one year (replaces wholesale)
       { propertyId, year, note, lines: [{category, label, amountCents, note}] }
DELETE /api/v1/service-charges?propertyId={id}&year=Y

Upsert semantics: re-submitting a year replaces that year's statement and all lines — corrections are a wholesale re-entry of the sheet.

UI​

"Service charges" tab on the property detail page: per-year cards with the line table (amount, last year, change badge — red with a warning icon when flagged), plus a record/edit form (category select + label + amount rows).

Qatar's Civil Code arts. 884–900 regulate common property, cost apportionment by share, and owners associations — but standardisation is inconsistent across towers (no WEG/Dubai-style detailed strata regime; The Pearl already runs annual owner approval + reserve fund + audit, many towers don't). The ledger's positioning: not replacing the law — giving a remote owner control over their money at a distance.

Deferred​

Per-line document attachments (contractor invoices), owner-share calculation for co-owned assets, and surfacing the ledger in the owner digest.