Close the books

At the end of a period, move the income and expense balances into equity with book.closeBooks, so those accounts start the next period at zero.

At the end of an accounting year, accountants close the books: the year's income and expenses are moved into equity (retained earnings) and the income and expense accounts return to zero. The reports for the new year then start clean, and the balance sheet shows the profit you kept. Closing does not stop you editing; it adds transactions.

Not to be confused with book.close, which closes the file.

Steps

Finish the period. Enter every transaction up to the closing date, reconcile your accounts (Reconcile an account) and run Check and repair.
Save a copy of the book first (Back up and recover). Closing adds transactions you cannot easily tell from your own.
Choose the equity accounts that take the income and the expenses; they may be one account. Create them if needed (Set up accounts).
Close with book.closeBooks: the closing date, incomeTotalAccount, expenseTotalAccount and a description. It posts, for each currency, one transaction for income and one for expenses, marked as closing transactions so reports can leave them out. A sub-account named after the currency is made under the equity account when more than one currency is closed.
Check with account.balance and asOf the closing date: the income and expense accounts are zero at the end of that day.
Save.

Run it once per period: it does not remember the date. An income or expense balance held in a security rather than a currency is refused.

Example

Example: with a copy of the reports/test-data example book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"book.closeBooks","params":{"date":"2024-03-31","incomeTotalAccount":"Root:Equity","expenseTotalAccount":"Root:Equity","description":"Close"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "transactions": [
      {
        "guid": "…",
        "kind": "income",
        "currency": "CURRENCY::USD",
        "equityAccount": "…",
        "total": {
          "num": "-257300",
          "denom": "100"
        }
      },
      "…"
    ],
    "createdAccounts": [
      "…",
      "…"
    ]
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"account.balance","params":{"account":"Root:Income","asOf":"2024-03-31"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "balances": {
      "balance": {
        "num": "0",
        "denom": "100"
      },
      "…": "…"
    },
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
book.closeBooks {"date":"2024-03-31","incomeTotalAccount":"Root:Equity","expenseTotalAccount":"Root:Equity","description":"Close"}
account.balance {"account":"Root:Income","asOf":"2024-03-31"}
EOF

It prints:

[
  {
    "transactions": [
      {
        "guid": "…",
        "kind": "income",
        "currency": "CURRENCY::USD",
        "equityAccount": "…",
        "total": {
          "num": "-257300",
          "denom": "100"
        }
      },
      "…"
    ],
    "createdAccounts": [
      "…",
      "…"
    ]
  },
  {
    "balances": {
      "balance": {
        "num": "0",
        "denom": "100"
      },
      "…": "…"
    },
    "…": "…"
  }
]

MCP tool call

Tool call:

{"name":"book.closeBooks","arguments":{"date":"2024-03-31","incomeTotalAccount":"Root:Equity","expenseTotalAccount":"Root:Equity","description":"Close"}}

Result:

{
  "structuredContent": {
    "transactions": [
      {
        "guid": "…",
        "kind": "income",
        "currency": "CURRENCY::USD",
        "equityAccount": "…",
        "total": {
          "num": "-257300",
          "denom": "100"
        }
      },
      "…"
    ],
    "createdAccounts": [
      "…",
      "…"
    ]
  }
}

Tool call:

{"name":"account.balance","arguments":{"account":"Root:Income","asOf":"2024-03-31"}}

Result:

{
  "structuredContent": {
    "balances": {
      "balance": {
        "num": "0",
        "denom": "100"
      },
      "…": "…"
    },
    "…": "…"
  }
}