Skip to content

In-depth reference

Debt & financing — in depth

Every loan field, the monthly debt ledger math, refinance events, exit settlement, and the exact debt-metric definitions the engine computes.

Debt is the second engine in the model. The operating side produces net operating income; the financing side layers a loan on top of it, and the two meet at levered cash flow — the stream your equity IRR discounts. This chapter is the complete reference for that financing side: every field you set, every number the engine derives from it, and the arithmetic in between. It is long because the engine is exact. Nothing here is a rule of thumb; every formula below is the one the calculation actually runs, month by month, from origination through payoff at sale.

If you only need to set a loan and read back the coverage, start with Debt & financing — that page is the quick tour of the Financing Terms card. Come here when you need to know why a DSCR moved when amortization kicked in, how a refinance’s proceeds were sized, or what exactly the engine subtracts from the sale price to get net proceeds to equity.

The Assumptions view; the Financing Terms card shows Sizing Basis, LTV, Loan Amount, Interest Rate, Loan Term, Amortization, I/O Period, and a Year 1 Debt engine-output block with Debt Service, DSCR, Debt Yield, and Ending Loan Balance.
Fig 01Financing Terms, right-hand card of Assumptions (⌘1). Inputs on top, engine output below. Everything under 'Year 1 Debt · Engine Output' is computed — you set the terms, the engine sizes the loan and reports the coverage.

The engine resolves debt in a deliberate order so that no number ever reads a stale input:

  1. Size the loan. A loan can carry a sizing spec instead of a hard-coded principal. The engine resolves the spec to a dollar proceeds figure first, so a scenario that stresses purchase price or rents re-sizes the debt automatically rather than leaving a stale principal behind.

  2. Run an unlevered NOI pre-pass (only when refinances exist). Net operating income is debt-independent, so the engine computes the full NOI stream once with no loans in it. That series is what a refinance sized off forward NOI reads — computing it before any debt exists is what keeps refi sizing from being circular.

  3. Resolve refinance events. Declarative refinance events become two things: a retirement month stamped on each retired loan, and a synthetic loan that originates on the refi date with resolved proceeds.

  4. Walk the monthly debt ledger. For every month of the projection, the engine advances each loan one month: accrue interest, allocate principal, charge fees, apply any draw or prepayment, and record the ending balance.

  5. Settle at sale. At the sale month the outstanding balance is paid off from the sale proceeds, any prepayment penalty is charged, and what remains flows to equity as the final levered cash flow.

The two-pass structure has one load-bearing invariant: NOI never depends on debt. Interest, amortization, fees, and refinance proceeds all sit below NOI. This is why the engine can size a refinance off forward NOI without a solver, and why stressing rents re-sizes the refi correctly for free.

The primary loan lives on Assumptions (⌘1) in the Financing Terms card — one loan, the fields most deals need, with the engine’s coverage read out below them. The deeper Debt workspace holds the full picture: the loan stack (multiple loans), per-loan advanced structure behind Inspect (rate type, index curve, accrual convention, prepayment, funding mechanic), and the Re-Finance Terms group. The split is deliberate — the sheet stays readable, the structural depth lives one click away.

The Debt workspace headline shows Total Principal (the one full-strength figure), Weighted Rate, Avg DSCR, and Min DSCR; the loan table columns are Loan, Principal, Rate, Term, Amortization, and IO.

Every field the engine consumes on a single loan. Fields marked resolved output are computed by the engine and rendered read-only — you edit the spec that drives them, not the number itself.

