book.closeBooks

Close the books: move income and expense balances into equity at a closing date, one closing transaction per currency. Not book.close.

GnuCash's Tools > Close Book: at a closing date it moves every income and expense balance into equity, one closing transaction per currency and kind, so those accounts start the next period at zero. Name the two equity accounts that take the income and the expenses (they may be the same one); a sub-account named after a currency is made under the equity account when more than one currency is closed.

The book stays open and editable. It does not mark the date anywhere, so run it once per period. An income or expense balance held in a security rather than a currency is refused with invalid, where GnuCash would book it as money.

Examples

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"
      },
      "…": "…"
    },
    "…": "…"
  }
}

Effect: write, on the Book.

Params

Params of book.closeBooks.

date (Date, required): The closing date; balances at the end of this day, local time, are closed.
incomeTotalAccount (AccountRef, required): The equity account taking the period's income (GnuCash's "Income Total").
expenseTotalAccount (AccountRef, required): The equity account taking the period's expense (GnuCash's "Expense Total"); may be the same account.
description (string): The closing transactions' description; empty by default, as in GnuCash's dialog.

Result

The result of book.closeBooks.

transactions (array of ClosingInfo, required): The closing transactions, income first.
createdAccounts (array of Guid, required): Equity accounts made for a currency.