scheduledTransaction.loan

Make a loan's repayment scheduled transaction, as GnuCash's mortgage and loan assistant does.

Makes the scheduled repayment of a loan, as GnuCash's mortgage and loan assistant does. Give the loan account (a LIABILITY), the principal, the annual rate in percent, the length, and where the money comes from and where interest goes. The result is a scheduled transaction whose formulas use pmt, ipmt and ppmt, and the fixed payment per period. Like any scheduled transaction it enters nothing until Since Last Run.

Only the financial functions that can be computed exactly are supported. red-ale refuses cpd_* and amort_*, whose results GnuCash rounds as floating point, so a rate or period count that would need them is refused.

Examples

Example: with a new, empty book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Mortgage","type":"LIABILITY","commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":3,"method":"account.create","params":{"name":"Interest","type":"EXPENSE","commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":4,"method":"scheduledTransaction.loan","params":{"loanAccount":"Mortgage","principal":"12000","rate":"6","length":{"months":12},"startDate":"2024-07-01","repayment":{"from":"Checking","interestTo":"Interest"}}}

Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "scheduledTransaction": {
      "name": "Loan",
      "schedule": [
        {
          "mult": 1,
          "periodType": "month",
          "…": "…"
        }
      ],
      "templateTransactions": [
        {
          "description": "Loan - Payment",
          "splits": [
            {
              "accountName": "Checking",
              "creditFormula": "pmt( 0.06000 / 12.00 : 12.00 : 12000.00 : 0 : 0 )",
              "…": "…"
            },
            {
              "accountName": "Mortgage",
              "debitFormula": "ppmt( 0.06000 / 12.00 : i : 12.00 : 12000.00 : 0 : 0 )",
              "…": "…"
            },
            {
              "accountName": "Interest",
              "…": "…"
            }
          ],
          "…": "…"
        }
      ],
      "…": "…"
    },
    "payment": {
      "num": "1613745557",
      "denom": "1562500"
    }
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
account.create {"name":"Checking","type":"BANK","commodity":"USD"}
account.create {"name":"Mortgage","type":"LIABILITY","commodity":"USD"}
account.create {"name":"Interest","type":"EXPENSE","commodity":"USD"}
scheduledTransaction.loan {"loanAccount":"Mortgage","principal":"12000","rate":"6","length":{"months":12},"startDate":"2024-07-01","repayment":{"from":"Checking","interestTo":"Interest"}}
EOF

It prints:

[
  "…",
  "…",
  "…",
  {
    "scheduledTransaction": {
      "name": "Loan",
      "schedule": [
        {
          "mult": 1,
          "periodType": "month",
          "…": "…"
        }
      ],
      "templateTransactions": [
        {
          "description": "Loan - Payment",
          "splits": [
            {
              "accountName": "Checking",
              "creditFormula": "pmt( 0.06000 / 12.00 : 12.00 : 12000.00 : 0 : 0 )",
              "…": "…"
            },
            {
              "accountName": "Mortgage",
              "debitFormula": "ppmt( 0.06000 / 12.00 : i : 12.00 : 12000.00 : 0 : 0 )",
              "…": "…"
            },
            {
              "accountName": "Interest",
              "…": "…"
            }
          ],
          "…": "…"
        }
      ],
      "…": "…"
    },
    "payment": {
      "num": "1613745557",
      "denom": "1562500"
    }
  }
]

MCP tool call

Tool call:

{"name":"account.create","arguments":{"name":"Checking","type":"BANK","commodity":"USD"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"account.create","arguments":{"name":"Mortgage","type":"LIABILITY","commodity":"USD"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"account.create","arguments":{"name":"Interest","type":"EXPENSE","commodity":"USD"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"scheduledTransaction.loan","arguments":{"loanAccount":"Mortgage","principal":"12000","rate":"6","length":{"months":12},"startDate":"2024-07-01","repayment":{"from":"Checking","interestTo":"Interest"}}}

Result:

{
  "structuredContent": {
    "scheduledTransaction": {
      "name": "Loan",
      "schedule": [
        {
          "mult": 1,
          "periodType": "month",
          "…": "…"
        }
      ],
      "templateTransactions": [
        {
          "description": "Loan - Payment",
          "splits": [
            {
              "accountName": "Checking",
              "creditFormula": "pmt( 0.06000 / 12.00 : 12.00 : 12000.00 : 0 : 0 )",
              "…": "…"
            },
            {
              "accountName": "Mortgage",
              "debitFormula": "ppmt( 0.06000 / 12.00 : i : 12.00 : 12000.00 : 0 : 0 )",
              "…": "…"
            },
            {
              "accountName": "Interest",
              "…": "…"
            }
          ],
          "…": "…"
        }
      ],
      "…": "…"
    },
    "payment": {
      "num": "1613745557",
      "denom": "1562500"
    }
  }
}

Effect: write, on the Book.

Params

Params of scheduledTransaction.loan.

name (string or null): The repayment's name; Loan by default.
loanAccount (AccountRef, required): The loan, a LIABILITY account.
principal (Amount, required): The principal, more than 0, in the loan account's commodity.
rate (Amount, required): The annual rate in percent, 0.001 to 100 with at most 3 decimals.
rateType (RateTypeWire): The rate's kind; simple ("Interest Rate") by default.
startDate (Date or null): The loan's start; today by default.
length (LengthParam, required): The loan's length.
monthsRemaining (integer (uint32) or null): Months still to pay; by default the length less the months from the start to today.
repayment (RepaymentParam, required): The repayment.
escrow (AccountRef or null): An escrow account the repayment goes through.
otherPayments (array of OtherPaymentParam): Other payments made as part of each repayment.

Result

The result of scheduledTransaction.loan.

scheduledTransaction (ScheduledTransactionInfo, required): The repayment scheduled transaction.
payment (Amount, required): The pmt formula's value, to 12 significant figures.