Method

transaction.reverse

Create the reversing transaction of a transaction.

Creates the reversing transaction of a transaction: a copy with every split's value and amount negated, posted on date (default today), and marks the original as reversed by it. Use it to cancel an entry while keeping both in the books, as the register's Reverse Transaction does.

It is refused with conflict if the original has already been reversed, and, unlike GnuCash, if it is void: unvoid it first. The new splits start unreconciled.

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.reverse","params":{"guid":"c0000000000000000000000000000003","date":"2024-07-01"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "description": "desc-4",
    "datePosted": "2024-07-01",
    "splits": [
      {
        "accountName": "Root:Asset:Bank",
        "value": {
          "num": "1500",
          "denom": "100"
        },
        "…": "…"
      },
      {
        "accountName": "Root:Expenses",
        "value": {
          "num": "-1500",
          "denom": "100"
        },
        "…": "…"
      }
    ],
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"transaction.reverse","params":{"guid":"c0000000000000000000000000000003"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": 2003,
    "message": "…",
    "data": {
      "help": "error/conflict"
    }
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
transaction.reverse {"guid":"c0000000000000000000000000000003","date":"2024-07-01"}
transaction.reverse {"guid":"c0000000000000000000000000000003"}
EOF

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

{
  "error": {
    "code": 2003,
    "message": "…",
    "data": {
      "help": "error/conflict"
    }
  }
}

MCP tool call

Tool call:

{"name":"transaction.reverse","arguments":{"guid":"c0000000000000000000000000000003","date":"2024-07-01"}}

Result:

{
  "structuredContent": {
    "description": "desc-4",
    "datePosted": "2024-07-01",
    "splits": [
      {
        "accountName": "Root:Asset:Bank",
        "value": {
          "num": "1500",
          "denom": "100"
        },
        "…": "…"
      },
      {
        "accountName": "Root:Expenses",
        "value": {
          "num": "-1500",
          "denom": "100"
        },
        "…": "…"
      }
    ],
    "…": "…"
  }
}

Tool call:

{"name":"transaction.reverse","arguments":{"guid":"c0000000000000000000000000000003"}}

Result:

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

Effect: write, on the Book.

Params

Params of transaction.reverse.

  • guid (Guid, required): The transaction to reverse.
  • date (Date or null): The reversing transaction's posted date; today by default, as in GnuCash's dialog.

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