Method

transaction.void

Void a transaction as GnuCash does: values kept in slots, splits zeroed and marked v.

Voids a transaction as GnuCash does: each split's value and amount are kept in slots and set to zero, the splits are marked v, and the transaction becomes read-only with notes Voided transaction. The history stays and the balances stop counting it. reason is optional.

It is refused with conflict if the transaction is already void, is read-only, or has a cleared, reconciled or frozen split; GnuCash's register silently ignores the already-void case. Undo it with transaction.unvoid.

Examples

Example: with a copy of the reports/test-data example book open as book.gnucash, at 2024-07-01T12:00:00Z.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"transaction.void","params":{"guid":"c0000000000000000000000000000000","reason":"Duplicate"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "void": true,
    "voidReason": "Duplicate",
    "voidTime": "2024-07-01T12:00:00Z",
    "readOnly": "Transaction Voided",
    "notes": "Voided transaction",
    "splits": [
      {
        "value": {
          "num": "0",
          "denom": "100"
        },
        "reconcileState": "v",
        "…": "…"
      },
      {
        "reconcileState": "v",
        "…": "…"
      }
    ],
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash transaction.void '{"guid":"c0000000000000000000000000000000","reason":"Duplicate"}'

It prints:

{
  "void": true,
  "voidReason": "Duplicate",
  "voidTime": "2024-07-01T12:00:00Z",
  "readOnly": "Transaction Voided",
  "notes": "Voided transaction",
  "splits": [
    {
      "value": {
        "num": "0",
        "denom": "100"
      },
      "reconcileState": "v",
      "…": "…"
    },
    {
      "reconcileState": "v",
      "…": "…"
    }
  ],
  "…": "…"
}

MCP tool call

Tool call:

{"name":"transaction.void","arguments":{"guid":"c0000000000000000000000000000000","reason":"Duplicate"}}

Result:

{
  "structuredContent": {
    "void": true,
    "voidReason": "Duplicate",
    "voidTime": "2024-07-01T12:00:00Z",
    "readOnly": "Transaction Voided",
    "notes": "Voided transaction",
    "splits": [
      {
        "value": {
          "num": "0",
          "denom": "100"
        },
        "reconcileState": "v",
        "…": "…"
      },
      {
        "reconcileState": "v",
        "…": "…"
      }
    ],
    "…": "…"
  }
}

Effect: write, on the Book.

Params

Params of transaction.void.

  • guid (Guid, required): The transaction's GUID.
  • reason (string): Why; empty writes no void-reason slot, as GnuCash does, and the transaction is still void.

Result

A transaction, as returned by every transaction method.

  • guid (Guid, required): The transaction's GUID.
  • currency (CommodityId, required): The transaction currency, which values are in.
  • num (string or null): Check or reference number.
  • description (string or null): Description.
  • notes (string or null): Notes.
  • datePosted (Date or null): The posted date.
  • datePostedTime (Timestamp, required): The posted instant as stored (the posted date's day-neutral time for transactions GnuCash or red-ale enters).
  • dateEntered (Timestamp, required): When it was entered.
  • void (boolean, required): Void, by GnuCash 5.17's rule: the void timestamp is set.
  • voidReason (string or null): Why it was voided.
  • voidTime (Timestamp or null): When it was voided.
  • readOnly (string or null): Why it may not be changed, when read-only (voided, or generated by a business document).
  • reversedBy (Guid or null): The transaction that reverses this one.
  • closing (boolean, required): A book-closing transaction.
  • balanced (boolean, required): The split values sum to zero; with trading accounts on, trading values and each commodity's amounts too.
  • docLink (string or null): The document link (assoc_uri slot), as stored: a URL, a file:// URI, or a path relative to the path head.
  • splits (array of SplitInfo, required): Its splits, in stored order (debits first).