Field UI label What it does
principal Loan Amount / Principal Loan proceeds. A resolved output when the loan carries a sizing spec (see below); otherwise honored as entered.
annualRate Interest Rate Fixed annual rate as a decimal (0.06 = 6%). For floating loans this is the fallback base when no baseRate is set.
termMonths Loan Term (Years) The note’s term. The loan balloons (pays its remaining balance) at maturity unless a refinance retires it first.
amortizationMonths Amortization (Years) The amortization schedule length. Defaults to termMonths when omitted — i.e. a self-amortizing loan. Set it longer than the term (e.g. 360 vs 120) for a balloon structure.
interestOnlyMonths I/O Period (Years) Months of interest-only payments from origination before principal begins amortizing. 0 (default) means amortization starts in month 1.
amortizationType Amortization type FixedPayment (level payment), InterestOnly (interest every month, balance balloons at maturity), or Balloon.
originationMonth Absolute month the loan funds. Defaults to 1 (funds at close). A refinance loan originates on the refi month.
Field UI surface What it does
originationFeePercent Inspector Charged on the funded amount at origination (and on each future-funding draw in its own month). A fee, not part of DSCR coverage.
exitFeePercent Inspector Charged on the outstanding balance being repaid at maturity — not the original principal. For an amortizing loan that balance is below par. With extensions, the exit fee moves to the extended maturity.
Field UI label What it does
rateType Rate type fixed (default) or floating.
baseRate Floating base (e.g. SOFR) as a decimal.
spread Added to the base each month for floating loans.
rateFloor / rateCap Clamp the effective floating rate. The floor is applied first, then the cap, so the cap always wins on a misconfigured band.
rateResets Dated base-rate changes [{month, baseRate}]. The latest reset on or before the month wins. Ignored when an index curve is set.
indexCurveId Index curve References a model-level named rate curve. When set, the effective rate is clamp(curve, floor, cap) + spread each month; per-loan resets are ignored.
interestAccrual Interest accrual thirty360 — labeled 30/360 (rate ÷ 12), the default — or actual365CompoundActual/365 compound, which accrues on the calendar days in each month.
Field UI surface What it does
sizing Sizing Basis The Loan Sizing Basis spec — LTV, LTC, or fixed. Drives principal. See Loan sizing.
fundingMechanic Funding mechanic upfront (all proceeds day one, default), pariPassu, or equityFirst. Governs how future-funding draws split between debt and equity.
futureFundingMax Cumulative cap on future-funding (Good News Funding) draws; spend beyond it falls to equity.
extensions Inspector {count, months, feePercent} — extension options, assumed exercised. Effective maturity = term + count × months.
prepaymentPenalty Prepayment {enabled, feePercent} — labeled Off / On (early retirement). Charged on the outstanding balance when the loan retires before its extended maturity, at sale or by an early refinance.

A loan’s principal can be entered directly or sized from a spec. Sizing runs before the debt ledger initializes, so the resolved proceeds flow through equity invested, the ledger, and any refinance payoff — never a stale input.

There are three bases.

fixedprincipal is pinned. proceeds = max(0, principal). Use this when you hold a committed term sheet and want debt held constant while you stress price.

ltvPrice — loan-to-value on purchase price:

proceeds = percent × purchasePrice

where purchasePrice is the acquisition breakdown’s purchase-price line, falling back to total acquisition cost. This is the Assumptions card’s default basis (LTV of Purchase Price): you set LTV, the engine derives Loan Amount.

ltcTotalCap — loan-to-cost on a selectable set of uses. The Debt Capitalization Switch toggles which uses count toward the cost basis: purchase price, closing costs, financing costs, and misc (one-time) capital. Closing costs are legal + title + due diligence + other; misc capital is the sum of one-time capital-plan items.

The subtle case is financing costs. When financing costs are a counted use and the loan carries an origination fee, the fee is itself a percentage of proceeds, so proceeds and cost chase each other. The engine solves it in closed form rather than iterating:

P = pct · U / (1 − pct · fee)

where U is the sum of the other counted uses and fee is the origination-fee percentage. If financing costs are counted but there is no origination fee, the static financing-cost figure from the acquisition breakdown is added to U instead, and proceeds = pct × U. (The static breakdown figure and the fee-derived cost represent the same dollars, so they are never both added — that would double-count the use.)

Before any month’s interest is computed, the engine resolves that month’s effective annual rate:

  1. If the loan has a resolved monthly rate curve (from an index curve), that value wins — it is already clamped and spread-adjusted, and held flat for months past the end of the curve.
  2. Otherwise, if the loan is not floating, the rate is annualRate, unchanged.
  3. For a floating loan with no curve: start from baseRate (falling back to annualRate), apply the latest rate reset on or before the month, add spread, then apply the floor and cap — floor first, cap second.

The monthly rate used in accrual is the effective annual rate ÷ 12 under the default thirty360 convention.

For each loan, each month, the engine computes one DebtServiceRow: {payment, coveragePayment, interest, principal, balance}.

