Method

account.delete

Delete an account, moving or deleting its transactions and sub-account.

Deletes an account. An account with transactions needs you to say what happens to them, transactions: "delete" (whole transactions go, other accounts' splits included) or {"moveTo": <account>}; the same choices exist for a sub-account (subaccount, subaccountTransactions), of which at most one is allowed. Targets must be of the deleted account's type, and a move to an account in another commodity needs allowCommodityMismatch: true.

GnuCash's engine, given no choice, deletes the splits one by one and its imbalance scrub then adds Imbalance splits; red-ale makes you choose and never leaves an imbalance. It refuses (conflict) while a document, budget, scheduled transaction or read-only transaction uses the account.

Examples

Without a choice the delete is refused and nothing changes:

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

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"account.delete","params":{"account":"Root:Asset:Wallet"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 2001,
    "message": "…",
    "data": {
      "help": "error/invalid"
    }
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"account.delete","params":{"account":"Root:Asset:Wallet","transactions":{"moveTo":"Root:Asset:Bank"}}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "deletedAccounts": [
      "…"
    ],
    "reparented": null,
    "movedSplits": [
      "…"
    ],
    "deletedTransactions": [],
    "deletedLots": []
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
account.delete {"account":"Root:Asset:Wallet"}
account.delete {"account":"Root:Asset:Wallet","transactions":{"moveTo":"Root:Asset:Bank"}}
EOF

It fails with exit status 2, printing on standard error:

{
  "error": {
    "code": 2001,
    "message": "…",
    "data": {
      "help": "error/invalid"
    }
  }
}

MCP tool call

Tool call:

{"name":"account.delete","arguments":{"account":"Root:Asset:Wallet"}}

Result:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 2001,
      "name": "invalid",
      "message": "…",
      "data": {
        "help": "error/invalid"
      }
    }
  }
}

Tool call:

{"name":"account.delete","arguments":{"account":"Root:Asset:Wallet","transactions":{"moveTo":"Root:Asset:Bank"}}}

Result:

{
  "structuredContent": {
    "deletedAccounts": [
      "…"
    ],
    "reparented": null,
    "movedSplits": [
      "…"
    ],
    "deletedTransactions": [],
    "deletedLots": []
  }
}

Effect: destructive, on the Book.

Params

Params of account.delete.

  • account (AccountRef, required): The account. It may have at most one sub-account.
  • transactions (DisposalParam or null): Its transactions; required when it has splits.
  • subaccount (DisposalParam or null): Its sub-account; required when it has one.
  • subaccountTransactions (DisposalParam or null): The deleted sub-account's transactions (and its descendants'); required when they have splits.
  • allowCommodityMismatch (boolean): Move splits to an account in another commodity, keeping their amounts' numbers. GnuCash warns and asks.

Result

What account.delete did.

  • deletedAccounts (array of Guid, required): Accounts deleted, the account first.
  • reparented (Guid or null): The sub-account re-parented, if any.
  • movedSplits (array of Guid, required): Splits moved.
  • deletedTransactions (array of Guid, required): Transactions deleted.
  • deletedLots (array of Guid, required): Lots deleted.