Skip to content

A local-first personal finance app

[AI] Add loan functions to formulas (#8705)

youngcwbf5bcf54fcbc
diff --git a/packages/desktop-client/src/components/formula/formulaCatalog.ts b/packages/desktop-client/src/components/formula/formulaCatalog.ts
index c36ab5f691..8680076f11 100644
--- a/packages/desktop-client/src/components/formula/formulaCatalog.ts
+++ b/packages/desktop-client/src/components/formula/formulaCatalog.ts
@@ -982,6 +982,135 @@ export function getFormulaFunctionCatalog(): Record<
{ name: 'pv', description: t('Present value') },
],
},
+ IPMT: {
+ name: 'IPMT',
+ category: 'math',
+ modes: ['query', 'transaction'],
+ description: t(
+ 'Calculates the interest portion of a loan payment for a given period.',
+ ),
+ parameters: [
+ { name: 'rate', description: t('Interest rate') },
+ { name: 'period', description: t('Period to calculate (1-based)') },
+ { name: 'nper', description: t('Number of periods') },
+ { name: 'pv', description: t('Present value') },
+ ],
+ },
+ PPMT: {
+ name: 'PPMT',
+ category: 'math',
+ modes: ['query', 'transaction'],
+ description: t(
+ 'Calculates the principal portion of a loan payment for a given period.',
+ ),
+ parameters: [
+ { name: 'rate', description: t('Interest rate') },
+ { name: 'period', description: t('Period to calculate (1-based)') },
+ { name: 'nper', description: t('Number of periods') },
+ { name: 'pv', description: t('Present value') },
+ ],
+ },
+ NPER: {
+ name: 'NPER',
+ category: 'math',
+ modes: ['query', 'transaction'],
+ description: t(
+ 'Calculates the number of payment periods for a loan or investment.',
+ ),
+ parameters: [
+ { name: 'rate', description: t('Interest rate') },
+ { name: 'pmt', description: t('Payment amount') },
+ { name: 'pv', description: t('Present value') },
+ ],
+ },
+ CUMIPMT: {
+ name: 'CUMIPMT',
+ category: 'math',
+ modes: ['query', 'transaction'],
+ description: t(
+ 'Calculates cumulative interest paid between two periods.',
+ ),
+ parameters: [
+ { name: 'rate', description: t('Interest rate') },
+ { name: 'nper', description: t('Number of periods') },
+ { name: 'pv', description: t('Present value') },
+ { name: 'start_period', description: t('First period (1-based)') },
+ { name: 'end_period', description: t('Last period (1-based)') },
+ {
+ name: 'type',
+ description: t('0 = end of period, 1 = start of period'),
+ },
+ ],
+ },
+ CUMPRINC: {
+ name: 'CUMPRINC',
+ category: 'math',
+ modes: ['query', 'transaction'],
+ description: t(
+ 'Calculates cumulative principal paid between two periods.',
+ ),
+ parameters: [
+ { name: 'rate', description: t('Interest rate') },
+ { name: 'nper', description: t('Number of periods') },
+ { name: 'pv', description: t('Present value') },
+ { name: 'start_period', description: t('First period (1-based)') },
+ { name: 'end_period', description: t('Last period (1-based)') },
+ {
+ name: 'type',
+ description: t('0 = end of period, 1 = start of period'),
+ },
+ ],
+ },
+ MIRR: {
+ name: 'MIRR',
+ category: 'math',
+ modes: ['query'],
+ description: t(
+ 'Calculates the modified internal rate of return for a series of cash flows.',
+ ),
+ parameters: [
+ { name: 'values', description: t('Range of cash flow values') },
+ {
+ name: 'finance_rate',
+ description: t('Interest rate paid on financing'),
+ },
+ {
+ name: 'reinvest_rate',
+ description: t('Interest rate earned on reinvested cash flows'),
+ },
+ ],
+ },
+ XNPV: {
+ name: 'XNPV',
+ category: 'math',
+ modes: ['query'],
+ description: t(
+ 'Calculates net present value for cash flows on irregular (dated) intervals.',
+ ),
+ parameters: [
+ { name: 'rate', description: t('Discount rate') },
+ { name: 'values', description: t('Range of cash flow values') },
+ {
+ name: 'dates',
+ description: t('Range of dates matching each cash flow'),
+ },
+ ],
+ },
+ FVSCHEDULE: {
+ name: 'FVSCHEDULE',
+ category: 'math',
+ modes: ['query'],
+ description: t(
+ 'Calculates future value of a principal using a schedule of varying interest rates.',
+ ),
+ parameters: [
+ { name: 'principal', description: t('Starting principal amount') },
+ {
+ name: 'schedule',
+ description: t('Range of interest rates to apply successively'),
+ },
+ ],
+ },
QUERY: {
name: 'QUERY',
category: 'query',
diff --git a/packages/docs/docs/experimental/formulas.md b/packages/docs/docs/experimental/formulas.md
index a7f3fbfd78..a6315e2d65 100644
--- a/packages/docs/docs/experimental/formulas.md
+++ b/packages/docs/docs/experimental/formulas.md
@@ -67,6 +67,8 @@ If a function isn’t listed here, it still might work. Actual uses HyperFormula
| `COUNTBLANK` | Query | Counts empty cells. | `=COUNTBLANK(A1:A10)` | — |
| `COUNTIF` | Query | Counts cells that meet a criteria. | `=COUNTIF(A1:A10, ">0")` | — |
| `COUNTIFS` | Query | Counts cells that meet multiple criteria. | `=COUNTIFS(A1:A10, ">0", B1:B10, "<=5")` | Repeat `(range, criteria)` pairs |
+| `CUMIPMT` | Query, Rules | Calculates cumulative interest paid between two periods. | `=CUMIPMT(0.05/12, 60, 20000, 1, 12, 0)` | — |
+| `CUMPRINC` | Query, Rules | Calculates cumulative principal paid between two periods. | `=CUMPRINC(0.05/12, 60, 20000, 1, 12, 0)` | — |
| `DATE` | Query, Rules | Returns date as number of days since null date. | `=DATE(2025, 12, 16)` | — |
| `DATEDIF` | Query, Rules | Calculates distance between dates. | `=DATEDIF("2025-01-01", "2025-12-31", "D")` | — |
| `DATEVALUE` | Rules | Parses a date string and returns it as a number. | `=DATEVALUE("2025-12-16")` | — |
@@ -78,10 +80,12 @@ If a function isn’t listed here, it still might work. Actual uses HyperFormula
| `EXP` | Query | Returns e raised to the power of number. | `=EXP(1)` | — |
| `FALSE` | Query, Rules | Returns the logical value FALSE. | `=FALSE()` | — |
| `FIND` | Query, Rules | Finds text within text (case-sensitive). | `=FIND("foo", notes)` | — |
+| `FIXED` | Query, Rules | Formats a number to a fixed amount of decimal places. | `=FIXED(1234.5, 2)` | — |
| `FLOOR` | Query, Rules | Rounds down to nearest multiple of significance. | `=FLOOR(10.8, 1)` | — |
| `FORMATCURRENCY` | Query, Rules | Formats a number as currency using your app currency, number format, symbol position, and spacing settings by default. | `=FORMATCURRENCY(1234.5)` | `symbol`, `decimals`, `thousandsSeparator`, `decimalSeparator`, `symbolPosition`, `spaceBetweenAmountAndSymbol` |
| `FORMATNUMBER` | Query, Rules | Formats a number using your app number format settings by default. | `=FORMATNUMBER(1234.5, 2)` | `decimals`, `thousandsSeparator`, `decimalSeparator` |
| `FV` | Query | Calculates future value of investment. | `=FV(0.05/12, 12, -100)` | — |
+| `FVSCHEDULE` | Query | Calculates future value of a principal using a schedule of varying interest rates. | `=FVSCHEDULE(1000, {0.05;0.06;0.07})` | — |
| `HLOOKUP` | Query | Searches horizontally in first row and returns value. | `=HLOOKUP("key", A1:D10, 2, TRUE)` | — |
| `IF` | Query, Rules | Returns one value if condition is TRUE, another if FALSE. | `=IF(amount<0, "Expense", "Income")` | — |
| `IFERROR` | Query, Rules | Returns value if no error, otherwise returns alternative. | `=IFERROR(1/0, 0)` | — |
@@ -90,6 +94,7 @@ If a function isn’t listed here, it still might work. Actual uses HyperFormula
| `INDEX` | Query | Returns value at specified row and column. | `=INDEX(A1:C10, 2, 3)` | — |
| `INTEGER_TO_AMOUNT` | Query, Rules | Converts integer amount to decimal amount (e.g., 1234 -> 12.34). | `=INTEGER_TO_AMOUNT(amount, 2)` | `decimal_places` (default: 2) |
| `INT` | Rules | Rounds down to nearest integer. | `=INT(10.9)` | — |
+| `IPMT` | Query, Rules | Calculates the interest portion of a loan payment for a given period. | `=IPMT(0.05/12, 1, 60, 20000)` | — |
| `IRR` | Query | Calculates internal rate of return. | `=IRR(A1:A12)` | — |
| `ISEVEN` | Rules | Returns TRUE if number is even. | `=ISEVEN(10)` | — |
| `ISODD` | Rules | Returns TRUE if number is odd. | `=ISODD(11)` | — |
@@ -115,6 +120,7 @@ If a function isn’t listed here, it still might work. Actual uses HyperFormula
| `MID` | Query, Rules | Returns substring from specified position. | `=MID(notes, 1, 10)` | — |
| `MIN` | Query | Returns the minimum value. | `=MIN(1, 2, 3)` | Accepts more than 2 values |
| `MINA` | Query | Returns the minimum value, including text and logical values. | `=MINA(1, TRUE, "2")` | Accepts more than 2 values |
+| `MIRR` | Query | Calculates the modified internal rate of return for a series of cash flows. | `=MIRR(A1:A12, 0.1, 0.12)` | — |
| `MOD` | Query, Rules | Returns the remainder of division. | `=MOD(10, 3)` | — |
| `MODE` | Query | Returns the most frequently occurring value. | `=MODE(1, 1, 2)` | Accepts more than 2 values |
| `MONTH` | Query, Rules | Returns the month from a date. | `=MONTH(date)` | — |
@@ -122,12 +128,14 @@ If a function isn’t listed here, it still might work. Actual uses HyperFormula
| `NETWORKDAYS` | Query | Returns number of working days between dates. | `=NETWORKDAYS("2025-12-01", "2025-12-31")` | — |
| `NOT` | Query, Rules | Reverses the logical value. | `=NOT(amount<0)` | — |
| `NOW` | Query, Rules | Returns current date and time. | `=NOW()` | — |
+| `NPER` | Query, Rules | Calculates the number of payment periods for a loan or investment. | `=NPER(0.05/12, -200, 10000)` | — |
| `NPV` | Query | Calculates net present value. | `=NPV(0.1, -1000, 200, 300)` | Accepts more than 2 values |
| `OR` | Query, Rules | Returns TRUE if any argument is TRUE. | `=OR(amount<0, amount>0)` | Accepts more than 2 conditions |
| `PERCENTILE` | Query | Returns the k-th percentile. | `=PERCENTILE(A1:A100, 0.9)` | — |
| `PI` | Query | Returns the value of PI. | `=PI()` | — |
| `PMT` | Query | Calculates payment for a loan. | `=PMT(0.05/12, 60, 10000)` | — |
| `POWER` | Query, Rules | Returns base raised to the power of exponent. | `=POWER(2, 8)` | — |
+| `PPMT` | Query, Rules | Calculates the principal portion of a loan payment for a given period. | `=PPMT(0.05/12, 1, 60, 20000)` | — |
| `PROPER` | Query, Rules | Capitalizes first letter of each word. | `=PROPER(notes)` | — |
| `PRODUCT` | Query | Returns the product of all numbers. | `=PRODUCT(2, 3, 4)` | Accepts more than 2 values |
| `PV` | Query | Calculates present value of investment. | `=PV(0.05/12, 12, -100)` | — |
@@ -173,6 +181,7 @@ If a function isn’t listed here, it still might work. Actual uses HyperFormula
| `VLOOKUP` | Query | Searches vertically in first column and returns value. | `=VLOOKUP("key", A1:D10, 2, TRUE)` | — |
| `WEEKDAY` | Query, Rules | Returns day of week (1-7). | `=WEEKDAY(date, 1)` | — |
| `WEEKNUM` | Query, Rules | Returns week number of year. | `=WEEKNUM(date, 1)` | — |
+| `XNPV` | Query | Calculates net present value for cash flows on irregular (dated) intervals. | `=XNPV(0.1, A1:A5, B1:B5)` | — |
| `XOR` | Query, Rules | Returns TRUE if odd number of arguments are TRUE. | `=XOR(TRUE(), FALSE())` | Accepts more than 2 conditions |
| `YEAR` | Query, Rules | Returns the year from a date. | `=YEAR(date)` | — |
@@ -339,7 +348,13 @@ Rule formulas evaluate with named variables from the transaction context, includ
- `cleared` — Whether transaction is cleared (`TRUE` or `FALSE`)
- `reconciled` — Whether transaction is reconciled (`TRUE` or `FALSE`)
-Tip: if you want “dollars” from `amount`, use `=amount / 100`.
+:::caution Cents in, dollars out
+Numbers going **into** a formula and numbers coming **out** of one use different units.
+
+The `amount` and `balance` variables hand you integer cents, but a number your formula produces is read as **dollars** and converted to cents when Actual stores it. So a formula of `=500 + 250` sets the amount to $750.00, not $7.50.
+
+When you calculate with `amount` or `balance`, divide by 100 first so both sides are in dollars. For example, `=amount / 100 * 1.05` adds 5% to the transaction amount, while `=amount * 1.05` gives a result 100 times too large.
+:::
### Available functions
@@ -357,6 +372,18 @@ Tip: if you want “dollars” from `amount`, use `=amount / 100`.
- Returns an integer in cents. For the amount in dollars, divide by 100 or `=INTEGER_TO_AMOUNT(BALANCE_OF("Checking"))`.
- `BALANCE_OF` is also available in Formula cards, where it returns the account's current balance instead — see [Account balances with `BALANCE_OF("name")`](#account-balances-with-balance_ofname) above.
+**Loan payment functions (`IPMT`, `PPMT`, `NPER`, `CUMIPMT`, `CUMPRINC`):**
+
+If you record a loan (mortgage, auto loan, etc.) payment as a single transaction, these functions let a rule split it into interest/principal or show progress, based on the transaction's own `date`. They need a **period number**, which you can derive from the loan's start date with `DATEDIF`:
+
+```text
+=IPMT(0.05/12, DATEDIF("2024-01-01", date, "M") + 1, 360, -300000)
+```
+
+This computes the interest portion of the payment for the month of the current transaction, for a 30-year (360-month) loan that started 2024-01-01 at 5% annual interest on a $300,000 principal. Swap `IPMT` for `PPMT` to get the principal portion instead, or use `CUMIPMT`/`CUMPRINC` with a `start_period` of `1` and that same period as `end_period` to get interest/principal paid to date.
+
+Write the principal in dollars (`-300000`), not cents. These functions return their result in the same unit you pass in, and Actual expects a numeric formula result in dollars — see [Cents in, dollars out](#available-variables) above.
+
### Result types
When a rule runs, Actual converts the formula result to the field type:
@@ -365,3 +392,5 @@ When a rule runs, Actual converts the formula result to the field type:
- **date fields**: must produce a valid date
- **boolean fields**: `TRUE`/`FALSE` (or a string that equals `"true"`/`"false"`)
- **string fields**: converted with `String(...)`
+
+Number fields receive the result in dollars and store it in cents — see [Cents in, dollars out](#available-variables) above.
diff --git a/upcoming-release-notes/add-loan-formula-autocomplete.md b/upcoming-release-notes/add-loan-formula-autocomplete.md
new file mode 100644
index 0000000000..b0b2e1e180
--- /dev/null
+++ b/upcoming-release-notes/add-loan-formula-autocomplete.md
@@ -0,0 +1,6 @@
+---
+category: Enhancements
+authors: [youngcw]
+---
+
+Add autocomplete and help text for loan and investment formula functions like IPMT, PPMT, NPER, and XNPV