transaction.update

Change a transaction's fields, currency and splits; the result must balance.

Changes a transaction: its date, description, number, notes, currency or splits. Give removeSplits (GUIDs), changeSplits (a split's guid and the fields to change) and addSplits (as in transaction.post); fields you leave out are kept. The steps run in that order and the result must balance and keep a split, or the whole call is refused and nothing changes; use transaction.delete to remove a transaction.

When a split's value changes in an account of the transaction's currency, its amount follows. Moving a split to an account of another commodity needs a new amount. A read-only transaction (voided, or before the book's auto read-only threshold) is refused with conflict. Changing the transaction's currency re-values the splits as GnuCash does, except that a split in a third commodity is multiplied by the rate rather than divided, which keeps the transaction balanced where GnuCash's result needs an Imbalance split.

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":"transaction.update","params":{"guid":"c0000000000000000000000000000005","description":"Fuel","notes":"corrected"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "guid": "c0000000000000000000000000000005",
    "description": "Fuel",
    "notes": "corrected",
    "balanced": true,
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash transaction.update '{"guid":"c0000000000000000000000000000005","description":"Fuel","notes":"corrected"}'

It prints:

{
  "guid": "c0000000000000000000000000000005",
  "description": "Fuel",
  "notes": "corrected",
  "balanced": true,
  "…": "…"
}

MCP tool call

Tool call:

{"name":"transaction.update","arguments":{"guid":"c0000000000000000000000000000005","description":"Fuel","notes":"corrected"}}

Result:

{
  "structuredContent": {
    "guid": "c0000000000000000000000000000005",
    "description": "Fuel",
    "notes": "corrected",
    "balanced": true,
    "…": "…"
  }
}

A change that unbalances the transaction is refused:

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

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"transaction.update","params":{"guid":"c0000000000000000000000000000005","changeSplits":[{"guid":"d000000000000000000000000000000b","value":"12.00"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 2002,
    "message": "…",
    "data": {
      "imbalance": "…",
      "currency": "…",
      "help": "error/unbalanced"
    }
  }
}

Command line

red-ale exec --book book.gnucash transaction.update '{"guid":"c0000000000000000000000000000005","changeSplits":[{"guid":"d000000000000000000000000000000b","value":"12.00"}]}'

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

{
  "error": {
    "code": 2002,
    "message": "…",
    "data": {
      "imbalance": "…",
      "currency": "…",
      "help": "error/unbalanced"
    }
  }
}

MCP tool call

Tool call:

{"name":"transaction.update","arguments":{"guid":"c0000000000000000000000000000005","changeSplits":[{"guid":"d000000000000000000000000000000b","value":"12.00"}]}}

Result:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 2002,
      "name": "unbalanced",
      "message": "…",
      "data": {
        "imbalance": "…",
        "currency": "…",
        "help": "error/unbalanced"
      }
    }
  }
}

Effect: write, on the Book.

Params

Params of transaction.update.

guid (Guid, required): The transaction's GUID.
currency (CommodityId or null): A new currency. Existing values are re-valued as xaccTransSetCurrency does, before the split changes.
datePosted (Date or null): A new posted date.
dateEntered (Timestamp or null): A new entered date.
num (string or null): A new num; empty clears it.
description (string or null): A new description.
notes (string or null): New notes; empty deletes them.
docLink (string or null): A new document link; empty deletes it. Refused on a read-only transaction.
removeSplits (array of Guid): Splits to remove, by GUID.
changeSplits (array of SplitChange): Splits to change.
addSplits (array of SplitParams): Splits to add.
recordPrice (boolean): Record prices from priced splits afterwards, as for transaction.post.

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).