For a fully-amortizing (FixedPayment) loan, the constant monthly payment is the standard mortgage formula:

P · i · (1 + i)^n
payment = ─────────────────
(1 + i)^n − 1

where P is the principal being amortized, i is the monthly rate, and n is the number of amortizing periods. Two guards: a zero monthly rate degenerates to P / n (straight-line), and a non-positive principal or period count returns 0.

The number of amortizing periods matters when there is an interest-only window:

amortizingMonths = amortizationMonths − interestOnlyMonths

A loan with a 30-year amortization (amortizationMonths = 360) and a 2-year IO window (interestOnlyMonths = 24) sizes its level payment to amortize the principal over 336 months — so it still fully amortizes by month 360, with no surprise balloon. For a loan with no IO, this is a no-op (amortizationMonths − 0), and behavior is byte-identical to a plain amortizing loan.

  • Fixed-rate, upfront loans size the level payment once, on the original principal over amortizingMonths — a constant payment for the life of the loan.
  • Floating-rate loans and draw-mechanic loans (whose balance grows with future funding) re-amortize each month: the payment is recomputed on the current balance over the remaining amortizing periods, so a rate change or a new draw properly shifts both interest and principal.

Under thirty360 (default):

interest = priorBalance × (annualRate / 12)

Under actual365Compound (typically for floating loans), interest compounds over the calendar days in the month:

interest = priorBalance × ((1 + annualRate)^(daysInMonth / 365) − 1)

The payment is always sized on the rate/12 level-payment math; the accrual convention only governs how the payment splits between interest and principal.

Given priorBalance, the effective rate, and the month’s position in the loan:

  • During the IO window (monthInLoan ≤ interestOnlyMonths) or an InterestOnly loan: principal = 0, payment = interest.
  • During amortization: principal = max(0, levelPayment − interest), payment = levelPayment.
  • At maturity (the last term month, when no refinance suppresses it): the loan balloons — principal = priorBalance, payment = interest + priorBalance.

The ending balance is max(0, priorBalance − principal), and a residual under half a cent snaps to zero (with the rounding folded into the final payment) so a fully-amortizing loan lands exactly on 0.

Each row carries two payment figures, and the difference is the whole reason DSCR is defined the way it is:

  • payment — the full cash outflow: interest + principal (+ any maturity balloon, prepayment, or fee).
  • coveragePayment — the recurring debt service used for DSCR. It equals interest during IO, the level payment while amortizing, and it excludes the maturity balloon and any refinance payoff. A balloon is a capital event, not recurring service, so folding it into DSCR would crater the coverage ratio in the final year for no economic reason.

On top of the payment, calcLoanFees charges, in the appropriate month:

  • Origination feeinitialFunding × originationFeePercent at the origination month, plus draw × originationFeePercent for each future-funding draw in its month.
  • Exit feepriorBalance × exitFeePercent at maturity (on the balance being repaid, not par).
  • Extension feepriorBalance × extensions.feePercent at each exercise date (initial maturity, then each extension anniversary). The final extended maturity balloons instead of exercising, so it charges no extension fee.
  • Prepayment penaltypriorBalance × prepaymentPenalty.feePercent when an early refinance retires the loan strictly before its extended maturity.

Fees roll into totalDebtService = payment + fees but never into coveragePayment — so fees never touch DSCR.

Walking one month advances every loan and aggregates the deal-level debt line:

Series Meaning
debtService Total cash service including fees — the number that hits levered cash flow.
debtServiceExFees Payment only, fees stripped.
debtServiceForDscr Sum of coveragePayment — the DSCR denominator.
debtServiceInterest / debtServicePrincipal The interest / principal split, for the interest-coverage metric and the amortization roll-forward.
loanFundingProceeds Cash in from debt: a late-originating loan’s day-one funding and each future-funding draw.
loanBalance Sum of every loan’s ending balance.

An upfront loan funds its full principal in its origination month — the common case. pariPassu and equityFirst split each debt-funded capital dollar between debt and equity, and Good News Funding draws derive live from capital-plan items flagged as debt-funded. A draw enters the balance at the start of its month (so it accrues interest from that month), rides levered cash flow as funding proceeds (offsetting the capital spend that triggered it), and — for a draw-mechanic loan — triggers a re-amortization on the grown balance.

