create_transactions

Create MANY transactions in one atomic command (bulk entry).

INPUT — transactions is a TSV block: a header row, then one row per transaction. The HEADER DECLARES THE LAYOUT. Base form: splits are (amount, account) column PAIRS, repeated as wide as a transaction needs::

ref<TAB>date<TAB>description<TAB>amt1<TAB>acct1<TAB>amt2<TAB>acct2...
1<TAB>2026-05-21<TAB>Gas<TAB>-54.19<TAB>Assets:Checking<TAB>54.19<TAB>Expenses:Auto:Fuel

Two opt-in extensions, each activated by naming it in the header (legacy headers parse exactly as before):

• PER-SPLIT MEMOS — declare memo split columns; splits become (amount, account, memo) TRIPLES::

  ref<TAB>date<TAB>description<TAB>amt1<TAB>acct1<TAB>memo1<TAB>amt2<TAB>acct2<TAB>memo2
  1<TAB>2026-05-21<TAB>Gas<TAB>-54.19<TAB>Assets:Checking<TAB>card #4471<TAB>54.19<TAB>Expenses:Auto:Fuel

  Empty memo cells mid-row keep their tabs; a row may simply END once its last split's amount and account are present (trailing memo/qty cells are read as empty — no placeholder tabs needed, as above).

• PER-TRANSACTION NOTES — declare a notes column directly after description::

  ref<TAB>date<TAB>description<TAB>notes<TAB>amt1<TAB>acct1...

  FIELD TARGETING for statement entry: description is the clean name; notes is what the purchase WAS — interpreted, not transcribed — and is what humans see in GnuCash's double-line register; the bank leg's memo is where the RAW statement line goes (provenance, visible only in expanded split view). Prefer filling notes whenever the description alone doesn't tell the story.

• PER-TRANSACTION CURRENCY — declare a cur column after description (before or after notes); an ISO code cell sets THAT ROW's transaction currency, an empty cell keeps the book default::

  ref<TAB>date<TAB>description<TAB>cur<TAB>amt1<TAB>acct1<TAB>amt2<TAB>acct2
  1<TAB>2026-07-15<TAB>USD Card Payment<TAB>USD<TAB>-500<TAB>Assets:USD Checking<TAB>500<TAB>Liabilities:USD Card

  With cur, the row's amt cells are in that currency and must balance in it. Use it when NO leg is in the book's default currency (a USD-to-USD transfer inside a CNY book needs no invented CNY values and no qty). Splits on accounts of any OTHER commodity still need qty. The currency must already exist in the book, and cur cannot combine with an auto-fill row.

• PER-SPLIT QUANTITY — declare qty split columns for splits whose ACCOUNT commodity differs from the book default (investment shares, foreign-currency accounts)::

  ref<TAB>date<TAB>description<TAB>amt1<TAB>acct1<TAB>qty1<TAB>amt2<TAB>acct2<TAB>qty2
  1<TAB>2026-07-01<TAB>VFIFX Purchase<TAB>-505.17<TAB>Assets:Checking<TAB><TAB>505.17<TAB>Assets:401k:VFIFX<TAB>7.7936

  amount stays in the book's default currency (the transaction currency — batch never changes that); qty is the amount in the account's own commodity. An EMPTY qty cell means the account uses the default currency (quantity == amount). A non-default-commodity account with an empty qty rejects that row.

• PER-SPLIT ACTION — declare act split columns for GnuCash's typed movement tag ("Buy"/"Sell"/"Dividend" on investment legs — desktop convention; "Wire"/"ATM" on bank legs). Same group mechanics as memo/qty; empty cells skip it. Rarely needed for plain spending.

All extensions combine; when several split fields are declared, the header's FIRST group fixes their order (e.g. amt, acct, memo, qty).

AUTO-FILL — a row with NO split cells at all (ends right after description/notes) reproduces the most recent transaction with the same description — splits, memos, and quantities included — exactly like calling create_transaction without splits::

1<TAB>2026-07-01<TAB>Rent
2<TAB>2026-07-01<TAB>Netflix

Auto-filled rows are marked auto_filled_from:<guid> in the results reason column; a row whose description matches nothing rejects ("no matching transaction to auto-fill from"). Use dry_run=true to preview what a batch of auto-fills would book. Perfect for recurring monthly entries. Transaction notes are NOT copied from the source (notes are often time-bound — "first appearance, investigate" must not replicate); supply a notes cell when the new instance needs one.

• ref: YOUR correlation key per row (e.g. 1, 2, 3), unique within the batch. It is echoed back so you can match results to what you sent; the server never reuses or interprets it.

• date: ISO YYYY-MM-DD. amount/qty: decimal STRINGS (never raw JSON numbers). Each transaction needs

  =2 splits balancing to zero in the default currency. Rows may differ in width (2 splits vs 3).

• The transaction currency is always the book default — for a transaction denominated in another currency, use create_transaction with its currency parameter.

BEHAVIOR — one book-open, one atomic save:

• A STRUCTURAL error (unbalanced, unknown account, bad pairs) aborts the WHOLE batch by default; nothing is written. Pass on_error="skip" to write the good rows and reject only the bad ones.

• A duplicate rejects ONLY its row; force=True overrides all blocking duplicates (as in create_transaction). dry_run=True validates + screens without writing.

OUTPUT — a JSON envelope of two TSV tables joined by ref:

• results (always): ref, status, txn_guid, dup_count, reason. status is created | rejected | would_create (dry_run); reason is a code like duplicate_detected or the validation message.

• duplicates (only when matches exist): ref, confidence, guid, date, amount, description, signals — the columns create_transaction emits, keyed back to the offending ref. Σ(dup_count) equals the duplicates row count.

Args: transactions: The TSV block described above. force: Override ALL blocking (HIGH) duplicates this batch. dry_run: Validate + screen, write nothing. on_error: "abort" (default) or "skip" for structural errors.