Loans and financing
The loans domain pack lets a model combine private or business financing agreements on one timeline. Each contract has its own terms, start period, cashflows, and balance or commitment outputs. Use one factory instance per agreement, or bind a factory template to typed rows with input.objectArray() and repeat().
The factories describe the borrower's contract cashflows. Posting account references are optional and always chosen by the model author. The pack does not infer a legal, tax, or accounting classification from the product name.
Ready loan choices
In the portal's model editor, use the loan symbol library for decisions and repayment methods:
const loanDecision = input.enum('keep', {
options: modules.loans.sym.keepSettleNewTemp('en'),
});
const repaymentMethod = input.enum('annuity', {
options: modules.loans.sym.amortMethods('en'),
});keepSettleNewTemp('en') supplies the choices Keep, Settle, New and Temporary. amortMethods('en') supplies Annuity, Straight-line, Interest-only and Fixed amortization. Pass 'sv' for Swedish labels. Connect the selected values to the plan and repayment rules in your model.
Omit the language or pass 'en' for English labels. Choice values stay the same in both languages. The symbol library, choice arrays and choice records are immutable. Supported languages are 'en' and 'sv'.
Choose a financing plan
| Need | Factory | Main outputs |
|---|---|---|
| General loan schedule, including housing, personal, student, vehicle, or business debt | loanPlan() or financing.termLoan() | Outstanding balance, interest, principal, payments, drawdowns |
| Purchase paid over time | financing.installmentPurchase() | Down-payment, financed amount, installments, optional balloon and balance |
| Vehicle, equipment, or other asset loan | financing.assetFinance() | Asset price, advance, financed amount, debt schedule |
| Credit line or overdraft | financing.revolvingCredit() | Limit, draws, repayments, utilization, available limit, interest, limit fee |
| Lease that finances an asset | financing.financialLease() | Asset purchase, debt, interest, rent, optional buyout |
| Lease measured as rent commitments | financing.operatingLease() | Rent, fees and deposits, remaining nominal commitment, optional buyout |
| Advance secured against an invoice, with optional recourse | financing.factoring() | Advance, reserve, fee, settlement and recourse payment |
| Sale of an invoice for a discounted price | financing.invoicePurchase() | Proceeds, discount, optional reserve release and recourse |
| Advance repaid from future revenue | financing.revenueBased() | Revenue holdback, repayment cap, remaining obligation |
| Fixed coupon debt | financing.bond() | Coupons, issue fee, principal redemption |
| Loan from an owner or related party | financing.shareholderLoan() | Term-loan balance and payments |
| Debt exchanged for an agreed share of equity | financing.convertibleLoan() | Outstanding debt, cash payment and converted equity |
| Owner capital paid into the business | financing.equityContribution() | Period contribution and cumulative contributed amount |
| Non-repayable grant or support | financing.grant() | Period receipt and cumulative amount received |
Choose terms that match the agreement. These are composable schedule types, not a catalogue of every jurisdiction's legal product names. A mortgage, car loan, or personal loan can use termLoan() with the appropriate amount, rate, timing, and repayment rule. Repayable aid belongs in a debt plan; a grant plan never creates a repayment obligation.
Combine repeated contracts
Give each contract family its own object array so Calculator can show the fields relevant to that family. The id remains stable in result paths while each row binds its own amount and timing.
const loanRows = input.objectArray([
{
id: input.id("bank-a"),
principal: input.money(300_000, currencies.SEK),
annualRate: input.decimal(0.06),
start: input.integer(0),
term: input.integer(36),
},
{
id: input.id("bank-b"),
principal: input.money(150_000, currencies.SEK),
annualRate: input.decimal(0.075),
start: input.integer(6),
term: input.integer(24),
},
]);
const row = loanRows.item;
const loanTemplate = financing.termLoan({
owner: company,
principal: row.data.principal,
annualRate: row.data.annualRate,
startPeriod: row.data.start,
termPeriods: row.data.term,
repayment: "annuity",
postings: { cash, liability: bankDebt, interestExpense },
});
const bankLoans = repeat(loanRows, loanTemplate.component);
return defineModel({
name: "Company funding plan",
currency: currencies.SEK,
timeline: periods.monthly({ from: "2026-01", count: 60 }),
preconditions: { loanRows },
entities: { company },
accounts: { cash, bankDebt, interestExpense },
components: { bankLoans },
});The runnable mixed financing portfolio shows repeated term loans, financial leases, and factoring contracts alongside an equity contribution and a grant. It uses one bank account and separate debt, asset, receivable, equity, income, and fee accounts.
Contract behavior
loanPlan() is the lower-level repayment engine. It supports opening debt, start- and end-period drawdowns, annual or period rates, regular and extra payments, and optional interest capitalization. termLoan() adds convenient contract periods and repayment profiles: annuity, fixed payment, fixed principal, interest-only, or bullet. A modeled projection horizon does not shorten a longer contract.
installmentPurchase() separates purchase price, down-payment, financing fee, and debt. assetFinance() uses the same debt engine and checks that the financed advance and any down-payment match the asset price. Neither plan calculates depreciation or ownership transfer.
revolvingCredit() applies a start-period draw, accrues interest, takes repayments at period end, and calculates any unused-limit fee from the remaining facility. unusedLimitFeeRate is already a model-period rate. Over-limit behavior is explicit: reject the draw or cap it at available capacity.
financialLease() records the asset and a financed balance, then applies rent and any maturity buyout through the debt schedule. If rent is omitted, a level amount is calculated to settle the balance. operatingLease() reports rents and their remaining nominal total. Indexation compounds once per model period from the lease start. Its commitment excludes fees, deposits, and an optional buyout; it is not a present value or an accounting lease liability.
factoring() pays an invoice advance and settles the reserve, fee, and selected recourse at the due period. Limited recourse is capped at the reserve; full recourse uses the modeled unpaid amount; no recourse leaves the modeled credit loss with the factor. The recourse amount is a settlement flow, not a continuing debt balance. invoicePurchase() models discounted sale proceeds, a separately configured fee, an optional reserve, and optional recourse. It creates no liability by default. Invoice amount, allocation rates, and contract periods are fixed terms; use separate rows for separate invoice agreements. unpaidAmount can vary and is read at settlement.
revenueBased() withholds a share of caller-supplied revenue until its total repayment cap reaches zero. It does not forecast revenue or accrue interest. bond() pays an annual nominal coupon converted to the model period and redeems principal at maturity. shareholderLoan() uses ordinary term-loan repayments. convertibleLoan() applies conversionShare to principal outstanding at the start of the conversion period: that portion moves to the selected equity account, current interest remains cash-serviced, and the ordinary payment can apply to any remaining debt.
equityContribution() records one capital inflow in the selected period without debt. Represent separate or staged injections as separate rows. grant() records non-repayable support as one payment by default or as equal installments in consecutive periods. The cumulative output counts receipts in the modeled horizon. For uneven grant tranches, use separate rows. Any repayable grant condition must be modeled as a separate loan or liability plan.
Standard account mappings
Pass account references in postings; a factory validates required account types and common ownership but does not select codes. Typical Swedish business mappings include:
| Posting role | Example BAS account | Example use |
|---|---|---|
cash | 1930 | Bank |
liability | 2350, 2391, 2393, 2330 | Bank debt, installment debt, related-party debt, or credit facility |
interestExpense | 8410, 8413 | Loan or account-credit interest |
feeExpense | 6570 | Bank or financing fees |
asset | 1220, 1227 | Equipment or financially leased equipment |
receivable | 1512 | Customer invoice before sale or factoring |
clearing for factoring | 2811 | Factoring settlement liability |
clearing for invoice purchase | 1680 | Retained invoice reserve asset |
equity | 2081, 2093 | Share capital or shareholder contribution |
income | 3985, 3981, 3987, 3990 | Government, EU, municipal, or other grant income |
The exact BAS account depends on the agreement and the applicable accounting policy. For example, a convertible loan can use share capital or another compatible equity account; a grant can use an account that matches its source. The factories only balance the movements selected in postings; they do not decide recognition, accrual timing, or tax treatment.
Personal account plans use the same reference interface. A personal revolving credit can map cash, liability, and interestExpense to assets.cash.bank, liabilities.credit_card, and expense.credit.consumer_interest. Personal capital can be mapped to the plan's compatible equity reference. Use stdaccount({ code, owner }) to create a reference for a standard account, or pass an existing account reference.
Timing, currencies, and boundaries
loanPlan() and revolvingCredit() can select their model calendar and require it to match the timeline. The other financing factories use monthly schedules and reject nonmonthly timelines; their period fields are monthly periods. Start drawdowns usually occur at period start, and scheduled debt payments at period end. There is no implicit daily accrual, day-count convention, foreign-exchange conversion, or hidden rounding. Money inputs within one agreement must use the model currency; mismatches fail before amounts are booked.
With postings enabled, each transaction is booked through the selected accounts and the engine derives cashflow from the selected cash account. Without postings, the same plan exposes signed cashflows without changing account balances. Account references in one posting map must have compatible types and belong to the same owner.
These contracts cover borrower-side amounts, schedules, balances, and cash movements. Tax, VAT, depreciation, accounting recognition under IFRS/K2, legal eligibility, lender credit risk, and grant conditions outside the payment schedule belong in separate model components.
Only loan.component is registered in the model. The returned fields, calculations, and flows are ordinary handles for reporting and explicit dependsOn composition. Loan callbacks may read declared inputs, external calculations, and opening accounts; they cannot read current fields or flows.
Amortization by loan-to-value ratio
repayments.loanToValue({ value, principalBase, tiers }) selects an annual amortization share from the remaining opening debt divided by the specified asset value. Each tier declares an exclusive above threshold and an annualShare. The highest crossed threshold applies; at or below the lowest threshold the share is zero. Tier order does not matter and thresholds must be unique. A small numeric tolerance keeps an exact threshold on its lower side.
The principal payment uses principalBase, which can remain the original loan amount while the remaining debt falls. Each period's payment includes interest and caps principal repayment at the current debt. Asset value and principal base accept the same readable values as other loan formulas. The tiers are explicit model assumptions, so the helper does not choose a country's statutory rules.
const payment = repayments.loanToValue({
value: homeValueAtPurchase,
principalBase: originalLoan,
tiers: [
{ above: 0.7, annualShare: 0.02 },
{ above: 0.5, annualShare: 0.01 },
],
});
const loan = loanPlan({ owner, openingBalance: originalLoan, annualRate, payment });Repeated loans and repayment choices
Use repeat(rows, loan.component) to create a loan for each editable row. The row can supply the amount, rate, repayment choice, and payment periods. Related lists can use different IDs: lookup(people.outputs.person, row.ownerId) selects the owner explicitly, and lookup(properties.column("value"), row.propertyId) selects the corresponding value. Declare those related repeats before the loans. A missing related ID raises an error; provide { fallback: sharedOwner } only when that is the intended rule.
repayments.select({ selector, cases }) chooses a named repayment formula from a string input or row field. Unknown choices raise an error. Combine it with repayments.settlement({ regular, atPeriod }) to pay the amount due at the end of the selected zero-based period and use the regular rule otherwise. Settlement includes that period's interest. An end-period drawdown occurs after settlement and remains debt for the next period.
The loan component exposes each calculation through loan.component.outputs, including interest, principalPaid and closingBalance. Its balance output is the closing-balance calculation. Flow outputs are named drawdownStartFlow, drawdownEndFlow and paymentFlow. They can be projected from repeated loans for reporting and account postings; existing returned fields and flow handles remain available.
For several tranches secured on one asset, supply the same aggregate opening debt as debtForLtv to every repayment rule and allocate principalBase between the tranches. For example, two tranches of 2,000,000 against a value of 5,000,000 use aggregate debt 4,000,000. At a two-percent tier, each tranche amortizes 40,000 per year, for 80,000 in total. Supply an independent opening-debt source that updates over time; a calculation depending on the same loan's outputs would create a dependency cycle.