A refinance is a declarative event, not a second loan you hand-wire. Each event carries a date, which loans it retires, a sizing spec, a fees percentage, and the new loan’s terms. The engine resolves it into a payoff of the retired loans plus a synthetic loan that originates on the refi date. Multiple events chain — a later event can retire an earlier refi’s synthetic loan.

The Refinance Date defaults to the month after the retired loans’ latest maturity (as extended) — the reference convention, requiring no date arithmetic. Set an explicit date to refinance mid-hold. Retires is either all (every loan outstanding at the refi date) or a specific list.

Two methods, both rendered as read-only derived outputs:

  • fixedAmount — proceeds are pinned to a committed term sheet.
  • ntmNoiValueLtv — proceeds are sized live off forward NOI:
Value = NTM NOI ÷ Refi Cap Rate
Proceeds = Refi LTV × Value

NTM NOI at Refinance is the sum of the next twelve months’ NOI from the refi month, read from the unlevered pre-pass. When the projection tail leaves fewer than twelve months, the available months annualize (× 12 / available) — the same stub-year convention used elsewhere. The live NTM NOI is reported even for a pinned fixedAmount event, so you can see the reference value beside your committed number.

Payoff is never pre-computed — the monthly ledger simply pays the retired loans’ outstanding balance at the retirement month, so the payoff is exact under amortization, prepayments, and floating rates. The retirement month’s payoff is principal-only, charges no further interest, and is excluded from DSCR coverage.

The refinance surfaces three bookkeeping flows in the month it fires — Loan Proceeds, Retired Loan Payoff, and Refinance Fees — and the net cash to (or from) equity is:

net refi cash = proceeds − payoff − fees

A positive figure is a cash-out distribution to equity. A negative figure is an equity infusion — proceeds did not cover payoff plus fees — and it is surfaced as a Model Intelligence notice, never applied silently. Any exit or prepayment fees the retired loan owes at payoff are folded into the refinance fees.

At the sale month the loan is retired from the sale proceeds. The engine builds two cash-flow streams — unlevered and levered — that both end at the sale month.

The levered stream is:

[ −equityInvested, cashFlowAfterDebtService(1), …, cashFlowAfterDebtService(saleMonth) ]

with the net sale settlement folded into the final period. Net proceeds to equity at sale are:

netResaleProceedsAfterDebt = resale.net − loanPayoff − prepaymentPenalty

where resale.net is the gross sale price less selling costs, loanPayoff is the outstanding loan balance at the sale month (the sale-month snapshot’s loanBalance), and prepaymentPenalty is charged on any loan the sale retires before its extended maturity (balance × feePercent). A loan that has already ballooned at maturity carries a zero balance and pays no penalty — consistent with “at maturity, nothing owed.”

The unlevered stream starts from −acquisitionCost and folds in the full resale.net (no loan payoff — there is no loan in the unlevered view).

Equity invested is the engine’s levered basis:

equityInvested = acquisitionCost − initialLoanProceeds

where initialLoanProceeds is the day-one funding of every loan originating in month ≤ 1.

Every ratio guards its denominator and reports null rather than NaN or Infinity. Year-1 flow-over-stock rates annualize on a stub first year (× 12 / monthsInYear) so a mid-year close does not halve them.

Metric Definition
LTV initialLoanPrincipal ÷ acquisitionCost. Acquisition cost is the value proxy — there is no separate appraisal input.
Debt yield (headline) (Year-1 NOI × annualization) ÷ initialLoanPrincipal.
Loan constant (Year-1 recurring debt service × annualization) ÷ initialLoanPrincipal, using debtServiceForDscr (ex-fees, ex-balloon).
Positive leverage goingInCapRate > loanConstant — a boolean. Cheaper debt than the going-in yield means leverage lifts equity returns.
Peak equity The deepest point of the cumulative levered series (its trough, negated) — the most equity outstanding at any point.
Payback months The index of the first levered cash flow at which the cumulative series turns non-negative after an outflow.
DSCR (year) = NOI ÷ recurring debt service

where recurring debt service is the year’s debtServiceForDscr — the sum of monthly coverage payments, which excludes origination fees, maturity balloons, and refinance payoffs. The engine reports each hold year’s DSCR plus the average and minimum across the hold (the reversion year is excluded). DSCR is a within-period flow ratio, so it stays raw on a stub year — it is not annualized.

