Skip to content
Kuberan AI Help

Mortgages

Open property → Mortgages

Overview

A mortgage tracks a secured loan against a property. The record stores lender, account number, original principal, current balance, rate, compounding, amortization, payment frequency, payment amount, and start date. One property can carry multiple mortgages — primary plus a second mortgage, a refinance, or a HELOC.

Mortgages are created, edited, and paid from the Mortgages subsection on the Property detail Overview tab — they always live in context of their property. A read-only Mortgages list (in the Properties sidebar group, at /app/books/:clientId/mortgages) shows every mortgage across the client with Lender, Property, Principal, Balance, Rate, and Status; each row links back to its property to edit, and allows delete. Creating, editing, and recording payments all happen on the property page.

UI elements

Add mortgage

Opens the New Mortgage form in a slide-over.

Record payment

Row action (shown only for Active mortgages). Opens the Record Payment dialog described below.

Fields

FieldNotes
LenderFree text.
Account #Lender’s account / reference number (free text).
Original principalLoan amount at origination.
Current balanceLive principal balance (currentPrincipalBalance) — auto-decremented by the principal portion of each recorded payment.
Interest rateAnnual interest rate (%).
CompoundingSemi-annual (Canadian residential default) or Monthly. Affects the interest split.
AmortizationAmortization period in months (default 300 = 25 years).
Payment frequencyMonthly / Semi-monthly / Bi-weekly / Weekly.
Payment amountScheduled amount per period.
Start dateOrigination / first payment date.
StatusActive / Paid off / Closed.

The journal entry posted for a payment debits the mortgage’s liability account (principal) and its interest expense account (interest). These GL accounts are stored on the mortgage record but are not yet selectable in the mortgage form — an account picker is planned for a later phase.

Payment split computation

computePaymentSplit is a pure function. Given the mortgage’s original principal, annual rate, compounding basis, payment amount, and the target payment number, it walks the amortization forward from origination to derive the principal / interest split for that payment. It works from the original terms (deterministic) rather than trusting the running currentPrincipalBalance, which manual JE adjustments could have drifted.

  • Monthly compounding: period rate = annualRate / 12.
  • Semi-annual (the Canadian convention for residential mortgages): period rate = (1 + annualRate / 2)^(1/6) − 1.

For each period, interest = balance × periodRate (rounded to cents) and principal = payment − interest, clamped so the final payment can’t overpay the remaining balance. The split math assumes a monthly payment; non-monthly frequencies are stored on the record but the per-period rate conversion is not scaled for them in the current version.

Record Payment dialog

Opens from the mortgage row’s Record payment button.

  1. Click Record payment on the mortgage row.
  2. Review the Next payment preview — the dialog shows the computed Principal, Interest, Balance after, and the payment number. These values are not editable.
  3. Confirm the Payment date (defaults to today).
  4. Enter the Cash account ID the payment came from — paste the Chart-of-Accounts account ID (a picker ships in a later phase).
  5. Click Record payment. A JE posts atomically.
Dr Mortgage liability (principal portion)
Dr Interest expense   (interest portion)
Cr Cash               (principal + interest)

The principal and interest lines carry propertyId so the Property P&L picks up the interest expense under the right property.

Idempotent counters: mortgage.paymentsMade and mortgage.currentPrincipalBalance are only updated when the JE helper reports the entry was actually new. Re-running with the same source does not double-count or double-decrement.

Auto-close: when the balance reaches 0 (clamped — it can’t go negative), the status flips to Paid off.

Bank-transaction path: a payment can also be posted by categorising a cleared bank transaction as a mortgage payment; the backend derives the cash account from the transaction’s linked bank account and posts the same JE shape.

Actions

Add a mortgage

  1. On the Property detail Overview tab, click Add mortgage.
  2. Fill lender, account number, original principal, current balance, rate, compounding, amortization, payment frequency, payment amount, and start date.
  3. Click Create mortgage.

Refinance

There is no built-in refinance flow. To model a refinance:

  1. Mark the old mortgage as Closed (status edit).
  2. Create a new mortgage with the new lender, balance, rate, and payment.
  3. Post a journal entry to square the balance transfer (Dr old mortgage liability, Cr new mortgage liability).