Home mortgage calculator

If the principal is not positive the task fails with invalid_input instead of inventing a quote.

What a fixed-rate home mortgage payment means and how amortization totals are built

A fixed-rate home mortgage monthly payment is the constant installment a borrower sends so that a principal P at annual nominal rate i percent is fully amortised in n months on a reducing-balance schedule. Origination fees, discount points, property taxes, and homeowner insurance are not invented: add financed fees to principal if they go into the note, otherwise leave them out. The monthly rate r is the annual percent divided by twelve hundred: r equals annual_rate divided by twelve divided by one hundred. The number of payments n is term_years times twelve, because a home mortgage is quoted in years but repaid monthly. When r is greater than zero the closed form is monthly_payment equals P times r times (1 plus r) to the n, divided by (1 plus r) to the n minus one. That identity is the standard amortizing installment lenders publish for conventional mortgages: each installment covers interest on the outstanding principal first, then reduces the balance, so the interest share falls and the principal share rises even though the cash payment never changes. When the annual rate is zero the denominator would be zero, so the calculator switches to the honest special case monthly_payment equals P divided by n. After the payment is rounded to cents, this endpoint walks the schedule in integer cents rather than multiplying the rounded payment by n and hoping the leftover pennies disappear. Each month interest is rounded from the current balance, principal is the payment minus that interest, and the last payment (or an early payoff) absorbs any remainder so total_principal, total_interest, and total_paid are the amortization totals of the note the borrower actually pays.

Input contract, the positive-principal rule, and the response shape

POST a JSON body with three required fields: principal, the financed amount as a finite number strictly greater than zero (aliases amount and loan_amount); annual_rate, the annual nominal interest as a percent such as 6.75 for six and three quarters percent per year, finite and at least zero (aliases rate and interest_rate); and term_years, the term as a positive integer number of years from one through fifty (aliases term and years). Each numeric field may arrive as a JSON number or as a numeric string. Missing fields, empty strings, non-finite values, and a negative annual_rate fail with invalid_input naming the field and are not billed. The distinctive product rule is the principal: principal must be positive. Zero, a negative amount, a boolean, or a non-numeric string never produce a fake schedule, because a mortgage with no principal is not a quote anyone can close. On success the body echoes principal, annual_rate, and term_years, and adds term_months (term_years times twelve), monthly_rate (annual_rate divided by twelve hundred), monthly_payment, payments (how many installments the walk actually posted), total_principal, total_interest, total_paid, final_payment (the last installment after rounding), and a formula string restating the amortizing identity, the zero-rate special case, and that totals come from the reducing-balance walk. Example: principal two hundred fifty thousand, annual_rate 6.75, term_years thirty yields a monthly rate of one twelfth of six and three quarters percent and a monthly payment rounded to two decimals, with amortization totals taken from three hundred sixty reducing-balance steps rather than from a single multiply. Pair the figure with your own tax and insurance table; this endpoint computes installment math only and does not emit an amortization schedule row by row.

Where a home mortgage calculator earns its keep

Educators teaching amortizing versus interest-only mortgages can seed classroom examples that fail loudly when the principal is not positive, instead of silently treating a zero or negative loan as a valid mortgage. Failed validation, including a principal that is not positive, does not consume balance. Quote tools and origination CRMs can call the same pure module from the browser for free previews and from the API when storing a scenario, guaranteeing that the monthly payment a visitor saw matches the monthly payment stored after they save a quote. Affordability worksheets already know the financed amount; posting principal, annual_rate, and term_years fills a card with monthly payment, total_principal, total_interest, and total_paid so a counselor can see whether a thirty-year quote is cheaper in cash than a fifteen-year note at a higher monthly hit. Content teams can illustrate zero-percent seller financing with annual_rate zero, where monthly_payment collapses to principal over term_months and the amortization walk reports total_interest of zero aside from rounding. Keep principal strictly positive and term_years a whole number of years, pin the rounded money fields in tests, and you get reproducible home-mortgage payments for widgets, LMS modules, and edge workers without a loan-origination stack of your own.