Metric Definition
Interest coverage NOI ÷ interest (interest only, no principal).
Debt yield (per year) year NOI ÷ loan balance at the year's first month, annualized on a stub year.
Break-even occupancy (operating expenses + total debt service) ÷ gross potential income, where GPI = PGR + retail sales rent + reimbursement revenue + misc revenue.
Return on equity cashFlowAfterDebtService ÷ current equity, where current equity = initial equity + principal amortized through the prior year end. Across a refinance, the payoff is not amortization — the net refi cash adjusts the basis instead (cash-out shrinks it, an infusion adds to it).

The bridge from operations to equity is one line, computed every month:

cashFlowAfterDebtService =
netCashFlowBeforeDebtService − debtService + loanFundingProceeds

netCashFlowBeforeDebtService is NOI − below-line expenses − TI − LC − capex. Subtracting debtService and adding back loanFundingProceeds (day-one late fundings, draws, and refi proceeds) gives the cash that actually reaches equity.

That monthly series, prefixed with −equityInvested and dated, is what the levered XIRR discounts. The dating conventions are exact:

  • t₀ is the analysis start date, carrying the equity outflow.
  • Each period’s cash flow is dated one month after that month’s start (period-end dating).
  • Discounting is actual/365: the year fraction between two dates is (end − start) / 365, so an XIRR reflects the true calendar spacing of the flows rather than assuming even periods.

The levered equity multiple is total distributions ÷ equity invested, netting each period (a negative month nets against distributions rather than being reclassified as a fresh capital call — the engine models a single equity contribution at close).

Worked example 1 — an IO→amortizing loan

Section titled “Worked example 1 — an IO→amortizing loan”

Take a $12,500,000 acquisition financed at 80% LTV of purchase price, a 6.00% fixed rate, a 10-year term, a 30-year amortization, and a 2-year interest-only period. Assume Year-1 NOI of $850,000, held flat here so the amortization effect is isolated.

Sizing. proceeds = 0.80 × 12,500,000 = $10,000,000. Equity. 12,500,000 − 10,000,000 = $2,500,000.

The IO years (months 1–24). Monthly rate = 0.06 / 12 = 0.005.

interest = 10,000,000 × 0.005 = $50,000 / month
principal = 0
payment = $50,000 / month

Annual IO debt service = 50,000 × 12 = $600,000. Because the coverage payment during IO equals interest:

DSCR (IO year) = 850,000 ÷ 600,000 = 1.42

The amortizing years (month 25 on). The level payment amortizes the full $10,000,000 over 360 − 24 = 336 months at i = 0.005:

10,000,000 × 0.005 × (1.005)^336
payment = ──────────────────────────────── ≈ $61,511 / month
(1.005)^336 − 1

The first amortizing month (month 25), where the balance is still $10,000,000:

interest = 10,000,000 × 0.005 = $50,000.00
principal = 61,511 − 50,000 = $11,511.00
balance = 10,000,000 − 11,511 = $9,988,489.00

Annual amortizing debt service = 61,511 × 12 ≈ $738,132, and now the coverage payment is the level payment:

DSCR (amortizing year) = 850,000 ÷ 738,132 = 1.15

That drop from 1.42 to 1.15 at the same NOI is exactly what the IO period buys you — coverage headroom early, at the cost of a lower ratio once principal starts amortizing. The headline debt metrics on this loan:

LTV = 10,000,000 ÷ 12,500,000 = 80.0%
Debt yield = 850,000 ÷ 10,000,000 = 8.5%
Loan constant = 600,000 ÷ 10,000,000 = 6.0% (Year-1, in IO)
Going-in cap = 850,000 ÷ 12,500,000 = 6.8%

Since the going-in cap (6.8%) exceeds the Year-1 loan constant (6.0%), the loan is positively levered — the debt earns more than it costs in Year 1.

Now take a $9,000,000 loan, 5.00% fixed, interest-only for its full 5-year (60-month) term, so its balance stays $9,000,000 throughout. A refinance retires it and re-levers off forward NOI.

Timing. With no explicit date, the refinance fires the month after maturity: 60 + 1 = month 61. The maturity balloon at month 60 is suppressed (the retirement is after maturity), so the balance carries to month 61, and month 61 is the payoff — principal-only, no interest.

Sizing (ntmNoiValueLtv), with NTM NOI of $920,000 from month 61, a refi cap of 6.50%, and refi LTV of 70%:

Value = 920,000 ÷ 0.065 = $14,153,846
Proceeds = 0.70 × 14,153,846 = $9,907,692

Fees at 1% of proceeds: 0.01 × 9,907,692 = $99,077.

Payoff is the retired loan’s outstanding balance at month 61: $9,000,000 (exactly par, because it was interest-only).

Net cash to equity:

net refi cash = 9,907,692 − 9,000,000 − 99,077 = $808,615

A positive figure, so month 61 delivers an $808,615 cash-out distribution to equity. Under the hood that month’s levered cash flow shows $9,907,692 of loan funding proceeds in, less $9,000,000 payoff and $99,077 of fees in debt service — netting to the same $808,615, on top of that month’s operating cash flow. Had proceeds fallen short of payoff plus fees, the difference would surface as an equity-infusion notice rather than a distribution. The new synthetic loan originates at month 61 with $9,907,692 of principal and begins its own accrual from there; only its recurring service (not the $9,000,000 payoff) counts toward DSCR from month 61 forward.

  • amortizationMonths defaults to termMonths. Leave it blank and you get a self-amortizing loan with no balloon. For a classic balloon, set the amortization longer than the term (e.g. 360-month amort, 120-month term).
  • The exit fee is on the payoff balance, not par. For an amortizing loan the balance at maturity is below the original principal, so the exit fee is smaller than a naive par × feePercent would suggest.
  • DSCR deliberately excludes the balloon. The final term year’s DSCR reflects recurring service only. If you want a coverage figure that includes the payoff, that is not DSCR — it is a different question the engine does not fold in.
  • principal is a resolved output when sizing is set. Editing the number directly does nothing; edit the sizing spec (LTV, LTC uses, or fixed amount). This is what lets a price-stress scenario re-size the debt automatically.
  • A refinance is never extracted. It is off by default and is a buyer choice. Turning it on is a deliberate act in the Re-Finance Terms card.
  • Extensions are assumed exercised. Effective maturity already includes count × months. To model “no extension,” zero the count in a scenario — the balloon and any exit fee move back to the stated maturity.
  • ntmNoiValueLtv refis need forward NOI. A refinance dated beyond the projection has no forward NOI to size against and will error; pin it with fixedAmount or move its date earlier.
  • NOI is debt-independent by invariant. No financing input can change NOI. If you ever see debt appearing to move NOI, that is a bug, not a feature — the entire two-pass design rests on this.

“DSCR collapsed in the last year.” Check whether you are reading the reported DSCR (which excludes the balloon) or a hand-computed one that includes it. The engine’s DSCR uses recurring coverage service only; the maturity payoff is not in it.

“DSCR dropped mid-hold for no reason.” The interest-only period ended and amortization began. Coverage service jumps from interest-only to the full level payment — Example 1 shows the exact magnitude.

“Loan amount won’t change when I type in it.” The loan carries a sizing spec, so Loan Amount is derived. Change LTV, the LTC uses, or switch Sizing Basis to fixed.

“Refinance proceeds look wrong.” They are derived: NTM NOI ÷ cap × LTV. Check the NTM NOI at Refinance the card shows against your expectation — a surprising proceeds figure almost always traces to a surprising forward NOI at the refi month.

“There’s an equity infusion I didn’t expect at the refi.” Proceeds did not cover payoff plus fees. Either the forward NOI (and thus the sized proceeds) came in low, the retired balance was higher than expected, or fees ate the margin. The Model Intelligence notice reports the exact shortfall.

“Net sale proceeds are lower than sale price minus selling costs.” The loan payoff — and any prepayment penalty on a sale before maturity — comes out too. Net to equity is resale.net − loanPayoff − prepaymentPenalty.

  • Debt & financing — the quick tour of the Financing Terms card.
  • Waterfall & promote — how the levered cash flow this chapter produces is split between LP and GP.
  • Pro forma — the annual statement where debt service, DSCR, and the levered cash flow land.