This file holds every Page of the red-ale Manual as Markdown, in Page ID order, each ending with its licence notice. A link whose target is a Page ID points at that Page in this file. Examples are shown as JSON-RPC requests and responses; the same call is the method of the same name through `red-ale exec` or as an MCP tool. --- # Account types The five basic kinds of Account and the Account types red-ale offers (BANK, CASH, ASSET, CREDIT, LIABILITY, STOCK, MUTUAL, CURRENCY, INCOME, EXPENSE, EQUITY, RECEIVABLE, PAYABLE, TRADING), which Account can sit under which, and what each is for. Bookkeeping groups everything into five kinds of thing: | Kind | What it is | |------|------------| | Assets | Things you own | | Liabilities | Things you owe | | Equity | Overall net worth | | Income | What increases the value of your accounts | | Expenses | What decreases it | Your bank balance is an asset, your mortgage a liability, your paycheck income and last night's dinner an expense. How the five relate is the subject of [Double entry](concept/double-entry). GnuCash divides these further into **Account types**, and every Account has exactly one. Call [`account.types`](method/account.types) for the list with each type's fundamental kind, the kind of Commodity it holds, the types it may sit under and the types it may be changed to once it has Splits. ## The types | Type | Fundamental kind | Use it for | |------|------------------|------------| | `BANK` | asset | Checking, savings and money market accounts | | `CASH` | asset | Cash in your wallet or a till | | `ASSET` | asset | Other things you own: a house, a car, prepaid items | | `RECEIVABLE` | asset | Money owed to you by customers (A/Receivable) | | `STOCK` | asset | A holding of a security. **⚠** Shares, not warehouse stock | | `MUTUAL` | asset | A holding of a mutual fund | | `CURRENCY` | asset | A holding of a foreign currency; deprecated, and cannot be chosen for a new Account | | `CREDIT` | liability | A credit card | | `LIABILITY` | liability | Other things you owe: a loan, a mortgage | | `PAYABLE` | liability | Money you owe vendors (A/Payable) | | `INCOME` | income | Salary, interest, dividends, sales | | `EXPENSE` | expense | Groceries, rent, fees | | `EQUITY` | equity | Opening balances and the owner's stake | | `TRADING` | none | Balances multi-currency Transactions; see [Trading accounts](concept/trading-accounts) | | `ROOT` | none | The nameless top of the Account tree; one per book, never created by you | **⚠** *Asset* and *liability* are also accounting ideas wider than the types of the same name: a `BANK` Account holds an asset in the first sense and is not of type `ASSET`. When this Manual means the type it writes it in capitals. ## What may sit under what An Account's parent must be compatible with its type, or [`account.create`](method/account.create) refuses it: - the asset and liability types (`BANK` to `PAYABLE` above) may share a branch with each other and sit directly under the root; - `INCOME` and `EXPENSE` may share a branch; - `EQUITY` goes under `EQUITY` or the root, and `TRADING` under `TRADING` or the root. A parent that exists only to group others is usually a placeholder: it accepts no Splits. See [The chart of accounts](concept/chart-of-accounts). ## Changing a type An Account with Splits can change only to a type compatible with its current one, for example `BANK` to `ASSET`. `RECEIVABLE` and `PAYABLE` can never change once they have Splits, because business documents depend on them. [`account.update`](method/account.update) checks the sub-accounts too when you retype them with their parent. ## Expenses and credit cards An Account of type `EXPENSE` replaces the "category" of other programs: set one up for each thing you want to track, as detailed or as general as you like, and you can move Transactions between them later. There is nothing to reconcile against, as no statement exists, though you may [reconcile](concept/reconciliation) one all the same. Its balance only grows; to see one period's spending run an [Income Statement](report/income-statement), or close the books ([Closing the books and the accounting period](concept/closing-the-books-and-accounting-period)). A credit card is a short-term loan, not an expense: the purchases are the expenses, and the card Account (`CREDIT`) holds what you owe. One payment to the card company is a transfer from your bank Account to the `CREDIT` Account. ## Related - [Double entry](concept/double-entry) - [The chart of accounts](concept/chart-of-accounts) - [account.types](method/account.types) - [account.create](method/account.create) - [account.update](method/account.update) - [Invoices and bills](guide/invoices-and-bills) - [Credit cards](guide/credit-cards) --- *red-ale Manual, `concept/account-types`. Adapted from GnuCash's documentation, `guide/ch_basics.docbook#basics-accounting52`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Books and files A Book is one set of Accounts kept in one file, XML (plain or gzipped) or SQLite. Locks, the journal, backups and retention, Book features, and which storage to choose. Database-server books are not supported. GnuCash organises data on three levels: books, accounts and transactions. One **Book** holds many Accounts, and one Account holds many Transactions. The Book is the top: one set of Accounts, with its commodities, prices, lots, scheduled transactions, budgets and business objects. A **Book file** stores one Book. You need one book for each set of accounts you keep; most people have one. ## Storage red-ale reads and writes the same files as GnuCash, so a copy of a `.gnucash` file opens in red-ale, and a book red-ale saved opens in GnuCash with nothing lost. | Format | Notes | |--------|-------| | XML, gzip-compressed | GnuCash's default. A book is rewritten whole on each save | | XML, plain | The same, readable in a text editor. A book keeps the compression it was read with; [`book.save`](method/book.save) can change it with `compressed` | | SQLite | A single file holding a database. GnuCash writes each change as it is made; red-ale writes them at `book.save`, in one SQL transaction | XML is the most established and is recommended for most people. SQLite has the benefits of SQL storage without a database server. Neither is multi-user: only one program writes a book at a time. **MySQL and PostgreSQL books are not supported.** A `mysql://` or `postgres://` path is refused with [`sql-book`](error/sql-book). In GnuCash use File > Save As to write an XML or SQLite copy, and open that. GnuCash can store an SQL book in places red-ale will not touch: if an SQLite book's schema is not GnuCash 5.17's, or it holds tables red-ale does not know, it opens read-only (see [Read-only books](concept/read-only-books)) and red-ale never upgrades a schema. ## Creating, opening, saving, closing One book is open at a time. - [`book.create`](method/book.create) makes a new, empty book (the root Account and nothing else) at a path that must be free. It is written at the first `book.save`. - [`book.open`](method/book.open) opens an existing book. `book.info` describes what you opened. - [`book.save`](method/book.save) writes it. Changes live in memory, and in the journal, until you save. - [`book.close`](method/book.close) releases the lock. It refuses to drop unsaved changes unless you say `save` or `discard`. `red-ale exec` opens, runs one method and saves for you. ## The files beside a book | File | What it is | |------|------------| | `.LCK` | The lock of an XML book: it stops two programs writing one book. GnuCash also writes a `.LNK`. SQLite books use a row of the `gnclock` table instead | | `..gnucash` | A **backup**: a complete copy of the previous file, made when a save replaces it. Restore one by opening it, then saving it under a name of your choice | | `..log` | The **journal**: every change to Transactions since the book was opened. It is not a backup of the book | - **Locks.** red-ale takes the lock when it opens a book for writing, and always releases it, also on an error. A book GnuCash or another red-ale holds is refused with [`book-locked`](error/book-locked); open it read-only to look at it. A crash can leave a `.LCK` file behind: delete it only if you know the program that made it is gone. - **Backups and the journal.** A save makes its backup first and reads the new file back to check it; a journal is started after each save. Backups and old journals are deleted after a retention period, 30 days by default (`--retention-days `, or `--keep-backups-forever`, on the command that starts red-ale). `book.save` lists what it removed. - **Recovering unsaved work.** After a crash, open the last saved book and replay its journal with [`book.replayJournal`](method/book.replayJournal). Replay restores Transactions only; changes to scheduled transactions, invoices or bills are not recovered, and Transactions created from them may no longer be tied to them, so check those. There is no autosave: save when you want to keep your changes. ## Book features A Book declares the capabilities it relies on in its `features` list (credit notes, natural-sign budgets, the split-action number field...), so that a program lacking one refuses to edit it. **⚠** A *Book feature* is not a "feature" of red-ale. red-ale keeps the list as read, adds a feature only when you use something that needs it (making a credit note, say), and opens a book read-only if it declares a feature red-ale does not implement. ## Moving between GnuCash and red-ale Use a copy of a book while you are learning, and never open the same book in both at once: whoever opens it second is told it is locked. See [Coming from GnuCash](concept/coming-from-gnucash). ## Related - [Read-only books](concept/read-only-books) - [book.create](method/book.create) - [book.open](method/book.open) - [book.info](method/book.info) - [book.save](method/book.save) - [book.close](method/book.close) - [book.replayJournal](method/book.replayJournal) - [Create, open and save a book](guide/create-open-and-save-a-book) - [Back up and recover a book](guide/back-up-and-recover) --- *red-ale Manual, `concept/books-and-files`. Adapted from GnuCash's documentation, `guide/ch_basics.docbook#basics-files1`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Budgets A Budget plans an amount per Account for each Budget period. Budget periods, set and unset amounts, natural signs, notes, actuals, estimating from past Transactions, and the budget reports. A **budget** is a tool for estimating expected income and expenses. It lets you plan how your finances should change over a period, and compare your actual Transactions to the plan. ## Kinds of budget - A *cash budget* plans receipts and disbursements: where the money comes from, where it goes, how much. - An *expense budget* plans what you spend; it ignores things like loan repayment, though it counts interest. Buying 100 of groceries on a credit card is a 100 expense; paying the card bill of 110 adds 10 of interest expense, and the repayment of the 100 is not budgeted. - A *capital budget* plans how to pay for a large future expense, with savings and borrowing. The kind is decided by which Accounts you give amounts to. Expense Accounts only make an expense budget; assets, liabilities, income and expenses together make a cash flow budget. Your Accounts must be at least as specific as your budget: you cannot budget for electricity and water separately with only `Expenses:Utilities`. ## What a Budget holds A Budget has a name, a description, a number of **Budget periods** and a Recurrence that dates them. The common periods are a month or a year; several periods in one Budget let you plan for seasons (an annual budget of 12 months, with more for heating in winter). Budget period *p* is numbered from 0. It runs from the Recurrence's *p*-th occurrence to the day before the next. **⚠** A Budget period has nothing to do with the *accounting period* of the Configuration. For each Account and period the Budget has: - a **Budget amount**: what you plan for that Account's balance to change by. Amounts are kept as written, with no rounding to the SCU; - a **Budget note**: free text. An amount is **set** or **unset**. An explicit zero is set. Only an unset amount lets a report sum the Account's children instead. **⚠** Unset is not zero, though GnuCash reads both as 0; red-ale's methods never confuse them, `null` is unset and `"0"` a set zero. A book may hold several Budgets. The one reports start from is the **default budget**, named by a book option ([`book.options`](method/book.options)); if none is named, the first. ## Natural signs Budget amounts carry the engine's sign, as the actuals do: debits positive, so an expense budget is positive, an income budget negative and a liability increase negative ([Double entry](concept/double-entry)). GnuCash has stored them so since 3.8, and the Book feature `Use natural signs in budget amounts` says a book's amounts are. **⚠** *Natural* means unreversed, not the sign a report shows. A book from before 3.8 holds Budgets without the feature and with amounts signed as the user's preference then. red-ale never converts on opening. Its budget methods that change anything refuse with `conflict` until you run [`budget.scrubSigns`](method/budget.scrubSigns), GnuCash's own scrub; [`budget.list`](method/budget.list) tells you when (`needsSignScrub`). ## Making one 1. [`budget.create`](method/budget.create) with a name, the number of periods and a Recurrence (the default: monthly from the start of this month). The first Budget in a book sets the natural-signs feature. 2. Fill in amounts with [`budget.setAmounts`](method/budget.setAmounts), by hand, all or none, for many cells at once, or 3. let [`budget.estimate`](method/budget.estimate) work them out from past Transactions: it takes a start date, looks at the same number of periods from there and stores each Account's change, rounded to a number of significant digits (`useAverage` stores the average in every period). It overwrites every period of the Accounts you name, so it is a destructive method. 4. Add notes with [`budget.setNotes`](method/budget.setNotes). [`budget.copy`](method/budget.copy) copies a Budget, [`budget.update`](method/budget.update) changes its options and [`budget.delete`](method/budget.delete) removes it. [`budget.get`](method/budget.get) returns it with its periods, amounts and notes. ## Actuals and reports The **actual** for an Account and period is what that Account and its sub-accounts did in the period: the change in its no-closing balance (Closing transactions left out), sub-accounts converted to the Account's commodity. It is computed and never stored. The [Budget Report](report/budget-report) shows the planned and actual amounts side by side for each period; the [Budget Income Statement](report/budget-income-statement) and [Budget Balance Sheet](report/budget-balance-sheet) are the statements as the budget predicts them, and the [Budget Flow](report/budget-flow) and [Budget Chart](report/budget-chart) compare them. Pick the Budget with the report's *Budget* option. See [Reports](concept/reports). ## Related - [Reports](concept/reports) - [Scheduled transactions](concept/scheduled-transactions) - [budget.create](method/budget.create) - [budget.setAmounts](method/budget.setAmounts) - [budget.setNotes](method/budget.setNotes) - [budget.estimate](method/budget.estimate) - [budget.get](method/budget.get) - [Budget Report](report/budget-report) - [Create a budget](guide/create-a-budget) --- *red-ale Manual, `concept/budgets`. Adapted from GnuCash's documentation, `guide/ch_budgets.docbook#budget_concepts1`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Business documents Owners (Customers, Vendors, Employees, Jobs) and their invoices, bills and expense vouchers - Entries, tax tables, billing terms, posting to A/Receivable or A/Payable, payments through Lots, credit notes, and printing an invoice. GnuCash has business features for customers that owe you, vendors you owe and employees you reimburse. For most people at home they are more than needed; they earn their place when many bills and receipts flow in and out and you do not want to lose track of one because you were not paid, or did not pay, at once. **GnuCash has no payroll system**: you can track payroll expenses, but calculating taxes and deductions happens outside it. ## The parts | Part | What it is | |------|------------| | Owner | Whoever a document belongs to: a Customer, a Vendor, an Employee or a Job | | Customer, Vendor, Employee | An Owner with an ID, a name, an Address and terms. Customers have a credit limit and tax settings; Employees a rate | | Job | A piece of work grouping documents for one Customer or Vendor. Optional | | Business document | An **invoice** (to a Customer), a **bill** (from a Vendor) or an **expense voucher** (from an Employee). **⚠** GnuCash's code calls all three *invoice*; red-ale says *document* for the general case | | Credit note | A document that reverses an invoice, bill or voucher of its kind: the paper that corrects what was wrongly billed or returned. Made with the same methods | | Entry | One line of a document: description, quantity, price, discount, tax | | Order | A group of Entries for one Owner, later invoiced | | Tax table | Named tax rates, each a percentage or a fixed value posted to an Account | | Billing term | When a document falls due and any early-payment discount: *days* or *proximo* | | Counter | The last number issued for a kind of document or Owner. Set a starting number with [`counter.set`](method/counter.set) | A document's **end owner**, the Customer or Vendor a Job belongs to, otherwise the Owner itself, decides its kind. Make each with its own methods: [`customer.create`](method/customer.create), [`vendor.create`](method/vendor.create), [`employee.create`](method/employee.create), [`job.create`](method/job.create), [`taxTable.create`](method/taxTable.create), [`billTerm.create`](method/billTerm.create), [`invoice.create`](method/invoice.create) with [`invoice.addEntry`](method/invoice.addEntry), [`order.create`](method/order.create). Each has `get`, `list` and `update` too. Totals are exact: [`invoice.totals`](method/invoice.totals) returns the subtotal, tax and total as printed. ## Accounts receivable and payable - **A/R**, Accounts Receivable, records sales for which you have not yet been paid: an asset, since you expect payment. Its Account type is `RECEIVABLE`. - **A/P**, Accounts Payable, records bills you have received but not yet paid: a liability. Its type is `PAYABLE`. You do not post to these Accounts yourself. Documents and payments do. ## Posting An invoice sits as a draft, with its Entries, until you **post** it with [`invoice.post`](method/invoice.post), naming the A/R (or A/P) Account, the posting date and, optionally, a due date. Posting: - makes a Transaction that credits the income Accounts of the Entries, adds the tax, and debits the A/R Account for the total (the other way round for a bill, in A/P); - makes a **Lot** in the A/R or A/P Account for the document, which later holds its payments ([Lots and capital gains](concept/lots-and-capital-gains)); - freezes copies of the document's tax tables and billing term, so editing them later does not change posted documents. A posted document cannot be edited. [`invoice.unpost`](method/invoice.unpost) reverses the posting (it deletes the posted Transaction and lot links), after which you can edit again. The Transaction a posting made is read-only. [`invoice.duplicate`](method/invoice.duplicate) copies a document to a new unposted one with the next number. ## Payments A **payment** is a Transaction that settles an Owner's open documents through their Lots. [`payment.openItems`](method/payment.openItems) lists what a payment can be applied to; [`payment.process`](method/payment.process) records a payment and applies it to chosen documents, or to all open ones; [`invoice.pay`](method/invoice.pay) pays one document. A payment bigger than the documents leaves a **pre-payment** lot, matched when the document arrives; a smaller one leaves the document partly paid. [`payment.fromTransaction`](method/payment.fromTransaction) turns an existing Transaction into a payment. [`invoice.due`](method/invoice.due) lists posted, unpaid documents falling due within a number of days. ## Printing an invoice An invoice is printed by running a report: [`report.run`](method/report.run) with the [Printable Invoice](report/printable-invoice) and its *Invoice Number* option set to the document. The Book's *Default invoice report* names the report GnuCash would run for Print Invoice; if it names a report red-ale does not have, run the Printable Invoice, as GnuCash does when the setting is not an invoice report. Company details on the invoice come from the book's *Business options* (name, address, ID, contact, phone, fax, email, URL, tax number), set with [`book.setOptions`](method/book.setOptions). See [From GnuCash: Reports menu](gnucash/reports-menu). ## Other business reports The other business reports of GnuCash - the customer, vendor and employee reports, aging, the Customer Summary, the Easy and Fancy invoices, the Tax invoice - are not part of red-ale. Write the one you need as a [User report](concept/report-scripts); the query API reads documents, Entries, Owners, Orders and billing terms. ## Related - [Account types](concept/account-types) - [Lots and capital gains](concept/lots-and-capital-gains) - [Report scripts](concept/report-scripts) - [customer.create](method/customer.create) - [vendor.create](method/vendor.create) - [invoice.create](method/invoice.create) - [invoice.post](method/invoice.post) - [payment.process](method/payment.process) - [taxTable.create](method/taxTable.create) - [billTerm.create](method/billTerm.create) - [Invoices and bills](guide/invoices-and-bills) - [Employees, vouchers and payroll](guide/employees-and-payroll) --- *red-ale Manual, `concept/business-documents`. Adapted from GnuCash's documentation, `guide/ch_bus_features.docbook#bus-intro`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # The chart of accounts The Account tree under the root Account, which GnuCash calls the chart of accounts - names, full names, placeholders, hidden Accounts, codes and how to lay one out. GnuCash calls the whole set of Accounts a book holds its **chart of accounts**; red-ale's term is the **Account tree**, the hierarchy under the root Account. Think of a table of contents for your finances: the main branches are whole groups (`Assets`, `Expenses`), the leaves are the individual bank accounts and expense categories. A summary report usually shows only the branches. An Account keeps track of what you own, owe, spend or receive. A book holds any number of them, and each can hold sub-accounts to any depth. Accounts stand for real accounts that send you statements (checking, a credit card, a loan) and for categories of money (groceries, salary). ## Names An Account has a name, unique among its siblings and never containing `:`. Its **full name** joins the names of its ancestors with `:`, leaving out the root: `Assets:Bank:Checking`. Methods take an Account as its GUID or its full name. red-ale refuses a new name containing `:`; if a book already holds one, [`account.list`](method/account.list) lists it under `nameViolations`. ## Looking at the tree - [`account.tree`](method/account.tree) returns the tree, or the part under one Account, as nested nodes. With `sorted` the siblings are in the order GnuCash displays them: by code, then type, then name. - [`account.list`](method/account.list) returns the same Accounts flat, in the order the book stores them. - [`account.get`](method/account.get) returns one. ## Placeholders, hidden Accounts and codes - A **placeholder** groups others and accepts no Splits. Make the branches of the tree placeholders so that nothing is posted to `Expenses` itself. - A **hidden** Account is kept but left out of everyday listings: use it for an Account you no longer use but whose history you keep. `excludeHidden` leaves hidden Accounts out of the listing methods. - An **Account code** is free text used to sort and number Accounts. A common scheme gives leaves codes ending in non-zero digits and their parents codes with more zeros (`1010` Checking under `1000` Assets). [`account.renumber`](method/account.renumber) numbers an Account's children in sequence. An Account also carries a description, notes, a colour, a tax-related flag, balance limits and the Accounts it remembers for roles such as dividends. [`account.update`](method/account.update) sets them, and [`account.cascade`](method/account.cascade) applies colour, placeholder or hidden to an Account and everything below it. ## Laying one out Start from the five kinds in [Account types](concept/account-types): top-level branches for `Assets`, `Liabilities`, `Income`, `Expenses` and `Equity`, with your real accounts as leaves under the first two and your categories under the rest. Keep it as detailed as you will use: Transactions can move to another Account later. red-ale has no starting-hierarchy assistant and no Account templates; build the tree with [`account.create`](method/account.create), import one (see [Importing and matching](concept/importing-and-matching)), or copy a book's tree to a new book with [`export.accounts`](method/export.accounts). ## Related - [Account types](concept/account-types) - [Transactions and Splits](concept/transactions-and-splits) - [account.tree](method/account.tree) - [account.list](method/account.list) - [account.get](method/account.get) - [account.create](method/account.create) - [Set up accounts](guide/set-up-accounts) --- *red-ale Manual, `concept/chart-of-accounts`. Adapted from GnuCash's documentation, `guide/ch_basics.docbook#basics-accounts2`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Closing the books and the accounting period The accounting period (fiscal year bounds, kept in the Configuration) and what book.closeBooks does - one closing Transaction per currency for income and for expenses, moved into equity - and why you rarely need it. Not book.close. ## The accounting period Reports and date options speak of "this year", "start of the accounting period" and so on. The **accounting period** is the start and end bounds that those mean, plus a **fiscal year end** (a month and day). Each bound is a relative choice (`year`, `previous-quarter`, `start of this month`, ...) or a date. **⚠** *Accounting period* means a configured pair of bounds, not a general period of time such as a month or quarter. It has nothing to do with a [Budget period](concept/budgets). It is a preference of the person running red-ale, kept in the Configuration (`accountingPeriod.start`, `.end`, `.fiscalYearEnd`) and never stored in the book; without a configured fiscal year end, red-ale uses the book's own fiscal-year-end Slot. - [`period.get`](method/period.get) reads the settings and [`period.set`](method/period.set) changes them; both are shortcuts to [`config.get`](method/config.get) and [`config.set`](method/config.set). - [`period.dates`](method/period.dates) turns a setting and a date into the first and last day. A fiscal year starts the day after the previous fiscal year ends: with a year ending 31 March, 15 July 2024 falls in 2024-04-01 to 2025-03-31. Day boundaries are local ([Dates and time zones](concept/dates-and-time-zones)). ## Closing the books **Closing the books** zeroes the income and expense Accounts at a date by moving their balances into equity. [`book.closeBooks`](method/book.closeBooks) does what GnuCash's Close Book assistant does, in one step, given: - `date`, the closing date; - `incomeTotalAccount` and `expenseTotalAccount`, `EQUITY` Accounts that take the income and the expense (they may be the same Account); - an optional `description` for the Transactions. For income, then for expenses, it makes **one closing Transaction per currency**. Each has a Split in every income (or expense) Account of that currency with the balance as of the end of the closing day, reversed, and one equity Split with their total. When a currency's total does not fit the chosen Account it goes to a sub-account named after the currency's mnemonic, made if need be. A **closing Transaction** carries the slot `book_closing`, which reports can leave out. Accounts with a zero balance are skipped. With no balances nothing is made and the call succeeds. **⚠** This is not [`book.close`](method/book.close), which closes the Session. After `book.closeBooks` the book stays open and editable. ### What it does not do It deletes no Account and no Transaction, creates no file and hides no Account. To undo it, delete the closing Transactions. GnuCash records no closing date, so nothing else marks the book. ### Do you need it? No. GnuCash's built-in reports work out retained earnings between periods without closing, and closing makes the standard reports less useful: they do not understand closing Transactions, so it looks to them as if each Account's net income for the closed period was zero. If you close your books, be prepared for inaccuracies in the standard reports of closed periods. On the other hand the Account tree then shows current-period income and expense figures. ## Related - [Dates and time zones](concept/dates-and-time-zones) - [The Configuration](concept/configuration) - [Account types](concept/account-types) - [book.closeBooks](method/book.closeBooks) - [period.get](method/period.get) - [period.set](method/period.set) - [period.dates](method/period.dates) - [Configure red-ale](guide/configure-red-ale) --- *red-ale Manual, `concept/closing-the-books-and-accounting-period`. Adapted from GnuCash's documentation, `manual/ch_Tools_Assistants.docbook#tool-close-book-workings`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Coming from GnuCash What changes if you know GnuCash - no windows, registers or menus, only methods - and GnuCash's words mapped to red-ale's, how the two share books safely, accounts instead of categories, and where the From GnuCash pages are. GnuCash is personal finance software made to keep track of anything from a checkbook to a business, with investments, loans and many currencies. red-ale reimplements it *without a window*. It reads and writes GnuCash's own files, XML or SQLite, and every operation is a JSON-RPC method, also an MCP tool for AI agents and a command of `red-ale exec`. There is no assistant and no register. If you know GnuCash, this is what to expect. ## What replaces the windows | In GnuCash | In red-ale | |---|---| | Menus and dialogs | Methods. Each [From GnuCash page](gnucash/file-menu) maps a menu to its methods | | The Account tree window | [`account.tree`](method/account.tree), [`account.list`](method/account.list), [`account.balance`](method/account.balance) | | The account register | [`transaction.list`](method/transaction.list) for an Account, [`transaction.post`](method/transaction.post) to enter | | The Reconcile window | [`reconcile.start`](method/reconcile.start) and its siblings; the caller carries the ticks | | Assistants (Stock Split, Loan, Close Book, Import) | One call, or a proposal call and an apply call, for each | | Preferences | The [Configuration](concept/configuration) | | Book options (File > Properties) | [`book.options`](method/book.options), [`book.setOptions`](method/book.setOptions) | | Reports in a window | [`report.run`](method/report.run) and [`report.export`](method/report.export) | | Help | [`help.search`](method/help.search), [`help.get`](method/help.get) and this Manual | Nothing is shown or confirmed for you: a method does what it says, completely or not at all. Every change is atomic and leaves every Transaction balanced. There is no "undo" button, so write to a copy while learning. ## Sharing a book with GnuCash - **A file is a file.** Copy your `.gnucash` file, open the copy with [`book.open`](method/book.open), and GnuCash opens the result with nothing lost: anything red-ale does not understand is kept and written back unchanged. GUIDs, the order of entities and timestamps are kept as read. - **One writer at a time.** XML books use a `.LCK` file and SQLite books the `gnclock` table. red-ale refuses a book GnuCash holds ([`book-locked`](error/book-locked)) and always releases its lock. - **Backups and the journal** are made as GnuCash makes them ([Books and files](concept/books-and-files)). - **Read-only when unsure.** A book that uses a feature red-ale lacks opens read-only ([Read-only books](concept/read-only-books)). - **It does not repair on its own.** GnuCash scrubs a book as it opens it, and runs Since Last Run; red-ale changes nothing until you ask ([Imbalance, orphans and scrubs](concept/imbalance-and-scrubs)). - **SQL.** SQLite books work. MySQL and PostgreSQL books are not supported: save a copy as SQLite or XML in GnuCash first. ## Words red-ale keeps GnuCash's terms and says so where it uses a word differently. | GnuCash says | red-ale says | |---|---| | Chart of accounts | **Account tree** ([The chart of accounts](concept/chart-of-accounts)) | | Category (in other programs) | An `INCOME` or `EXPENSE` **Account** ([Double entry](concept/double-entry)) | | Amount, quantity | **Amount** is a Split's size in its Account's Commodity; **value** is its size in the Transaction currency ([Value and amount](concept/value-and-amount)) | | Preferences | The **Configuration**; a *Book option* is something else, kept in the book | | Transaction log, `.log` | **Journal** | | KVP, key-value pairs | **Slots** and **Frames** | | SX | **Scheduled transaction** | | Custom report | **Saved report configuration**; a *User report* is your own script | | Invoice (bill, voucher) | **Business document**, or invoice, bill, expense voucher | | Red line | The **auto read-only threshold** | | Currency, security | Both are **Commodities**; a currency is a Commodity in the `CURRENCY` namespace | | Close Book | `book.closeBooks`, not `book.close` ([Closing the books](concept/closing-the-books-and-accounting-period)) | | Reverse balanced accounts | A display preference. Methods always use the **raw sign**: debits positive | ## Accounts versus categories If you come from a program that uses categories, income and expenses are Accounts in GnuCash and in red-ale. Where you would have named a category, name an income or expense Account; everything you could do with a category you can do. See [Double entry](concept/double-entry). ## Not in red-ale GUI windows, registers, autocompletion, the Tip of the Day, online banking, OFX import, Finance::Quote, Python bindings, Guile scripting, the Account templates, the financial calculator, check printing, PDF export, most business reports and the tax reports are not ported. [Not in red-ale](gnucash/not-in-red-ale) says what to do instead of each. ## Finding your way Search the Manual in your own words, or by the name of a GnuCash menu item: `help.search` finds "Stock Split..." and "Reconcile". The From GnuCash pages are [File menu](gnucash/file-menu), [Accounts and Actions](gnucash/account-menu), [Transactions](gnucash/transaction-menu), [Business](gnucash/business-menu), [Tools](gnucash/tools-menu), [Stock assistants](gnucash/stock-assistants), [Import and Export](gnucash/import-and-export), [Reports](gnucash/reports-menu), [Preferences and book options](gnucash/preferences-and-book-options) and [Windows and registers](gnucash/windows-and-registers). ## Related - [Books and files](concept/books-and-files) - [Value and amount](concept/value-and-amount) - [The chart of accounts](concept/chart-of-accounts) - [The Configuration](concept/configuration) - [File menu and the New File assistant](gnucash/file-menu) - [Not in red-ale](gnucash/not-in-red-ale) - [help.search](method/help.search) - [Migrate from GnuCash](guide/migrate-from-gnucash) --- *red-ale Manual, `concept/coming-from-gnucash`. Adapted from GnuCash's documentation, `guide/ch_oview.docbook#chapter_oview`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Commodities and currencies A Commodity is anything an Account can hold - a currency or a security - named by namespace and mnemonic, with a smallest unit. The built-in ISO currencies, euro legacy currencies, display symbols and how to add a security. A **Commodity** is anything an Account can hold. A **currency** is a Commodity in the `CURRENCY` namespace (US dollars, euros). A **security** is any other Commodity: shares of a company, units of a mutual fund, a bond. **⚠** In GnuCash a currency is not a separate kind of thing; it is a Commodity, and a *security* is what the rest of the world would call a commodity. ## Naming A Commodity is identified by a **namespace** and a **mnemonic**, written `NAMESPACE::MNEMONIC`: `CURRENCY::USD`, `NASDAQ::AAPL`. The namespace is `CURRENCY` for currencies, an exchange for shares (`NASDAQ`, `NYSE`) or a name you choose. The mnemonic is the symbol within it. **⚠** The XML calls it `id`, but it is not a GUID. Methods accept a currency as `USD` or `CURRENCY::USD`. [`commodity.list`](method/commodity.list) lists them, [`commodity.namespaces`](method/commodity.namespaces) groups them, [`commodity.get`](method/commodity.get) reads one. ## Currencies GnuCash supports over two hundred currencies, from the Andorran franc to the Zimbabwe dollar. Every book has all 227 ISO 4217 currencies built in: you can use any in an Account or Transaction without defining it, and the book file stores one only when it carries quotes or other settings. [`currency.list`](method/currency.list) lists them. You cannot create or delete a currency. A currency replaced by the euro (DEM, FRF and so on) is a **euro legacy currency** with a fixed rate; [`currency.euroConvert`](method/currency.euroConvert) converts between it and the euro. Several Accounts can hold different currencies in one book: a euro account beside a dollar one. The cost of that is a conversion every time money crosses between them, which is what [Value and amount](concept/value-and-amount) and [Prices and exchange rates](concept/prices-and-exchange-rates) are about. **Report currency.** A report totals in one currency, its *Report's currency* option, which defaults to the Configuration's `reports.currency`. If your Accounts are in one currency and the reports in another, with no prices between, the reports show zeros. Set the Configuration's `defaultCurrency` and `reports.currency` to your own ([The Configuration](concept/configuration)). ## Securities [`commodity.create`](method/commodity.create) adds a security with its namespace, mnemonic, full name and `fraction`. A security must exist before an Account can hold it. The currency namespace and a namespace containing `::` are refused. A security has no price until you add one ([Prices and exchange rates](concept/prices-and-exchange-rates)). ## The smallest unit A Commodity's **smallest commodity unit** (SCU, its `fraction`) is the denominator its amounts are kept in: 100 for USD (cents), 1 for JPY, 10000 for a typical share. An Account can have its own, set with `scu` when it is created. [Value and amount](concept/value-and-amount) explains the rounding. ## Symbols A Commodity shows with its **display symbol**: the symbol you chose (`userSymbol`), else the built-in symbol of the ISO table (`$`, `€`), else the mnemonic. **⚠** GnuCash calls this the "nice symbol". ## Quotes A Commodity can carry a quote flag and a quote source naming where its online prices come from. See [Prices and exchange rates](concept/prices-and-exchange-rates). ## Deleting [`commodity.delete`](method/commodity.delete) refuses a Commodity something still refers to: an Account, a Transaction, a business object, or Prices (unless you pass `deletePrices`). GnuCash lets you, and leaves dangling references; red-ale does not. ## Related - [Value and amount](concept/value-and-amount) - [Prices and exchange rates](concept/prices-and-exchange-rates) - [Investments](concept/investments) - [commodity.list](method/commodity.list) - [commodity.create](method/commodity.create) - [currency.list](method/currency.list) - [currency.euroConvert](method/currency.euroConvert) --- *red-ale Manual, `concept/commodities-and-currencies`. Adapted from GnuCash's documentation, `guide/ch_currency.docbook#currency_concepts1`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # The Configuration red-ale's own settings file, for what GnuCash keeps in preferences and user files, against Book options, which live in the book. Where it is, how to read and change a Setting by path, secrets, and the settings you are likely to want. GnuCash keeps settings in two places. *Preferences* (Edit > Preferences) belong to the person using GnuCash and are kept outside the book. **Book options** (File > Properties) belong to the book and travel with it. red-ale keeps the same split. | | Kept in | Examples | Methods | |---|---|---|---| | The **Configuration** | red-ale's own JSON settings file | Accounting period, report currency, import settings, quote services, saved report configurations, the report directory | `config.get`, `config.set`, `config.schema`, and the shortcuts `period.*` and `docLink.setPathHead` | | **Book options** | The Book, as Slots GnuCash reads | Use trading accounts, the auto read-only threshold, the split-action number field, the default budget, business details | `book.options`, `book.setOptions`, `counter.*` | **⚠** Do not call the Configuration a "preference file of the book": it never goes into a book. A preference that GnuCash holds, such as the accounting period, is in red-ale's Configuration. GUI-only preferences (window layout, register look, the Tip of the Day) have nothing to configure. ## Where it is Every red-ale process reads one Configuration file: | Started with | Configuration | |---|---| | neither option | The default file, shared by every process started this way: `~/.config/red-ale/config.json` on Linux (`$XDG_CONFIG_HOME/red-ale/config.json` if set), `~/Library/Application Support/red-ale/config.json` on macOS | | `--config ` | That file, for this process | | `--no-config` | Memory only, for this process: nothing is read or written | The file is read at every use, so a change made by hand or by another process takes effect at once. A change takes a lock on `.lock` while it reads and rewrites the file, so two processes do not lose each other's changes; the file is written whole and renamed into place, and readable by its owner only. ## Settings A **Setting** is one value of the Configuration, named by its **setting path**, the keys joined with `.`: `accountingPeriod.start`, `import.settings.matchThreshold`, `quotes.services.alphavantage.key`. Paths are typed on command lines, so there is no escaping. - [`config.schema`](method/config.schema) returns the JSON Schema of every setting: its type, default and description. `format`s such as `period-bound`, `commodity-id` and `decimal` are checked. - [`config.get`](method/config.get) reads one setting by `path`, or the whole Configuration with defaults filled in. It works with no book open. It also lists `unknown` keys in the file (typos, kept and ignored) and `problems` with values that do not match the schema. - [`config.set`](method/config.set) changes one or more by path, validated against the schema, *all or none*. Setting a path to `null` restores its default. *Example: with no book.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"config.get","params":{"path":"accountingPeriod.start"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "path": "accountingPeriod.start", "value": "year", "unknown": [], "problems": [], "configFile": null } } ``` Some Settings are owned by other methods: saved report configurations (`reports.saved`) and style sheets (`reports.styleSheets`) change only through the `report.*` methods, so `config.set` refuses them. ### Secrets and the network A **secret**, such as a quote service's API key, is never shown: `config.get` says only `{"set": true}` or `{"set": false}`, and no key appears in a result, error, log or journal. Settings that only a person may change are refused through MCP: `quotes.network`, which lets quote fetches reach the network (off by default, and the only network red-ale uses), and each quote service's `key` and `keyEnv`. Changing them over JSON-RPC, the CLI or by editing the file is allowed. A key is also tied to its service's host: pointing a service at a new host clears its key. ## Settings you are likely to want | Setting | Meaning | |---|---| | `accountingPeriod.start`, `.end`, `.fiscalYearEnd` | The accounting period ([Closing the books and the accounting period](concept/closing-the-books-and-accounting-period)) | | `reports.directory` | Where your own report scripts are ([Report scripts](concept/report-scripts)) | | `reports.currency`, `reports.dateFormat`, `reports.weekStart`, `reports.reverseBalancedAccounts`, `reports.limits.*` | What reports read where GnuCash reads a preference | | `locale` | Number, date and currency conventions (`C` by default, or a POSIX name such as `fr_FR`) | | `defaultCurrency` | GnuCash's default currency: what currencies are quoted in | | `docLinks.pathHead` | The folder relative document links start from | | `import.settings.*`, `import.csvLayouts.*`, `import.qifAccountMap` | The matcher's thresholds and saved layouts ([Importing and matching](concept/importing-and-matching)) | | `quotes.network`, `quotes.services.*`, `quotes.sources.*` | Online quotes ([Prices and exchange rates](concept/prices-and-exchange-rates)) | ## Book options [`book.options`](method/book.options) reads the options kept in the book, and [`book.setOptions`](method/book.setOptions) changes them as GnuCash's Book Options dialog does. An absent option is left alone. | Option | Meaning | |---|---| | `useTradingAccounts` | Keep multi-currency Transactions balanced through trading Accounts ([Trading accounts](concept/trading-accounts)) | | `splitActionForNum` | Use a Split's action field as its number. Turning it on adds the Book feature `Number Field Source` | | `autoReadOnlyDays` | A number of days; Transactions older than that become read-only (0 turns it off) | | `defaultBudget` | The Budget reports start from ([Budgets](concept/budgets)) | | `companyName`, `companyAddress`, `companyContactPerson`, `companyPhoneNumber`, `companyFaxNumber`, `companyEmailAddress`, `companyWebsiteUrl`, `companyId`, `taxNumber` | The business details the Printable Invoice prints | | `defaultInvoiceReport` | The invoice report Print Invoice runs | Document numbers are kept separately: **counters** hold the last number issued for each kind of document or owner (`gncInvoice`, `gncCustomer`, ...), with a format such as `%.6li`. [`counter.list`](method/counter.list) and [`counter.set`](method/counter.set) read and change them. **⚠** GnuCash's book options call a counter the *previous* number: the next ID is one more. ## Related - [Books and files](concept/books-and-files) - [Closing the books and the accounting period](concept/closing-the-books-and-accounting-period) - [Report scripts](concept/report-scripts) - [config.get](method/config.get) - [config.set](method/config.set) - [config.schema](method/config.schema) - [book.options](method/book.options) - [book.setOptions](method/book.setOptions) - [Configure red-ale](guide/configure-red-ale) --- *red-ale Manual, `concept/configuration`. Adapted from GnuCash's documentation, `manual/ch_Customize.docbook#book-options`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Dates and time zones A Date is a calendar day; a timestamp is an instant in UTC. How red-ale stores a posted date, which time zone defines "today" and where a day starts and ends, and how to ask for the accounting period. red-ale handles dates and time zones as GnuCash 5.17 does, so a red-ale server and a GnuCash in the same time zone agree on every date. ## Dates and timestamps - A **Date** is a calendar day with no time: `2024-07-01`. A Transaction's `datePosted`, a Price's day and a due date are Dates. This is what you send and what you usually read back. - A *timestamp* is an instant, always written in UTC with a `Z`: `2024-07-01T10:59:00Z`. Entered times, reconcile times and the time a method ran are timestamps. A Date you choose is stored as the **day-neutral time**: 10:59:00 UTC on that day, moved to 11:59 in zones west of UTC-10 and to 09:59 in zones east of UTC+13, so that it falls on that day wherever the book is read. A posted date also gets a `date-posted` Slot holding the calendar day. Do not compute with the stored instant: read the Date. ## The local time zone Day boundaries depend on one time zone, the **local time zone** of the process that serves red-ale, read once at start-up as GnuCash reads it: the `TZ` environment variable as a zone file (`Europe/Paris`), else `TZ` as a POSIX string, else the machine's zone, else UTC. **⚠** In a POSIX string GnuCash reads the sign the opposite way round to the C library (`XYZ11` is UTC+11); red-ale does the same. A **local day** runs from 00:00:00 to 23:59:59 local time. This decides: - **"Today"**, wherever a method defaults to it: the local date of the server's clock, not of the client's; - which Prices fall on the **same day**; - the start and end of the accounting period and of a report's date ranges; - balances "as of" a day. If an agent and the server are in different zones, send explicit Dates. Run the server with `TZ` set to the zone the book belongs to. ## The accounting period The **accounting period** is the pair of dates that reports and `*Period` options mean by "this year" or "start of the accounting period", set by the Configuration's `accountingPeriod.start`, `.end` and `.fiscalYearEnd` (or, without a setting, the book's own fiscal-year-end Slot). It is a preference of the person running red-ale, not Book data: see [The Configuration](concept/configuration) and [Closing the books and the accounting period](concept/closing-the-books-and-accounting-period). [`period.dates`](method/period.dates) gives the first and last day of the period that contains a date, plus the instants GnuCash uses (local 00:00:00 of the first day, 23:59:59 of the last). Use it to work out the dates you pass to a report or to [`transaction.list`](method/transaction.list). *Example: with no book, at 2024-07-15T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"period.dates","params":{"date":"2024-07-15","start":"fiscal-year","end":"fiscal-year","fiscalYearEnd":"03-31"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "start": "2024-04-01", "end": "2025-03-31", "…": "…" } } ``` ## Relative dates Report options can take a **relative date**, GnuCash's names for a day worked out from now: `today`, `one-month-ago`, `start-this-month`, `end-prev-quarter`, `start-accounting-period` and so on. They are resolved from the server's clock, zone and accounting period before a report runs, and a report result records the dates it used. To reproduce an earlier run, pass the same `now` to `report.run`. ## Where red-ale and GnuCash differ red-ale follows a zone file's transitions exactly. GnuCash fits each year with one rule, which puts local midnight an hour late on the autumn change in some European zones and drops daylight saving from 2037. This changes only which day an instant within that hour belongs to (a balance "as of" a day, a same-day price lookup), never what is written. ## Related - [Transactions and Splits](concept/transactions-and-splits) - [Closing the books and the accounting period](concept/closing-the-books-and-accounting-period) - [period.dates](method/period.dates) - [period.get](method/period.get) - [config.get](method/config.get) --- *red-ale Manual, `concept/dates-and-time-zones`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Double entry Every Transaction moves value between Accounts and its Split values sum to exactly zero. The accounting equation, debits and credits, and the raw sign red-ale uses for balances. GnuCash, and so red-ale, keeps books by double entry. You need little accounting to use red-ale, but this idea explains most of what its methods insist on. ## The accounting equation Everything a book tracks falls under five kinds of Account (see [Account types](concept/account-types)): assets, liabilities, equity, income and expenses. They relate by the accounting equation: ``` Assets - Liabilities = Equity + (Income - Expenses) ``` Your net worth (assets less liabilities) is your equity, and income raises it while expenses lower it. The equation must always hold. A paycheck that raises an income Account must raise an asset by the same amount; a loan that raises an asset also raises a liability. ## Every change has two sides For each change in one Account there is a balancing change in another. This is the Principle of Balance, and it is why a [Transaction](concept/transactions-and-splits) has at least two Splits whose values sum to exactly zero. A Transaction that does not sum to zero is refused with [`unbalanced`](error/unbalanced), and nothing is recorded. ## Debits and credits Moving the terms of the equation so that assets and expenses stand on one side gives: ``` Assets + Expenses = Liabilities + Equity + Income ``` Accounts on the left are *debit balance* accounts: a debit increases them and a credit decreases them. Accounts on the right are *credit balance* accounts: a credit increases them and a debit decreases them. | Account kind | Debit | Credit | |--------------|-------|--------| | Asset, Expense | increases | decreases | | Liability, Equity, Income | decreases | increases | Debit and credit do not mean increase and decrease. In everyday speech "credit" sounds good; in accounting it means only the right-hand side of the ledger. ## The raw sign red-ale does not show an Account's balance as "how much you have" or "how much you owe". It uses the **raw sign** that GnuCash's engine uses: debits are positive and credits negative. So a bank Account with money in it has a positive balance, a credit card you owe on has a negative one, and an income Account has a negative balance, because income is credits. GnuCash's registers and reports flip the sign of credit Accounts for display (its "Reverse Balanced Accounts" preference); the methods do not. A `value` in [`transaction.post`](method/transaction.post) follows the same rule: positive is a debit, negative a credit. *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Salary","type":"INCOME","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"transaction.post","params":{"datePosted":"2024-07-01","description":"Pay","splits":[{"account":"Checking","value":"2500.00"},{"account":"Salary","value":"-2500.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"account.balance","params":{"account":"Checking"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "balances": { "commodity": "CURRENCY::USD", "balance": { "num": "250000", "denom": "100" }, "…": "…" }, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"account.balance","params":{"account":"Salary"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": { "balances": { "commodity": "CURRENCY::USD", "balance": { "num": "-250000", "denom": "100" }, "…": "…" }, "…": "…" } } ``` ## Income and expenses are Accounts If you come from a program that files money under categories, an income or expense Account takes the place of a category. Name the expense Account where you would have named the category: the transaction is the same. See [Coming from GnuCash](concept/coming-from-gnucash) for the other words that change. ## Related - [Account types](concept/account-types) - [Transactions and Splits](concept/transactions-and-splits) - [Value and amount](concept/value-and-amount) - [transaction.post](method/transaction.post) - [account.balance](method/account.balance) - [unbalanced](error/unbalanced) --- *red-ale Manual, `concept/double-entry`. Adapted from GnuCash's documentation, `guide/ch_basics.docbook#basics-accounting1`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Imbalance, orphans and scrubs What the Imbalance-CUR and Orphan-CUR Accounts are, why red-ale refuses an unbalanced Transaction instead of creating them, and how scrub.checkAndRepair puts right a book that already has them. A Transaction's Split values should sum to exactly zero ([Double entry](concept/double-entry)). GnuCash enforces that by repairing: when a Transaction does not balance it adds a Split in an Account named `Imbalance-USD` (one per currency) for the difference. A Split with no Account at all is moved to `Orphan-USD`. These repairs are called **scrubs**. ## What red-ale does differently - **It refuses, rather than repairs.** [`transaction.post`](method/transaction.post) and the other methods that change Transactions refuse one that does not balance, with [`unbalanced`](error/unbalanced) naming the difference, and change nothing. An `Imbalance-USD` Account never appears because of something you did through red-ale. - **It never scrubs on its own.** GnuCash scrubs a book as it loads it. red-ale opens a book exactly as it is, and a book it opens can still hold an orphan Split, a Split whose amount disagrees with its value, or an unbalanced Transaction that GnuCash would quietly fix. Nothing is changed unless you ask. ## Check and repair Run a scrub when a book comes from elsewhere (an import, an old GnuCash book) and you want it clean: | Method | Does | |--------|------| | [`scrub.orphans`](method/scrub.orphans) | Moves Splits with no Account to `Orphan-` | | [`scrub.currency`](method/scrub.currency) | Gives a Transaction whose currency is not a currency the common currency of its Splits | | [`scrub.imbalance`](method/scrub.imbalance) | Balances unbalanced Transactions with an `Imbalance-` Split, after fixing orphans and Split amounts | | [`scrub.checkAndRepair`](method/scrub.checkAndRepair) | GnuCash's Check & Repair: orphans, then imbalances, and with `lots: true` the [Lot](concept/lots-and-capital-gains) scrub | Each takes one Transaction, or one Account (with `subaccounts: true` for its descendants), or neither for the whole book. Each is atomic: it repairs everything it reports or nothing. The result lists every change made, in order, as `repairs`: an Account created, a Split assigned, a balancing Split added, and so on. All four are marked destructive because a repair can remove a Split. ## After a repair `Imbalance-USD` is a real Account, of type `BANK`, under the root. It holds what was out of balance; it is not an answer. Open each Transaction that has a Split in it, work out where the money went, and move the Split to the right Account with [`transaction.update`](method/transaction.update). When the Account is empty, delete it ([`account.delete`](method/account.delete)). Do the same for `Orphan-USD`. An import can also leave an imbalance when a file's Transactions do not balance; the import proposal reports it before you apply anything ([Importing and matching](concept/importing-and-matching)). ## Related - [Double entry](concept/double-entry) - [Transactions and Splits](concept/transactions-and-splits) - [scrub.checkAndRepair](method/scrub.checkAndRepair) - [scrub.imbalance](method/scrub.imbalance) - [scrub.orphans](method/scrub.orphans) - [scrub.currency](method/scrub.currency) - [unbalanced](error/unbalanced) --- *red-ale Manual, `concept/imbalance-and-scrubs`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Importing and matching Importing QIF, CSV and business files in two calls - import.preview builds a proposal and changes nothing, import.apply applies your choices - and how the matcher finds duplicates, scores candidates and learns accounts from import maps. GnuCash imports transactions from files in the formats QIF, OFX/QFX, CSV, MT940, MT942 and DTAUS. red-ale imports *QIF and CSV*; OFX, QFX, MT940, MT942, DTAUS and online banking are not supported ([From GnuCash: Not in red-ale](gnucash/not-in-red-ale)). | `format` | Imports | Duplicates found by | |----------|---------|---------------------| | `csvTransactions` | Transactions, with a saved or inline column layout | The matcher | | `qif` | Accounts, commodities, Transactions and Prices | QIF's own duplicate finder | | `csvAccounts` | An Account tree | Full name | | `csvPrices` | Prices | Same day, either direction | | `csvDocuments` | Invoices or bills, posted when the file says | Document ID | | `csvOwners` | Customers or Vendors | Owner ID | ## Two calls An import is never a single step. GnuCash shows its matcher in a window; red-ale's equivalent is a proposal you can read. 1. [`import.preview`](method/import.preview) reads the file and works out what it holds, and returns an **Import proposal**: each **Imported transaction** (or account, price, document, owner) with the **Import action** chosen for it, its **Candidate matches**, the account of each Split, any imbalance, and whether it would be read-only by date. It changes nothing. The server holds the proposal under an ID. 2. Read it. Change an action, a chosen match or an account. 3. [`import.apply`](method/import.apply) applies the proposal with your changes as *one change*: everything or nothing. [`import.discard`](method/import.discard) throws a proposal away. A proposal is tied to the **book revision** it was made at: if the book changed since, `import.apply` refuses it (`conflict`) and you preview again. The server keeps 16 proposals and drops the oldest. Paths are read on the server, so they are relative to where it runs. ### Import actions For an Imported transaction, `import.apply` can: - **add** it as a new Transaction; - **clear** the existing Transaction it matches: it sets that Split's reconcile state to `c` and deletes nothing; - **update** that Transaction from the imported one and clear it (GnuCash's "update and clear" is one action, not two); - **skip** it. For accounts, prices, documents and owners the actions are add, update (replace a same-day Price) and skip. ## The matcher For `csvTransactions` the matcher compares each imported transaction with the book's existing ones, so that importing the same bank file twice does not double your entries. It looks for **Candidate matches**: Splits in the same Account posted within 42 days. Each gets a **Match score**, an integer: points for an equal or nearly equal amount, a close date, an equal number, memo and description; points off for a different amount or number, or dates far apart. The best score decides the action by the thresholds of the **Import settings**: at or below `autoAddThreshold` the transaction is added, at or above `autoClearThreshold` it is cleared against the match, and the others are left for you. **⚠** The score is not a probability. The settings (`matchThreshold`, the date thresholds, `enableSkip`, `enableUpdate`, `useBayes`, `atmFeeThreshold`) are in the Configuration under `import.settings`, with GnuCash's defaults ([The Configuration](concept/configuration)). ## Learning accounts A file with only one side of each Transaction needs a second Account. The matcher fills it in from what earlier imports taught it, kept in Slots of the Accounts as the **Import map**: - **Bayesian matching**, on by default (`useBayes`): the Account whose combined probability over the transaction's words reaches 90%, learned per source Account. - the *plain* **Import map**: an exact description to an Account, when Bayesian matching is off. A CSV layout can also name the Account itself. `import.apply` learns from your final choices, so the second import of a file from the same bank needs fewer corrections. [`importMap.list`](method/importMap.list) shows what has been learned and [`importMap.delete`](method/importMap.delete) forgets an entry. ## Layouts and QIF GnuCash keeps CSV column layouts ("presets") and the QIF account map (which Account each QIF account, category and payee went to) in its own user files. red-ale keeps them in the Configuration (`import.csvLayouts.`, `import.qifAccountMap`) and `import.apply` saves the QIF map. ## Imbalance GnuCash's importers do not refuse an imported transaction that does not balance: committing it adds an `Imbalance-` Split. red-ale flags each such transaction in the proposal as `imbalance`, before anything changes, and `import.apply` then does as GnuCash does. See [Imbalance, orphans and scrubs](concept/imbalance-and-scrubs). ## Exporting The other way: [`export.csvTransactions`](method/export.csvTransactions) and [`export.csvTree`](method/export.csvTree) return CSV text (nothing is written by the server), and [`export.accounts`](method/export.accounts) writes a new book holding the Account tree and Commodities and no Transactions. ## Related - [Transactions and Splits](concept/transactions-and-splits) - [Reconciliation](concept/reconciliation) - [The Configuration](concept/configuration) - [import.preview](method/import.preview) - [import.apply](method/import.apply) - [import.discard](method/import.discard) - [importMap.list](method/importMap.list) - [importMap.delete](method/importMap.delete) - [Import transactions](guide/import-transactions) --- *red-ale Manual, `concept/importing-and-matching`. Adapted from GnuCash's documentation, `guide/ch_importing.docbook#importing-matcher`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Investments Stocks, mutual funds, bonds and fixed assets in the books - one STOCK or MUTUAL Account per holding, shares as amounts, prices in the price database, income Accounts for dividends and interest, and how fees, dividends and returns are recorded. An investment is something you buy hoping to earn from it or sell it for more. This page covers how the books hold the common kinds. For gains see [Lots and capital gains](concept/lots-and-capital-gains). ## Words you will meet | Term | Meaning | |------|---------| | Security | A Commodity that is not a currency: a share, a fund unit, a bond. **⚠** GnuCash's *stock* is a share of a company; `STOCK` is also the Account type | | Capital gain or loss | The difference between purchase and selling prices. Also *realised* gain or loss | | Commission | The fee a broker charges to buy or sell | | Dividend | A cash payment a company makes to its shareholders | | Interest | What a borrower pays a lender for the use of money, usually a percentage of the principal per year | | Compounding | Reinvested interest that earns interest of its own | | Principal | The original sum invested or borrowed | | Yield | The income an investment earns, as a percentage of its price; it leaves out capital gains. A $100 share paying $2 a year yields 2% | | Return | Income plus capital gains or losses. **⚠** Not a *return of capital* | | Risk | The chance that the return differs from what was expected | | Liquidity | How easily it turns into cash | | Valuation | Working out what it would sell for now | | Stock split | More shares for each existing one, at no cost, with the price adjusted so the value does not change | ## Kinds of investment - **Interest-bearing accounts**, such as savings and certificates of deposit: ordinary `BANK` Accounts. Interest is income, recorded as a Transaction from an `INCOME` Account. - **Stocks and mutual funds**: a mutual fund is treated exactly like a single stock, for tax and for the books. - **Fixed assets**, a house or a painting: value is hard to know until you sell, so there is little to do beyond recording the purchase and the sale ([Other assets and depreciation](concept/other-assets-and-depreciation)). ## Setting up a holding 1. Make the security with [`commodity.create`](method/commodity.create) (namespace such as `NASDAQ`, mnemonic `AMZN`). 2. Make an Account of type `STOCK` (or `MUTUAL`) for *every security you own*, holding that Commodity, usually under an `Assets:Investments:Brokerage` branch, named by the ticker. The Account's balance is in shares, not money: 100, not $2,000. 3. If you track income per security, make `Income:Dividends:AMZN`, `Income:Interest:AMZN` and capital-gain Accounts such as `Income:Cap Gain (Long):AMZN` and `Income:Cap Gain (Short):AMZN`, and an `Expenses:Commission` Account. 4. Put a Price for the security in the price database ([`price.add`](method/price.add)), once, and keep it current. red-ale has no predefined investment Accounts. An Account can remember the Accounts for a security's roles (dividends, capital gains, cash proceeds, broker fees) as its *associated accounts*. ## Buying A purchase is a Transaction in the currency you paid, with a Split in the stock Account that has an *amount* in shares and a *value* in money ([Value and amount](concept/value-and-amount)), and a Split in the bank or brokerage Account paying for it. The share price is `value / amount`; give the amount and the value and let the price follow, so that no rounding is hidden in it. **Commissions** can be handled two ways. In *gross pricing* you record the price before fees and put the fee in an expense Account in a third Split: this tracks fees but the gain scrub does not know to deduct them, so work gains out yourself. In *net pricing* you record the price including the fee and no expense: it works with the lots, but the price in the database is the effective price. Take advice if you are unsure which your tax rules want. ## Selling A sale mirrors the purchase: negative value and amount in the stock Account, the proceeds in the bank Account, and a gain or loss Split in an income Account. [Lots](concept/lots-and-capital-gains) can compute the gain by FIFO and record it for you. ## Dividends - **Cash dividends** are income into the Account that received the money, from `Income:Dividends`. To tie a dividend to one holding, add a Split in the stock Account with amount `0`, price `1` and value `0`. - **Reinvested dividends** (a dividend reinvestment plan, DRIP) are recorded in the stock Account: the Income Account is credited and the stock Account receives the new shares. - A **return of capital** has no income to record: it only lowers the cost basis, and the number of shares stays the same. Record a Split in the stock Account with amount `0` and a negative value equal to the capital returned, against a debit to the bank Account. [`stock.split`](method/stock.split) cannot do this. ## Stock splits and mergers [`stock.split`](method/stock.split) records a split. A merger that swaps shares at a ratio (0.77942 new shares for each old one) is a stock split in each affected holding, with `shares` the change in the number held (`"-22.058"` for 100 shares). Give `price` only if you want a new Price recorded. ## Reports The [Investment Portfolio](report/investment-portfolio), [Advanced Portfolio](report/advanced-portfolio) and [Investment Lots](report/investment-lots) reports show holdings, cost, gains, income and returns. ## Related - [Lots and capital gains](concept/lots-and-capital-gains) - [Prices and exchange rates](concept/prices-and-exchange-rates) - [Commodities and currencies](concept/commodities-and-currencies) - [Value and amount](concept/value-and-amount) - [commodity.create](method/commodity.create) - [account.create](method/account.create) - [price.add](method/price.add) - [Buy and sell shares](guide/buy-and-sell-shares) --- *red-ale Manual, `concept/investments`. Adapted from GnuCash's documentation, `guide/ch_invest.docbook#invest_concepts1`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Loans and interest Principal, interest, compounding and amortisation; how a loan is kept in the books as a liability, the payment formulas red-ale computes exactly, and the loan assistant as scheduledTransaction.loan. There is no loan calculator. A loan is a financial arrangement in which someone pays for the use of someone else's money: a credit card, a car loan, a mortgage, a business loan, or money you lend to a friend. ## Terms | Term | Meaning | |------|---------| | Principal | The original amount of the loan, or the part of it still owed. Each payment repays some principal and pays some interest | | Interest | What the borrower pays for the use of the money, usually a yearly percentage of the principal (the annual percentage rate, APR) | | Compounding | Interest that is added to the principal, so later interest is charged on it too | | Amortisation | A repayment plan that pays the loan off by equal periodic payments, each split into principal and interest; the principal share grows and the interest share shrinks | | Disbursement | An amount of the loan paid out to the borrower. Some loans have several | | Loan fee | A processing fee taken from the principal when the loan is made | | Escrow | Money held by the lender for taxes or insurance, paid with each instalment | ## How the books hold a loan - A loan *you owe* is a liability: an Account of type `LIABILITY` for the loan, with the balance negative (credits). The money you receive goes to your bank Account (a debit); each payment moves money out of the bank Account, reduces the liability by the principal share and charges the interest share to an `EXPENSE` Account. - A loan *you made* is an asset: a short-term receivable such as `Assets:Current Assets:LoanToJoe`. Lending debits it and credits the bank; each repayment debits the bank and credits it. The interest you earn is income. - A mortgage's tax and insurance paid through escrow are expenses too. The books record what the lender's statement says, so reconcile the loan Account against it ([Reconciliation](concept/reconciliation)). ## The arithmetic The fundamental financial equation links five variables: the number of periods *n*, the interest rate per period *i*, the present value *PV* (what is owed now), the periodic payment *PMT* and the future value *FV* (what is owed at the end, usually zero): ``` PV * (1 + i)^n + PMT * (1 + i*X) * ((1 + i)^n - 1) / i + FV = 0 ``` with *X* 0 for payments at the end of each period and 1 for payments at the beginning. For 100,000 over 30 years at 4% compounded monthly, *n* = 360 and *i* = 1/300 per month, so the monthly payment is 477.42. A *nominal* annual rate must first be turned into the effective rate per payment period: with *CF* compounding periods and *PF* payments per year, `ieff = (1 + rate/CF)^(CF/PF) - 1`. **There is no Loan Repayment Calculator in red-ale.** The same arithmetic is available where it matters, in the financial functions of scheduled-transaction formulas: `pmt`, `ipmt`, `ppmt` and the others ([Scheduled transactions](concept/scheduled-transactions)). Given a whole number of periods red-ale computes them with exact rationals and rounds the result to 12 significant figures and then to the currency's fraction, as GnuCash does; GnuCash computes them in floating point, so a result can differ by a cent when the exact figure lies within a hair of a half cent. Functions with a non-whole power of the rate are refused. ## The loan assistant [`scheduledTransaction.loan`](method/scheduledTransaction.loan) is GnuCash's Mortgage and Loan Repayment assistant as one call: give the loan Account, the principal, the rate and its type, the start date, the length and the repayment accounts, and it creates the scheduled transaction GnuCash's assistant would, with the same `pmt`, `ppmt` and `ipmt` formulas, so GnuCash computes the same repayments from it. The result includes `payment`, the periodic payment. Escrow and other payments (taxes, insurance, PMI) can be added. An adjustable-rate loan changes its rate on a schedule (an ARM 10/1 is fixed for 10 years, then changes yearly). The assistant makes a fixed-rate schedule; edit it or make a new one when the rate changes ([`scheduledTransaction.update`](method/scheduledTransaction.update)). The final payment is an ordinary Transaction with the figures from the bank. ## Related - [Scheduled transactions](concept/scheduled-transactions) - [Account types](concept/account-types) - [Investments](concept/investments) - [scheduledTransaction.loan](method/scheduledTransaction.loan) - [scheduledTransaction.create](method/scheduledTransaction.create) - [Track a loan](guide/track-a-loan) - [Set up accounts](guide/set-up-accounts) --- *red-ale Manual, `concept/loans-and-interest`. Adapted from GnuCash's documentation, `guide/ch_loans.docbook#loans_concepts1`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Lots and capital gains A Lot groups the Splits that buy and then sell one holding. Realised and unrealised gains, cost basis, the FIFO lot policy, the gains Transaction red-ale records, and what stock splits do to lots. Many things you own change in value: stocks, bonds, a house, a painting. Track the change only for items you could sell for cash or that matter for tax. Food and printer paper are expenses; you spent the money and it is gone. ## Gains - When an asset's value rises above what you paid, the difference is an **unrealised gain**. It exists on paper only: red-ale never records it as a Split. A report such as the [Advanced Portfolio](report/advanced-portfolio) works it out as the value now, from the price database, less the cost basis. - When you sell, the profit or loss is a **realised gain**, also called a **capital gain** or loss, and it is recorded. - **Cost basis** is what a holding cost you, the figure gains are measured against. red-ale reads it from Lots: the purchases a sale draws on. Whether and how a gain is taxed varies by country and by the kind of asset (a home you live in, a bond whose interest must be recognised each year). Consult the tax rules that apply to you. Only revalue assets that sell readily at a well-known price, such as listed shares; for the rest it is better to wait for the sale, when the gain is exact. ## Lots A **Lot** groups the Splits of one Account that buy and then sell the same holding. A Lot is **closed** when it has Splits and their amounts sum to zero: everything bought has been sold. You can see an Account's Lots with [`lot.list`](method/lot.list) (`state`: `all`, `open`, `closed`) and one Lot with its Splits with [`lot.get`](method/lot.get). A Split joins only a Lot of its own Account. [`lot.assignSplit`](method/lot.assignSplit) puts a Split into a Lot, cutting the Split in two if it would overfill the Lot; without a `lot` it chooses by the **lot policy**. GnuCash 5.17 has one policy, **first in, first out (FIFO)**: a sale draws on the earliest purchases first. [`lot.removeSplit`](method/lot.removeSplit) takes one out again. [`lot.create`](method/lot.create) makes an empty Lot, titled `Lot 1`, `Lot 2` and so on, and [`lot.update`](method/lot.update) sets its title and notes. [`lot.scrubAccount`](method/lot.scrubAccount) does it for a whole Account: it assigns every Split to a Lot by FIFO and repairs each Lot, with `subaccounts: true` for the subtree. [`lot.scrub`](method/lot.scrub) repairs one Lot. [`lot.freeSplits`](method/lot.freeSplits) lists the Splits in no Lot. ## Recording the gain [`lot.computeGains`](method/lot.computeGains) (also run by the scrubs) records the realised gain of each selling Split as a **gains Transaction**, described `Realized Gain/Loss`. It has two Splits: - a *gains Split* in the Lot, with amount zero and the gain as its value; - a Split in the **gains Account** with the opposite value. The gains Account is the one the Lot's Account remembers for its currency; if none is set, an income Account `Orphaned Gains-` under the root, found by name or created. Pass `gainsAccount` to choose one. The result lists what was created and changed. ## Stock splits A stock split changes the number of shares without changing value: 100 shares become 200, each worth half. [`stock.split`](method/stock.split) records it as a Split with value zero and the action `Split`. Such Splits never join Lots and never produce gains, and Lot balances, closure and FIFO use each Split's *adjusted amount*, restated in the units after any later split. The adjusted amount is worked out as needed and never stored. Do not post a stock split by hand as an ordinary buy and sell: it would create a false gain. ## A worked case Buy 100 shares at 10.00, then 100 at 12.00, then sell 150 at 15.00. FIFO takes the first 100 and 50 of the second: the gain is `100 x (15-10) + 50 x (15-12) = 650`. The sale is cut into a Split of 100 shares, which closes the first Lot, and one of 50, which sells half of the second; that Lot stays open with 50 shares. ## Related - [Investments](concept/investments) - [Prices and exchange rates](concept/prices-and-exchange-rates) - [lot.create](method/lot.create) - [lot.assignSplit](method/lot.assignSplit) - [lot.computeGains](method/lot.computeGains) - [lot.scrubAccount](method/lot.scrubAccount) - [lot.list](method/lot.list) - [stock.split](method/stock.split) - [Capital gains with lots](guide/capital-gains-with-lots) --- *red-ale Manual, `concept/lots-and-capital-gains`. Adapted from GnuCash's documentation, `guide/ch_capgain.docbook#capgain_concepts1`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Other assets and depreciation Current and fixed assets, prepaid items and suspense accounts, and depreciation - why, book and tax depreciation, and the linear, geometric and sum-of-digits schemes - recorded with ordinary Accounts and a scheduled transaction. Assets in the balance sheet are grouped by how long they last. Neither group needs a special Account type: use `ASSET` (or `BANK`, `CASH`) Accounts and build the tree as suits you. ## Current assets **Current assets** are expected to last a year or less. Examples: - **Short-term receivables**: money lent to someone you trust and expect back within a year. Lending 500 debits `Assets:Current Assets:LoanToJoe` and credits the bank; each repayment does the opposite. The word *loan* in the name is a tip-off that you really have a receivable. - **Reimbursable expenses and travel advances**: money you spend for an employer and later recover. Keep one Account per trip if you want the details apart. - **Prepaid items**, such as insurance paid for a year, which you spread over the year as it is used up. - **Deposits**: if the deposit will be returned, record it as an asset (debit `Deposits Receivable`); if you write it off, debit an expense. Decide when you pay. - **Suspense or wash Accounts**: a place for amounts you cannot yet place. Empty it as soon as you know what they were. ## Fixed assets Long-term, or **fixed assets**, last longer than a year: land, buildings, vehicles, equipment and intangibles such as patents. Land does not wear out, so it is recorded at cost and its rise in value is not recorded until you sell; the cost of land bought with a building is split between them. Buildings, vehicles and equipment wear, which is what depreciation accounts for. To show a sale, compare the price with the cost less depreciation to find the gain or loss ([Lots and capital gains](concept/lots-and-capital-gains)). ## Depreciation **Depreciation** is the accounting method for expensing a capital purchase over time. Two reasons to record it: to keep an estimate of your net worth in personal books, or to match the cost of equipment against the income it earns in a business. | Term | Meaning | |------|---------| | Original cost | What the asset cost, including shipping, installation and training needed to use it | | Book depreciation | The amount you record in your financial statements each period | | Tax depreciation | The amount you take for income tax, by rules the tax authority sets | | Accumulated depreciation | The total book depreciation taken so far | | Net book value | Original cost less accumulated depreciation | | Fair market value | What the asset could be sold for now | | Salvage value | What you estimate it will sell for at the end of its useful life, usually taken as zero | **Personal books.** Record the purchase as an asset, and each year a depreciation expense; the net book value then tracks the market value. There are no rules: use your best judgement, and only for assets of notable worth such as a car or boat. **Business books.** Capitalise what you expect to help earn income for more than the current year, with the costs of getting it into use; do not capitalise goods bought for resale. Choose a scheme for book depreciation; tax depreciation is fixed by your tax code and often differs. ### Schemes For an asset costing 1,500 and a salvage value of zero: - **Linear**: the same amount each period over the useful life; 300 a year for 5 years takes 1,500 to 0. - **Geometric** (declining balance): a fixed percentage of the previous period's value, so more early on and a remaining value at the end; 30% a year gives 450, 315, 220.50, and so on. - **Sum of digits**: a falling fraction of the cost. For 5 years the fractions are 5/15, 4/15, 3/15, 2/15 and 1/15. Stop when the net book value reaches the salvage value. ## Recording it Each period's depreciation is one Transaction: debit an `EXPENSE` Account (`Expenses:Depreciation`) and credit a contra asset Account (`Assets:Fixed Assets:Computer:Accumulated Depreciation`), or credit the asset directly. A fixed amount every period is a [scheduled transaction](concept/scheduled-transactions), made with [`scheduledTransaction.create`](method/scheduledTransaction.create); amounts that change each period are posted one at a time with [`transaction.post`](method/transaction.post). ## Related - [Account types](concept/account-types) - [Scheduled transactions](concept/scheduled-transactions) - [Lots and capital gains](concept/lots-and-capital-gains) - [account.create](method/account.create) - [scheduledTransaction.create](method/scheduledTransaction.create) - [transaction.post](method/transaction.post) - [Set up accounts](guide/set-up-accounts) - [Depreciate an asset](guide/depreciate-an-asset) --- *red-ale Manual, `concept/other-assets-and-depreciation`. Adapted from GnuCash's documentation, `guide/ch_dep.docbook#dep_concepts1`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Prices and exchange rates The price database holds the value of one Commodity in another at a time. Prices, direct and indirect lookup, same-day rules and source rank, and fetching quotes from Quote services when the Configuration allows the network. An Account that holds shares tracks how many you own; what each share is worth lives in the **price database**. A **Price** is the value of one Commodity in another, usually a currency, at a time: 40.50 USD per share of AMZN on a given day. Exchange rates between currencies are Prices too, in the same table. A Price has the Commodity it prices, the `currency` its value is in, a `value` (exact, as given), a time, a `source` saying where it came from and a `type` (`last`, `bid`, `ask`, `nav` or `unknown`; informational). ## Adding and finding Prices - [`price.add`](method/price.add) adds one by hand, for a day (`date`) or an exact time. The first price for a Commodity puts it in the database; you do it once. - [`price.update`](method/price.update) and [`price.delete`](method/price.delete) edit and remove. - [`price.list`](method/price.list) lists them by Commodity, currency and date range. - [`price.removeOld`](method/price.removeOld) thins old prices, keeping the last of each week, month or quarter. Transactions in other currencies, transfers and stock splits can record Prices too: see [`transaction.transfer`](method/transaction.transfer) (`recordPrice`) and [`stock.split`](method/stock.split). ## How a rate is looked up When something converts one Commodity to another (a report in one currency, a balance of foreign accounts), it asks for a Price at a time: - **`nearest`** takes the Price closest to the time (the older on a tie), **`before`** the newest at or before it, and **`latest`** the newest there is: [`price.nearest`](method/price.nearest) and [`price.latest`](method/price.latest). - A *direct* price is one between the two Commodities, in either direction; a Price quoted the other way round is inverted. When there is none, an *indirect* price goes through a third Commodity both are priced in (shares to USD to EUR). **⚠** For the *latest* lookup GnuCash takes a direct price even if it lies in the future, but an indirect one only up to now. - With no price at all, the conversion gives nothing: a report shows a zero or leaves the Commodity unconverted rather than guess. ## The same day Two Prices of one Commodity pair on the same local day compete ([Dates and time zones](concept/dates-and-time-zones)). The source decides which stays: a price you entered in the price editor ranks above a fetched quote, which ranks above one recorded from a transaction, and so on down to `temporary`. A lower-ranked Price never replaces a higher one, and a Price from an unknown source ranks last. A refused price is reported (`priceStatus`) rather than silently dropped. ## Online quotes GnuCash fetches quotes through Finance::Quote, a Perl library. *red-ale has no Perl* and does not run Finance::Quote. It asks web services itself. - A Commodity is set up with a quote flag and a **quote source** (`alphavantage`, `yahoo_json`, `currency` and so on), which says *what* to fetch. - A **Quote service** in the Configuration says *where from*: a URL template, a response format, an optional key and a minimum interval. The Configuration maps each quote source to the services that answer it. - [`price.fetchQuotes`](method/price.fetchQuotes) starts a fetch in the background and [`price.fetchStatus`](method/price.fetchStatus) reports it; the Prices it got are added in one change, with the source GnuCash writes for fetched quotes. - **The network is off by default.** `quotes.network` is `false` until a person sets it, and without it `price.fetchQuotes` fails with [`network-disabled`](error/network-disabled) and sends nothing. It cannot be changed through MCP, nor can a service's key. See [The Configuration](concept/configuration) for these settings. A book whose prices red-ale fetched is a book GnuCash could have fetched. ## Related - [Commodities and currencies](concept/commodities-and-currencies) - [Value and amount](concept/value-and-amount) - [Investments](concept/investments) - [price.add](method/price.add) - [price.list](method/price.list) - [price.nearest](method/price.nearest) - [price.latest](method/price.latest) - [price.fetchQuotes](method/price.fetchQuotes) - [Record prices and commodities](guide/record-prices) --- *red-ale Manual, `concept/prices-and-exchange-rates`. Adapted from GnuCash's documentation, `guide/ch_invest.docbook#invest-stockprice1`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Read-only books Why a Book opens read-only - you asked, it declares a Book feature red-ale lacks, it holds content red-ale cannot safely edit, or its SQL schema is not GnuCash 5.17's - what readOnlyReasons says and what to do about each. A **read-only session** never takes the lock and refuses every method that changes the Book (with [`read-only`](error/read-only)). [`book.open`](method/book.open) and [`book.info`](method/book.info) say whether the book is read-only and why, in `readOnlyReasons`: a list of `{ code, message }`. red-ale prefers to refuse than to risk a book. If it cannot be sure that an edit will leave what GnuCash keeps intact, it opens the book read-only and tells you. | Code | Why | What to do | |------|-----|-----------| | `requested` | You opened it with `readOnly: true` | Close it and open it again without `readOnly` | | `unsupported-features` | The book declares a Book feature that GnuCash implements and red-ale does not. Writing could drop what that feature means | Edit it in GnuCash. Reading, reports and exports all work | | `unrecognised-content` | It holds something red-ale can keep but not edit safely: an unknown SQLite table or column, damaged slot rows, a failed integrity check | Edit it in GnuCash. Reading, reports and exports work | | `schema-version` | An SQLite book whose tables are not at GnuCash 5.17's versions. red-ale never upgrades a schema | Open it in GnuCash 5.17 so that it upgrades the book, then reopen | A read-only book is also how to look at a book that another program holds: a read-only open takes no lock, so it works beside a running GnuCash. You get the book as it was last saved; edits made since are not there. ## What is not read-only - A Book with the num field source option, the auto read-only threshold or trading accounts opens writable. The threshold makes only the *old Transactions* read-only: see [Transactions and Splits](concept/transactions-and-splits). - Unknown XML elements and Slots in an XML book are not a reason in themselves: red-ale keeps them and writes them back unchanged ([Books and files](concept/books-and-files)). ## Checking before you change a book Call `book.info` after opening, and read `readOnly`. An agent that is about to edit should stop and tell the user when `readOnlyReasons` holds a reason other than `requested`: red-ale will not write the book however it asks. ## Related - [Books and files](concept/books-and-files) - [book.open](method/book.open) - [book.info](method/book.info) - [read-only](error/read-only) - [book-locked](error/book-locked) - [Create, open and save a book](guide/create-open-and-save-a-book) --- *red-ale Manual, `concept/read-only-books`. Adapted from GnuCash's documentation, `guide/ch_basics.docbook#basics-files-storage-comparison`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Reconciliation Checking an Account against a bank statement. Reconcile states, the statement, ticked Splits, the difference that must reach zero, finishing or postponing, and auto-clear. red-ale keeps no reconcile window - the caller carries the ticks. **Reconciliation** double-checks your records and the bank's: it matches the Transactions in an Account with a statement from the bank or other institution, and shows up differences and outstanding items such as cheques not yet cashed. You can reconcile any Account that has statements: a bank account, a credit card, a loan. An expense account has none, so there is nothing to reconcile. ## Reconcile states Every Split has a state, shown in GnuCash's register as the R column: | State | Meaning | |-------|---------| | `n` | New. The default | | `c` | Cleared. The bank has processed it but it is not yet reconciled to a statement. Set by hand, or by an import | | `y` | Reconciled. Only a reconciliation sets this. A reconciled Split warns you before you change it | | `f` | Frozen. GnuCash does not implement it | | `v` | Voided. Set by [`transaction.void`](method/transaction.void), never by hand | [`reconcile.setState`](method/reconcile.setState) sets a Split to `n`, `c`, `y` or `f`. It refuses `v`, and any change to a Split of a voided Transaction. Setting `y` records the reconcile date. ## The statement A **statement** is one reconciliation: an Account, a statement date, the ending balance printed on the statement, and whether the Account's sub-accounts are included. The starting balance is not asked for: it is the total of everything already reconciled (`y`, `f`). All reconcile figures use the raw sign: debits positive, credits negative ([Double entry](concept/double-entry)). For a credit card, the amount you owe is a negative ending balance. GnuCash's window flips the sign for credit Accounts; the methods do not. ## The steps 1. [`reconcile.start`](method/reconcile.start) fills in GnuCash's defaults (the statement date is a month after the last reconciliation, the ending balance the book's balance at that date) and lists the Splits you can tick: every new or cleared Split of the Account. Cleared Splits dated on or before the statement date arrive pre-ticked. 2. Compare the list with the statement. **Ticked splits** are the ones that appear on it. Call [`reconcile.status`](method/reconcile.status) with your ticks (`ticked`, adding with `mark` and `unmark`) to see the balances again: `reconciledBalance` is the starting balance plus the ticked Splits, and `difference = endingBalance - reconciledBalance`. 3. When `difference` is zero, [`reconcile.finish`](method/reconcile.finish) turns every ticked Split into `y` with the statement date as its reconcile date and records the statement date as the Account's last reconciliation. It refuses a non-zero difference unless you pass `force: true`. 4. If you cannot finish, [`reconcile.postpone`](method/reconcile.postpone) saves your place: the ticked Splits become `c`, un-ticked cleared ones on or before the date become `n`, and the statement date and balance are kept so the next `reconcile.start` resumes from them. **The caller carries the ticks.** GnuCash holds them in its window until you press Finish or Postpone. red-ale has no window and keeps nothing between calls: every call to `reconcile.status` and `reconcile.finish` names the ticks. Only `finish` and `postpone` change the book, each in one step. A missing Transaction or a wrong amount is fixed with the ordinary methods ([`transaction.post`](method/transaction.post), [`transaction.update`](method/transaction.update)) between steps; interest or a fee on the statement is an ordinary Transaction too. red-ale has no "Enter Interest Payment" button. ## Auto-clear When you only have a figure, [`reconcile.findAutoClear`](method/reconcile.findAutoClear) looks for the one set of uncleared Splits in an Account that brings its cleared balance to a given amount, and [`reconcile.autoClear`](method/reconcile.autoClear) marks them cleared. It fails if no set does, or if more than one set does: it will not guess. ## Last reconcile date [`reconcile.info`](method/reconcile.info) gives an Account's last reconciliation and the interval used to suggest the next date; [`reconcile.setInfo`](method/reconcile.setInfo) edits them. ## Related - [Transactions and Splits](concept/transactions-and-splits) - [reconcile.start](method/reconcile.start) - [reconcile.status](method/reconcile.status) - [reconcile.finish](method/reconcile.finish) - [reconcile.postpone](method/reconcile.postpone) - [reconcile.autoClear](method/reconcile.autoClear) - [reconcile.setState](method/reconcile.setState) - [Reconcile an account](guide/reconcile-an-account) --- *red-ale Manual, `concept/reconciliation`. Adapted from GnuCash's documentation, `manual/ch_Account-Actions.docbook#acct-reconcile`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Report scripts User reports - how to write your own report as a .rhai script in the Configuration's report directory. The shape of a script (templates, options, render), option types, the query API's main reads, exact Rational arithmetic, the report result's blocks, limits, library modules and load errors. red-ale ports the reports GnuCash itself relies on and leaves the rest for you to write: the business and tax reports, the Easy and Fancy invoices, and anything particular to your own books. A report you write is a **User report**: a **Report script**, a `.rhai` file, that defines one or more report templates. Rhai is a small scripting language that looks like Rust. red-ale never runs Guile, GnuCash's Scheme; its own reports are GnuCash's Scheme translated into Rhai, and they serve as worked examples (below). **⚠** A User report is not GnuCash's "custom report", which is a [saved configuration](concept/reports) of an existing template. A script reads the book only through a read-only query API. It cannot change the book, open a file, reach the network or read the clock. No method takes a script's text: **the script is a file on the machine where red-ale runs**, so an agent that writes reports needs file access there. ## Where scripts live Set the **report directory** in the Configuration: ``` red-ale exec config.set 'changes:={"reports.directory": "/home/me/reports"}' ``` `reports.directory` is relative to the Configuration file if it is not absolute (see [The Configuration](concept/configuration)). red-ale reads every `*.rhai` file below it, at most 1,000 files of at most 1 MiB each, each time a report method runs, so edits show without a restart. Symbolic links that lead outside the directory are ignored. A script with no `templates()` function is a library module that other scripts import. [`report.list`](method/report.list) lists your templates with `kind` `user` and the script that defines them (`./mine/report.rhai`). A script that does not load, for example because it does not compile or repeats a GUID, defines no template; `report.list` gives its error, with the file, line and column, in `problems` (error [`report-load`](error/report-load)), so one bad file does not hide the others. Naming one of its templates is `not-found`. ## The shape of a script A script is three functions: ```rhai fn templates() { [#{ guid: "0f2d5e3a9b1c4d6e8a7b3c5d9e1f2a4b", name: "Bank balances", menuPath: ["_Assets & Liabilities"] }] } fn options(params, o, book) { o.date("General", "Balance Date", "a", "Balances at the end of this day.", "today", #{}); } fn render(params, book, opts, ctx) { let at = ctx.end_of_day(opts.get("General", "Balance Date")); let rows = []; for a in book.accounts_of_types(["BANK"]) { let balance = monetary(a.commodity, a.balance_as_of(at + 1)); rows.push(#{ account: a.guid, cells: [#{ text: a.fullName, account: a.guid }, #{ monetary: balance }] }); } #{ title: "Bank balances", sections: [#{ blocks: [#{ kind: "table", columns: [#{ label: "Account", role: "label" }, #{ label: "Balance", role: "amount" }], rows: rows }] }] } } ``` - `templates()` returns the template records: a `guid` of 32 lowercase hex digits (make your own and keep it: saved configurations refer to it), a `name`, and optionally `menuPath`, `menuName`, `menuTip`, `inMenu`, `exportTypes` and `params`, values that tell templates of one script apart. - `options(params, o, book)` declares the options through the builder `o`. `book` is the open book, or an empty one when none is open, so defaults can be computed from it. - `render(params, book, opts, ctx)` returns the report result as a map. `opts.get(section, name)` is an option's value, with dates already as times; `ctx` gives time and formatting. red-ale adds GnuCash's three General options (*Report name*, *Stylesheet*, *Add options summary*) to every template. A misspelt variable or map key is an error, and a function may not have the name of an engine function of the same arity. ## Options `o.boolean`, `o.string`, `o.text`, `o.font`, `o.color`, `o.multichoice`, `o.list`, `o.number_range`, `o.plot_size`, `o.date`, `o.start_date` and `o.end_date`, `o.account_list`, `o.account_sel`, `o.currency`, `o.commodity`, `o.budget`, `o.internal`, and two for the Printable Invoice: **`o.invoice`**, an option whose value is a business document's GUID (a script sees an Invoice, or `()` for none) and **`o.image`**, a picture's file name that the HTML refers to but the server never reads. Each takes a section, a name, a sort key, a help text and a default. The wire forms are those of `report.options` ([Reports](concept/reports)). The built-in library module `lib/options` has the common ones GnuCash's reports share, such as the report date, the date interval and the account levels. ## What a script can read All handles are read-only, and lists come back in a fixed order, never in hash order. - **Book**: `root()`, `account(ref)`, `accounts()`, `accounts_of_types(types)`, `commodity(id)`, `prices(...)`, `price_rate(...)`, `price_convert(...)`, `split_query(q)` for splits by account and date, budgets and, from v0.6, **`book.option("Business/Company Name")`**, which reads an option stored in the book, and `book.invoice(guid)`. - **Account**: names, type, commodity, `children()`, `descendants_sorted()`, `splits()`, `splits_between(from, to)`, `balance_as_of(t)`. - **Split** and **Transaction**: amount, value, memo, action, reconcile state, dates, description, `splits()`. - **Commodity** and **Price**. - **Invoice**, **Entry**, **Owner**, **Order** and **BillTerm** (v0.6), the reads the Printable Invoice uses: a document's type, owner and addresses, terms, dates, Entries (quantity, price, discount, taxes), totals, posted Transaction and Lot. Each figure is exact and computed by red-ale; a script never recomputes one. - **ctx**: `now`, `today()`, `start_of_day(t)`, `end_of_day(t)`, `local(t)`, `print_date(t)`, `print_time(t, format)` (date directives only, `%d %m %Y %B ...`) and the report settings (`report_currency()`, `week_start()`, `accounting_period()`). The clock is the run's `now`, not the machine's. ## Exact arithmetic Money in reports is a **Rational**, an exact fraction of any size. `rational("12.34")` and `rational(1234, 100)` make one; `+ - * /` and the comparisons are exact. There is no float: a float literal is a syntax error. A **Monetary** is a Rational with a Commodity (`monetary(commodity, r)`); adding two Commodities is an error. Round only to show a figure: `r.round_to(denom, mode)`, `m.round_scu()`, `r.to_decimal(places)`. Dividing by zero is a `report-script` error. ## The report result `render` returns a map with a `title` and `sections`, each with `blocks`. The kinds are `text` (with a `role` of `paragraph`, `heading` or `note`), `warning`, `table`, `chart`, `list`, `group` (blocks side by side), `grid` (a Multicolumn View's cells) and, from v0.6, **`image`** (a `src` starting `file:///`). A table has `columns` and `rows` whose `cells` are one of `text`, `monetary`, `commodities`, `number`, `price`, `date` or `anchors`. From v0.6: - **`class`** on any block or cell, one or more CSS class names for the report's own style, and **`css`** on the result, the CSS itself (red-ale leaves out text its CSS template would refuse and logs why); - **`numberFormat: "exact"`** on a `number` cell, to print the figure unrounded. The host checks the result and fills in display text, so a malformed result is `report-result` and names the path (`sections[0].blocks[0].text`). Whatever the script `print`s or `debug`s is returned in the result's `log`. ## Limits A script runs under limits that make a runaway script an error, not a hung server: 1,000,000,000 operations, 120 seconds, call depth 64, a string of 1 MiB, 10,000,000 array items, and so on. Change them under `reports.limits.*` in the Configuration. Passing one is [`report-limit`](error/report-limit); a script error is [`report-script`](error/report-script); a bad option value, [`report-option`](error/report-option). A tree of reports that embed reports shares one time limit. ## Using the library `import "lib/exchange" as exchange;` loads a built-in module (`lib/accounts`, `lib/balances`, `lib/dates`, `lib/options`, `lib/exchange`, `lib/html-utilities` and others). `import "standard/"` and `import "example/"` load a built-in report. `import "./other"` loads another script of yours, inside the report directory; `..` and absolute paths are refused. No two scripts in a run may define a function with the same name and number of parameters. ## Worked examples The built-in reports are ordinary scripts, translated line by line from GnuCash's Scheme and commented with where each line comes from. In red-ale's source they are in `crates/red-ale-report/scripts/`: - `standard/account-summary.rhai`, `standard/balance-sheet.rhai`: tables of accounts and balances; - `standard/transaction.rhai`: filters, sorting and subtotals; - `standard/invoice.rhai`: Invoices, Entries, options of type `invoice` and `image`, `class` and `css`; - `example/average-balance.rhai`, `example/daily-reports.rhai`: GnuCash's own example reports, including charts; - `lib/*.rhai`: the shared modules. Run yours with [`report.run`](method/report.run), render it with [`report.export`](method/report.export), and save a set of options with `report.saveConfiguration`. ## Related - [Reports](concept/reports) - [The Configuration](concept/configuration) - [Business documents](concept/business-documents) - [report.list](method/report.list) - [report.options](method/report.options) - [report.run](method/report.run) - [report.export](method/report.export) - [config.set](method/config.set) - [Print an invoice](guide/print-an-invoice) - [Write your own report](guide/write-your-own-report) --- *red-ale Manual, `concept/report-scripts`. Adapted from GnuCash's documentation, `manual/ch_Reports.docbook#report-create`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Reports Report templates and their options, the report result and its HTML export, style sheets, saved report configurations and the Multicolumn View - what red-ale ports from GnuCash, and what you write yourself as a User report. A **report** is a read-only view of your book: balances, income and spending, the holdings of your investments, a single invoice. Running a report never changes the book, never marks it dirty and works on a book that is open read-only. ## Templates and options A **report template** is a report definition with a GUID, a name and *options*. The built-in templates keep GnuCash 5.17's names and GUIDs. **⚠** GnuCash also calls saved configurations "custom reports"; red-ale says *saved report configuration* for those (below). - [`report.list`](method/report.list) lists every template and saved configuration, with `kind` `builtin`, `user` or `saved`. It needs no book. - [`report.options`](method/report.options) lists a report's *options*: each is named by a section and name (GnuCash's English strings, such as *General* / *Start Date*), has a type, a default and the current value, plus a JSON Schema for the `options` of `report.run`. Options come in GnuCash's order. - Report options go in `options` as `{ "

": { "": } }`, changing only what differs from the defaults. Dates may be absolute or *relative* (`start-this-month`, `end-prev-quarter`). Accounts are given by GUID or full name. Every report has GnuCash's three General options: *Report name*, *Stylesheet* and *Add options summary*. ## Running and the report result [`report.run`](method/report.run) runs a report and returns the **report result**: a document of sections made of tables, charts and text, with every figure exact (a `{num, denom}` rational and its display form) and roles instead of styles. It is the published language for reports: an agent reads figures from it, a renderer draws it. Pass `now` to run the report as of another time, and `locale` to format numbers and dates in another Locale; the same book, options, time and settings give the same bytes. Amounts in reports are exact rationals, and rounding to the Commodity's smallest unit happens only when a figure is displayed. GnuCash computes many reports in floating point; red-ale does not, so a report may differ from GnuCash's in the last cent where GnuCash's own sum drifts. ## Exporting - [`report.export`](method/report.export) runs a report and returns it as a single HTML document, rendered through a style sheet: self-contained (no script, no outside resource), the same bytes for the same inputs. Nothing is written to disk: the CLI's `--output` saves it on your side. - [`report.exportCsv`](method/report.exportCsv) returns the data of the net-worth and category charts as CSV text. - **There is no PDF export.** Turn the exported HTML into PDF with a general tool such as pandoc or an HTML-to-PDF converter. ## Style sheets A **style sheet** is a named set of presentation options, applied when a result is rendered as HTML. red-ale has GnuCash's six predefined style sheets: *Default*, *CSS-based stylesheet (experimental)*, *Easy*, *Technicolor*, *Footer* and *Head or Tail*. [`report.styleSheets`](method/report.styleSheets) lists them with their options; [`report.createStyleSheet`](method/report.createStyleSheet), `report.updateStyleSheet` and `report.deleteStyleSheet` manage your own. Changing one changes every report that uses it. Images in style sheets (a background picture, a banner or logo) are not rendered. ## Saved report configurations Once you have a report set up as you like it, save it: [`report.saveConfiguration`](method/report.saveConfiguration) stores its options, only those that differ from the template's, under a new name and GUID in the Configuration ([The Configuration](concept/configuration)). A saved configuration runs and exports like any report; [`report.updateConfiguration`](method/report.updateConfiguration), `report.renameConfiguration` and `report.deleteConfiguration` change it. [`report.importConfigurations`](method/report.importConfigurations) and `report.importStyleSheets` read GnuCash's own `saved-reports-2.8` and `stylesheets-2.0` files, which you give as text. A **Multicolumn View** ([`report/multicolumn-view`](report/multicolumn-view)) puts several reports on one page; its children are templates or saved configurations. ## What is built in red-ale ports the reports GnuCash's own work relies on. They are in the groups the GnuCash Reports menu has. - **Assets and liabilities**: [Account Summary](report/account-summary), [Balance Sheet](report/balance-sheet), [Multicolumn Balance Sheet](report/balance-sheet-multicolumn), [Advanced Portfolio](report/advanced-portfolio), [Investment Portfolio](report/investment-portfolio), [Average Balance](report/average-balance), [Net Worth Barchart](report/net-worth-barchart) and [Linechart](report/net-worth-linechart), [Assets](report/assets) and [Liabilities](report/liabilities) pie charts, [Securities](report/securities), [Price Scatterplot](report/price-scatterplot). - **Income and expense**: [Income Statement](report/income-statement) (also called Profit & Loss), its [multicolumn](report/income-statement-multicolumn) form, [Cash Flow](report/cash-flow), [Equity Statement](report/equity-statement), [Trial Balance](report/trial-balance), [Income and Expense charts](report/income-expense-chart), [Income](report/income-accounts) and [Expense](report/expense-accounts) pies, the [over-time](report/income-over-time) and [day-of-week](report/income-vs-day-of-week) charts. - **Transactions**: [Transaction Report](report/transaction-report), [General Journal](report/general-journal), [General Ledger](report/general-ledger), [Transaction Breakdown](report/transaction-breakdown-report), [Reconciliation Report](report/reconciliation-report). - **Budget**: [Budget Report](report/budget-report), [Budget Flow](report/budget-flow), [Budget Chart](report/budget-chart), [Budget Income Statement](report/budget-income-statement) and [Budget Balance Sheet](report/budget-balance-sheet) ([Budgets](concept/budgets)). - **Scheduled transactions**: [Balance Forecast](report/balance-forecast), [Future Scheduled Transactions Summary](report/future-scheduled-transactions-summary) ([Scheduled transactions](concept/scheduled-transactions)). - **Investments**: [Investment Lots](report/investment-lots), [IFRS cost basis](report/ifrs-weighted-average-cost-basis-report) ([Lots and capital gains](concept/lots-and-capital-gains)). - **Business**: the [Printable Invoice](report/printable-invoice) ([Business documents](concept/business-documents)). - **Multicolumn**: the [Multicolumn View](report/multicolumn-view) and the [Dashboard](report/dashboard), a built-in saved configuration of it. GnuCash's other business reports, its tax reports, the Easy and Fancy invoices, the Hello World and Sample Graphs examples and the eguile Balance Sheet are not ported. The Balance Sheet above gives the figures of the last. Write anything else you need as a [User report](concept/report-scripts). To find a GnuCash report here, see [From GnuCash: Reports menu](gnucash/reports-menu). ## Related - [Report scripts](concept/report-scripts) - [Budgets](concept/budgets) - [report.list](method/report.list) - [report.options](method/report.options) - [report.run](method/report.run) - [report.export](method/report.export) - [report.exportCsv](method/report.exportCsv) - [report.saveConfiguration](method/report.saveConfiguration) - [report.styleSheets](method/report.styleSheets) - [Run and export a report](guide/run-and-export-a-report) --- *red-ale Manual, `concept/reports`. Adapted from GnuCash's documentation, `guide/ch_reports.docbook#rpt_concepts`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Scheduled transactions A Scheduled transaction is a Transaction that recurs - a schedule of Recurrences, template Transactions with formulas and variables, and Instances created by Since Last Run. red-ale runs Since Last Run only when asked, as a proposal you apply. A **scheduled transaction** is a Transaction that recurs: rent, salary, a loan repayment, a depreciation entry. GnuCash calls it *SX* in its code; red-ale says scheduled transaction. Scheduled transactions either enter themselves when they fall due or remind you, and you review what they made with **Since Last Run**. ## What one holds | Part | Meaning | |------|---------| | Name | What you call it; used as the description of the Transactions it makes | | Start date, end | The first possible date, and an end: a date, a number of occurrences, or none | | Schedule | A list of **Recurrences**: a step repeated from a start, each with a multiplier, a period type (`day`, `week`, `month`, `endOfMonth`, `nthWeekday`, `lastWeekday`, `year`, `once`) and a weekend adjustment (`none`, `back`, `forward`) | | Template transactions | The Transactions it copies, with accounts and amounts as formulas | | Enabled, auto-create | Whether it is considered at all, and whether due Instances are created without asking, with a days-ahead window and an optional notice | **⚠** A Schedule is a *list* of Recurrences, not one: "semi-monthly" is two monthly Recurrences, and "weekly on several days" one weekly Recurrence per day. The next **Occurrence** is the earliest next date of any of them. A start day past the end of a month clamps to its last day: monthly from 31 January gives 31 Jan, 29 Feb, 31 Mar. *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"scheduledTransaction.occurrences","params":{"schedule":[{"mult":1,"periodType":"month","start":"2024-01-31"}],"startDate":"2024-01-31","count":3}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "occurrences": [ { "date": "2024-01-31", "instanceCount": 1 }, { "date": "2024-02-29", "instanceCount": 2 }, { "date": "2024-03-31", "instanceCount": 3 } ] } } ``` ## Template transactions A scheduled transaction's template Transactions live in a hidden **template account** of its own, under the **template root**, outside the Account tree: no balance, report, find, import, scrub or export sees them. Each template split names the real Account the copy goes to, a memo and action, and a **formula** for its debit and its credit amount. ### Formulas and variables A formula is arithmetic in GnuCash's expression syntax: numbers, `+ - * /`, parentheses, names and calls of financial functions with `:` between arguments (`pmt(rate : nper : pv : fv : type)`). It is evaluated exactly. A formula that is a single number in parentheses is negated, by the accounting convention: `(5)` is minus 5. Every name in a formula is a **variable**, given a value for each Instance before it is created. `i` is predefined, the **Instance count**, starting at 1; it is a counter of Instances acted on, not of Transactions made, because postponing counts and GnuCash overwrites it from the last Instance acted on. A split in another Commodity than the Transaction currency gets an exchange-rate variable such as `EUR -> USD`. The financial functions `pmt`, `ipmt`, `ppmt`, `futureValue`, `computeInterestIncrement` and `periodic_rate` are supported; others are refused with [`formula`](error/formula). See [Loans and interest](concept/loans-and-interest). An unparsable formula is refused when the scheduled transaction is made. A template that must balance and cannot is refused with [`unbalanced`](error/unbalanced). ## Making one - [`scheduledTransaction.create`](method/scheduledTransaction.create) from a schedule and template Transactions. - [`scheduledTransaction.fromTransaction`](method/scheduledTransaction.fromTransaction) from an existing Transaction, as GnuCash's "Schedule" action does: the quickest way to make one. - [`scheduledTransaction.loan`](method/scheduledTransaction.loan) from a loan's terms, GnuCash's loan assistant. - [`scheduledTransaction.occurrences`](method/scheduledTransaction.occurrences) previews the dates of one, saved or not. - [`scheduledTransaction.update`](method/scheduledTransaction.update), `.delete`, `.get` and `.list` do the rest. Deleting an Account that a scheduled transaction uses is refused, naming it. ## Since Last Run **Since Last Run** creates the Transactions of every enabled scheduled transaction that have fallen due since it last ran, and reminds you of those coming. GnuCash runs it whenever a book opens. **red-ale never changes a book when it opens it: you ask**, in two calls, like an import: 1. [`scheduledTransaction.sinceLastRun`](method/scheduledTransaction.sinceLastRun) changes nothing. It returns a *proposal* of **Instances**, each an Occurrence with its date, Instance count, variable values and a state. 2. Read it. Change an Instance's state, and give values for variables the formulas need. 3. [`scheduledTransaction.apply`](method/scheduledTransaction.apply) applies the proposal with your choices as one change. [`scheduledTransaction.discard`](method/scheduledTransaction.discard) drops it. An Instance's state is one of: *toCreate* (create its Transactions), *reminder* (nothing; it is proposed again next time), *postponed* (saved as a **Deferred instance** so Since Last Run proposes it again) or *ignored* (skipped for good). *created* appears in results only. The server holds a proposal until it is applied, discarded, or pushed out by 16 newer ones, and `apply` refuses a proposal made against a different state of the book (`conflict`). Instances dated before the book's auto read-only threshold are marked, since Transactions there cannot be created. Deferred instances cannot be held by an SQLite book. ## Forecasts The reports [Balance Forecast](report/balance-forecast) and [Future Scheduled Transactions Summary](report/future-scheduled-transactions-summary) read your scheduled transactions without creating anything. ## Related - [Loans and interest](concept/loans-and-interest) - [Budgets](concept/budgets) - [scheduledTransaction.create](method/scheduledTransaction.create) - [scheduledTransaction.sinceLastRun](method/scheduledTransaction.sinceLastRun) - [scheduledTransaction.apply](method/scheduledTransaction.apply) - [scheduledTransaction.occurrences](method/scheduledTransaction.occurrences) - [scheduledTransaction.fromTransaction](method/scheduledTransaction.fromTransaction) - [scheduledTransaction.loan](method/scheduledTransaction.loan) - [Schedule a transaction](guide/schedule-a-transaction) --- *red-ale Manual, `concept/scheduled-transactions`. Adapted from GnuCash's documentation, `manual/ch_Transactions.docbook#trans-sched`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Trading accounts With the book option Use Trading Accounts on, every Transaction that crosses Commodities also records what was bought and sold in TRADING Accounts, so amounts balance per Commodity as well as values. What the option does, and what to expect. A Transaction in two Commodities balances by *value* (in the Transaction currency) but not by *amount*: you spent 100 USD and received 92 EUR, so the amounts, being in different Commodities, sum to nothing in particular. **Trading accounts** make the books balance per Commodity too. In accounting terms they are specialised equity Accounts that record changes in income which come from Transactions between two or more currencies (or securities and currencies). In GnuCash they are Accounts of type `TRADING`. Extended, the accounting equation reads: ``` Assets = Liabilities + Equity + (Income - Expenses) + Trading ``` ## The option Trading accounts are off by default. Switch them on with the book option **Use trading accounts** (`useTradingAccounts`), read by [`book.options`](method/book.options) and set by [`book.setOptions`](method/book.setOptions). Changing it alters no Transaction: an existing Transaction gets trading Splits the next time it is changed. ## What it does With the option on, every Transaction that is created or changed is kept **balanced with trading accounts**: its non-trading Split values sum to zero; its trading Split values sum to zero; and, per Commodity, the amounts of its Splits sum to zero. When a Transaction does not already balance that way, red-ale removes its trading Splits and adds new ones, in an Account for each Commodity under `Trading::`: ``` Trading CURRENCY EUR USD ``` They are created when needed. For the Transaction above, a Split in `Trading:CURRENCY:USD` and one in `Trading:CURRENCY:EUR` make both Commodities' amounts balance. **⚠** *Trading splits* are added and removed by red-ale itself, as GnuCash does, and are not entries of your own. Do not post to a Trading Account by hand; a change to the Transaction replaces them. `balanced` in a Transaction's result follows the option: without it, balanced means only that the values sum to zero. The Account tree lists these Accounts like any other, but their balances measure currency gains and losses, not money you hold. Reports can show them. ## If you do not use them Leave the option off and record foreign-currency Transactions by hand: transfer money into the foreign Account at the rate you got, and record gains and losses as ordinary Transactions with an income or expense Account. Trading accounts earn their place when you buy and sell across currencies often and want the gains and losses worked out for you. A book that uses trading accounts opens for editing: red-ale applies the same rule as GnuCash on every change, in the same Accounts with the same figures. ## Related - [Value and amount](concept/value-and-amount) - [Commodities and currencies](concept/commodities-and-currencies) - [Account types](concept/account-types) - [book.options](method/book.options) - [book.setOptions](method/book.setOptions) - [transaction.post](method/transaction.post) - [Use trading accounts](guide/use-trading-accounts) --- *red-ale Manual, `concept/trading-accounts`. Adapted from GnuCash's documentation, `guide/ch_currency.docbook#trading_acct_concepts`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Transactions and Splits A Transaction is a dated, balanced exchange made of two or more Splits, each in one Account. Its dates, description, num, notes, and a Split's memo, action and reconcile state; read-only Transactions. Money moves between Accounts in **Transactions**. Whenever you spend or receive money, or transfer it between Accounts, that is one Transaction: paying a phone bill, moving money from savings to checking, depositing a paycheck. In double entry every Transaction involves at least two Accounts, a source and a destination. red-ale records this as a line for each Account affected, called a **Split**. A Transaction has any number of Splits, so a paycheck can credit `Salary` once and debit `Checking`, `Taxes` and `Pension` in one Transaction. Its Split values sum to exactly zero ([Double entry](concept/double-entry)). ## A Transaction | Field | Meaning | |-------|---------| | `currency` | The Transaction currency, in which every Split's value is expressed | | `datePosted` | The date the Transaction takes effect: the date reports use. A calendar date, with no time | | `dateEntered` | When it was first recorded; separate from the posted date, and now unless you say otherwise | | `description` | A short free-text description (the payee, say) | | `num` | A free-text check or reference number | | `notes` | Longer free text. **⚠** Not a Split's memo | | `splits` | Its Splits | Posting a Transaction with [`transaction.post`](method/transaction.post) either records it whole or, if it does not balance or breaks another rule, records nothing. [`transaction.update`](method/transaction.update) changes fields and Splits the same way. See [Dates and time zones](concept/dates-and-time-zones) for what a posted date means. ## A Split | Field | Meaning | |-------|---------| | `account` | The Account the Split belongs to; not a placeholder or the root | | `value` | Its size in the Transaction currency; positive is a debit, negative a credit | | `amount` | Its size in the Account's Commodity. **⚠** What GnuCash calls the *quantity* in a file; see [Value and amount](concept/value-and-amount) | | `memo` | A note on this line. **⚠** Not the Transaction's `notes` | | `action` | A free-text action field (`Buy`, `Sell`, `Split`, ...) | | `reconcileState` | `n` new, `c` cleared, `y` reconciled, `f` frozen, `v` voided; see [Reconciliation](concept/reconciliation) | A Split can also belong to a [Lot](concept/lots-and-capital-gains). The Transaction's `num` is what you would call the check number; some books use the Split's `action` as the number instead (the book option `splitActionForNum`, see [The Configuration](concept/configuration)). ## Finding them - [`transaction.get`](method/transaction.get) returns one Transaction. - [`transaction.list`](method/transaction.list) lists the Transactions in an Account and a date range. - [`transaction.find`](method/transaction.find) finds Splits by any combination of text, amounts, dates, states and Accounts, as GnuCash's Find dialog does. GnuCash's register is a view of one Account's Splits. red-ale has no register: ask for the Account's Transactions and its balance. ## Changing a Transaction later - **Void** keeps the Transaction with its Split figures set to zero, the old figures and a reason in its Slots: [`transaction.void`](method/transaction.void), undone by [`transaction.unvoid`](method/transaction.unvoid). - **Reverse** creates a second Transaction with every Split negated: [`transaction.reverse`](method/transaction.reverse). - **Delete** removes it: [`transaction.delete`](method/transaction.delete). ## Read-only Transactions Some Transactions refuse change (`conflict`): - voided ones, and those a business document posted, which carry a read-only mark; - those posted before the book's auto read-only threshold, when it is set (the book option `autoReadOnlyDays`), which GnuCash's register shows behind its "red line". The threshold is a book option: see [`book.setOptions`](method/book.setOptions). ## Related - [Double entry](concept/double-entry) - [Value and amount](concept/value-and-amount) - [Reconciliation](concept/reconciliation) - [transaction.post](method/transaction.post) - [transaction.get](method/transaction.get) - [transaction.list](method/transaction.list) - [transaction.update](method/transaction.update) --- *red-ale Manual, `concept/transactions-and-splits`. Adapted from GnuCash's documentation, `guide/ch_basics.docbook#basics-transactions2`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Value and amount A Split has a value, in the Transaction currency, and an amount, in its Account's Commodity. Both are exact rationals; values sum to zero per Transaction. GnuCash's quantity is red-ale's amount. A Split has two sizes, and mixing them up is the commonest mistake with multiple currencies or securities. - Its **value** is in the **Transaction currency**: the one currency every Split of the Transaction shares. The values of a Transaction's Splits sum to exactly zero. - Its **amount** is in the **Commodity of the Split's Account**: euros in a euro account, shares in a stock account. **⚠** GnuCash's word *amount* means exactly this quantity, not a generic number, and its files call it `quantity`. Elsewhere in this Manual a *value* is always in the Transaction currency. When an Account holds the Transaction currency, value and amount are equal, and red-ale fills in the amount from the value if you leave it out. When the Account's Commodity differs, you give both, and their ratio is the price the Split implies: ``` price = value / amount ``` Buying 10 shares of AAPL for 1,500.00 USD from a USD bank Account is a USD Transaction with two Splits: | Account | Value (USD) | Amount | |---------|-------------|--------| | Broker (AAPL) | 1500.00 | 10 shares | | Bank (USD) | -1500.00 | -1500.00 USD | Transferring 100.00 USD to a euro Account at 0.92 is a USD Transaction too: the euro Account's Split has value 100.00 and amount 92.00. [`transaction.transfer`](method/transaction.transfer) works that out from a rate; [`transaction.post`](method/transaction.post) takes the amounts as you give them. *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Bank","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Euro account","type":"BANK","commodity":"EUR"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"transaction.post","params":{"datePosted":"2024-07-01","description":"To euros","currency":"USD","splits":[{"account":"Bank","value":"-100.00"},{"account":"Euro account","value":"100.00","amount":"92.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"account.balance","params":{"account":"Euro account"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "balances": { "commodity": "CURRENCY::EUR", "balance": { "num": "9200", "denom": "100" }, "…": "…" }, "…": "…" } } ``` Both are kept; neither is derived from the other when a book is saved, so a change of rate later does not silently rewrite what you recorded. ## Exact numbers Amounts, values, prices and rates are *exact rationals*, a numerator over a denominator, never floating point. On the wire send one as a decimal string (`"12.34"`), a rational string (`"1234/100"`) or an object (`{"num": "1234", "denom": "100"}`); red-ale answers with the object. A JSON number is refused. This holds in every door: JSON-RPC, MCP and the CLI. An amount is held to its Commodity's **smallest commodity unit** (SCU): 100 for USD (cents), 1 for JPY, 10000 for a typical share. When red-ale records a figure it rounds half up to the currency's fraction (values) or the Account's SCU (amounts), and refuses a non-zero figure that would round to zero. GnuCash reduces fractions when it reads them back (`-617/50`) but stores what was written (`-1234/100`), and red-ale does the same; compare figures by value, not by their text. ## Signs Both value and amount use the raw sign: positive is a debit, negative a credit ([Double entry](concept/double-entry)). Selling shares gives the stock Account a negative value and a negative amount, and the bank Account that receives the proceeds a positive value and a positive amount. ## Related - [Transactions and Splits](concept/transactions-and-splits) - [Commodities and currencies](concept/commodities-and-currencies) - [Prices and exchange rates](concept/prices-and-exchange-rates) - [transaction.post](method/transaction.post) - [transaction.transfer](method/transaction.transfer) --- *red-ale Manual, `concept/value-and-amount`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # arithmetic Exact arithmetic overflowed or was undefined. **Cause.** Amounts are exact fractions of 64-bit integers, and the calculation needed more than they hold or divided by zero. Nothing was changed. **Fix.** Use smaller amounts, or a coarser denominator (`"12.34"` rather than 20 decimal places), or a non-zero rate or divisor. **Code:** `2004` · **Name:** `arithmetic` --- *red-ale Manual, `error/arithmetic`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # backup-failed The backup could not be made, so nothing was written. **Cause.** red-ale copies the previous file to `..gnucash` before it overwrites it. That copy failed (no space, no permission), and it will not write without a backup. Nothing was written. **Fix.** Free space or fix permissions in the book's directory and save again. **Code:** `1011` · **Name:** `backup-failed` ## Related - [book.save](method/book.save) --- *red-ale Manual, `error/backup-failed`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # book-already-open A book is already open in this server. **Cause.** `book.open` or `book.create` was called while the server holds a book. One server holds one book. **Fix.** Close the open one with [book.close](method/book.close) (with `save` or `discard` if it has changes), then open the other. Or start a second server for the second book. **Code:** `1001` · **Name:** `book-already-open` ## Related - [book.close](method/book.close) --- *red-ale Manual, `error/book-already-open`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # book-changed Another program changed the SQLite book since red-ale read it. **Cause.** Another program wrote the SQLite book, or broke its lock, after red-ale opened it or last saved it. `data.path` is the book and `data.detail` what differed. red-ale writes nothing, so it cannot overwrite the other program's changes. **Fix.** Close the book discarding your changes and open it again; make your edits again on the new state. Keep GnuCash and red-ale from holding the same book at once. **Code:** `1013` · **Name:** `book-changed` ## Related - [book.save](method/book.save) --- *red-ale Manual, `error/book-changed`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # book-locked Another program holds the book's lock. **Cause.** GnuCash, or another red-ale, has the book open for writing. An XML book is locked by a `.LCK` file beside it (`data.path` is that file); an SQLite book by a row in its `gnclock` table (`data.path` is the book and `data.holder` the row's `hostname` and `pid`). With no `holder`, another program was writing the SQLite book for longer than red-ale's 5 second wait. **Fix.** Close the other program and call again. Open the book with `readOnly: true` to look at it meanwhile; a read-only open takes no lock. Delete a `.LCK` file only if you know the program that made it is gone, as a crash can leave one behind, and never while GnuCash is running. **Code:** `1002` · **Name:** `book-locked` ## Related - [book.open](method/book.open) --- *red-ale Manual, `error/book-locked`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # cannot-lock The lock could not be taken because the location is not writable. **Cause.** red-ale could not create the `.LCK` file beside an XML book, or could not write the SQLite book or its directory, so it cannot take the lock that makes writing safe. Nothing was opened. **Fix.** Make the directory writable (or the file, for SQLite), or open the book with `readOnly: true`, which needs no lock. A book on a read-only mount can only be opened read-only. **Code:** `1003` · **Name:** `cannot-lock` ## Related - [book.open](method/book.open) --- *red-ale Manual, `error/cannot-lock`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # conflict The entity exists but may not be changed this way. **Cause.** The change clashes with what is already there: an account, commodity or price that already exists, a transaction that is read-only or a split that is void, a document that is already posted, a transaction already posted before the book's auto read-only threshold that `transaction.update`, `delete`, `void` or `unvoid` would change (`data.reason` `auto-read-only`, with `data.date` and `data.threshold`), a built-in saved report configuration such as the [Dashboard](report/dashboard) (`data.reason` `built-in`), or a report name that several reports have (`data.matches`). Nothing was changed. A date before the threshold that you ask for, as `transaction.post`'s `datePosted` or a new one in `transaction.update`, is [invalid](error/invalid) instead, with the same `data`: the request is wrong, not the transaction. GnuCash draws the same line: its register will not let you type such a date, and makes a transaction already before the threshold read-only. **Fix.** The message says which. Pick a different name, undo the state that blocks the change (unpost the document, lower the threshold with [book.setOptions](method/book.setOptions)), copy a built-in configuration with [report.saveConfiguration](method/report.saveConfiguration) and change the copy, name a report by its GUID, or leave the record as it is. **Code:** `2003` · **Name:** `conflict` --- *red-ale Manual, `error/conflict`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # file-exists The file to create already exists. **Cause.** `book.create` was given a path where a file already exists. red-ale never overwrites a book on creation. **Fix.** Choose another path, or move or delete the old file yourself if you really mean to replace it. **Code:** `1007` · **Name:** `file-exists` ## Related - [book.create](method/book.create) --- *red-ale Manual, `error/file-exists`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # file-format The file is not a readable GnuCash XML book or journal. **Cause.** The file does not parse as a GnuCash 2.x-or-later XML book (plain or gzipped), as an SQLite book, or, for `book.replayJournal`, as a GnuCash `.log` journal. GnuCash version 1 files are in this group too. **Fix.** Check that you named the right file. Open a very old file in GnuCash and save it again, which upgrades it. A file damaged by a failed copy needs its backup (`..gnucash`). **Code:** `1009` · **Name:** `file-format` --- *red-ale Manual, `error/file-format`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # formula A scheduled transaction's formula could not be used. **Cause.** A formula in a scheduled transaction does not parse, uses a function red-ale does not compute, or cannot be evaluated (for example it divides by zero or names a variable that has no value). `data.reason`, `data.formula` and `data.position` say what and where. **Fix.** Correct the formula at that position, or give the variable a value. **Code:** `6000` · **Name:** `formula` --- *red-ale Manual, `error/formula`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # import-file An import file cannot be read as its format. **Cause.** The file given to an import is not readable as the format named (QIF, CSV, OFX and so on) at all. `data.file`, `data.line` and `data.reason` say where it gave up. **Fix.** Check that you chose the right format and encoding, and that the file is whole. Fix or remove the line named, then preview the import again. **Code:** `4000` · **Name:** `import-file` --- *red-ale Manual, `error/import-file`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # internal-error A bug in red-ale. **Cause.** red-ale hit a state it did not expect. The book is not changed by the failed call; a mutation applies completely or not at all. **Fix.** There is nothing to fix in the request. Repeat it once; if it fails again, keep the request and the book (a copy, never your only one) and report the bug. **Code:** `-32603` · **Name:** `internal-error` --- *red-ale Manual, `error/internal-error`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # invalid The request is not valid for the book as it stands. **Cause.** The params are well formed but the change they ask for breaks a rule of the book: a commodity the account cannot hold, an account type that cannot sit under that parent, a value that is out of range, a posted date before the auto read-only threshold (`data.reason` `auto-read-only`, with `data.date` and `data.threshold`), and so on. The message names the rule. Nothing was changed. Changing a transaction that is already before the threshold is a [conflict](error/conflict) instead. **Fix.** Read the message and change the request to respect it. The method's Reference page lists its rules. **Code:** `2001` · **Name:** `invalid` --- *red-ale Manual, `error/invalid`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # invalid-params The params do not match the method's schema. **Cause.** The params are not what the method's schema allows: a name the method does not have (so a typo never passes silently), a missing required field, a value of the wrong type, positional params, or a JSON number given as an amount. The message names the field. Nothing was changed. **Fix.** Check the method's Reference page or its schema (`api.schema`). Send amounts as strings (`"12.34"`) or as `{"num": "1234", "denom": "100"}`, never as JSON numbers, which could lose digits. Spell params in camelCase. **Code:** `-32602` · **Name:** `invalid-params` ## Related - [help.get](method/help.get) --- *red-ale Manual, `error/invalid-params`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # invalid-request The request was JSON but not a JSON-RPC 2.0 request. **Cause.** The document parsed, but it is not a JSON-RPC 2.0 request: `jsonrpc` is not `"2.0"`, `method` is missing or not a string, or `params` is neither an object nor absent. This is a protocol error (code -32600). **Fix.** Send `{"jsonrpc": "2.0", "id": 1, "method": "book.info", "params": {}}`. Params are always an object, by name; an array of positional params is refused with [invalid-params](error/invalid-params). **Code:** `-32600` · **Name:** `invalid-request` --- *red-ale Manual, `error/invalid-request`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # io-error A file operation failed. **Cause.** Reading or writing a file failed at the operating system: the file is missing or unreadable, the disk is full, or permissions forbid it. The message carries the system's reason and the path. **Fix.** Fix the path or permissions named in the message and call again. For `book.save`, the book on disk is unchanged and the book in memory still holds your changes. **Code:** `1008` · **Name:** `io-error` --- *red-ale Manual, `error/io-error`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # method-not-found No method has that name. **Cause.** The request named a method red-ale does not have. Method names are case-sensitive and namespaced: `account.create`, not `createAccount` or `Account.Create`. **Fix.** List the methods with `red-ale methods` or [help.topics](method/help.topics), or search for the task with [help.search](method/help.search). A name from a newer red-ale than the server you are talking to also lands here. **Code:** `-32601` · **Name:** `method-not-found` --- *red-ale Manual, `error/method-not-found`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # network-disabled The method needs the network and the Configuration has it off. **Cause.** Fetching online quotes (and other methods that use the network) is off in red-ale's Configuration. Nothing was sent. **Fix.** Turn it on with [config.set](method/config.set) if you want it, and call again. The setting is there so a headless server never reaches the network unasked. **Code:** `5000` · **Name:** `network-disabled` --- *red-ale Manual, `error/network-disabled`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # no-book No book is open. **Cause.** The method works on a book and the server has none open. A server holds one book at a time, and starts with none unless it was given `--book`. **Fix.** Call [book.open](method/book.open) with the path of an existing book, or [book.create](method/book.create) for a new one. `red-ale exec --book ` opens it for you. Methods that need no book (`help.*`, `config.*`, `period.*`) never fail this way. **Code:** `1000` · **Name:** `no-book` ## Related - [book.open](method/book.open) - [book.create](method/book.create) --- *red-ale Manual, `error/no-book`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # not-found An entity named in the request does not exist. **Cause.** An account, transaction, split, lot, price, commodity or other entity named in the request is not in the book. `data.kind` says what kind and `data.id` what was asked for. Account names are full names with `:` between levels, and are case-sensitive. **Fix.** Look the entity up first ([account.list](method/account.list), [transaction.find](method/transaction.find), [commodity.list](method/commodity.list) and so on) and pass its GUID or exact name. **Code:** `2000` · **Name:** `not-found` --- *red-ale Manual, `error/not-found`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # parse-error The request was not valid JSON. **Cause.** The server received text it could not parse as JSON, so it could not even tell which method was meant. This is a JSON-RPC protocol error (code -32700) and comes from the HTTP door and stdin scripts, not from a method. **Fix.** Send a well-formed JSON document: balanced braces, double-quoted names and strings, no trailing commas. With `red-ale exec`, give params as one JSON object or as `key=value` and `key:=json` pairs, and quote the object for your shell. **Code:** `-32700` · **Name:** `parse-error` --- *red-ale Manual, `error/parse-error`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # read-only The book is open read-only, so it cannot be changed. **Cause.** A method that changes the book was called on a book that is open read-only. `data.reason` says why: it was opened with `readOnly: true`, or red-ale opened it read-only on its own because it declares a Book feature red-ale does not implement. [book.info](method/book.info) lists the same `readOnlyReasons`. **Fix.** If you asked for read-only, close and reopen the book without `readOnly`. If red-ale chose it, the book stays read-only: writing it could lose data GnuCash would keep, so use GnuCash for those changes. A change dated before the book's auto read-only threshold is refused separately, as `conflict` or `invalid` with `data.reason` `auto-read-only` (see [book.setOptions](method/book.setOptions)). **Code:** `1006` · **Name:** `read-only` ## Related - [book.info](method/book.info) --- *red-ale Manual, `error/read-only`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # report-limit A report script passed one of its limits. **Cause.** Report scripts run in a sandbox with limits on operations, time and call depth. `data.limit` says which was passed. This guards the server against runaway scripts. **Fix.** Narrow the report (a shorter date range, fewer accounts) or simplify the script so it loops less. **Code:** `3001` · **Name:** `report-limit` --- *red-ale Manual, `error/report-limit`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # report-load A user report script does not load. **Cause.** A report script you provided could not be read or compiled. `data.source` is the file and `data.line` where it stopped. **Fix.** Fix the syntax error at that line and load the script again. **Code:** `3004` · **Name:** `report-load` --- *red-ale Manual, `error/report-load`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # report-option A report option value is not valid. **Cause.** An option was given a value its type does not allow: an unknown name, a number out of range, a choice that is not on the list, an account that does not suit the report. `data.section`, `data.name` and `data.reason` say which. **Fix.** Look up the option and its allowed values on the report's Page, or via `report.options`, and send a value of that kind. **Code:** `3002` · **Name:** `report-option` --- *red-ale Manual, `error/report-option`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # report-result A report script returned a malformed result. **Cause.** The script finished but what it returned is not a valid report document. `data.path` says where in the result the first problem is. **Fix.** Fix the script so it returns the report structure the Manual's custom-report Pages describe. **Code:** `3003` · **Name:** `report-result` --- *red-ale Manual, `error/report-result`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # report-script A report script failed while running. **Cause.** A report's Rhai script raised an error at run time. `data.source`, `data.line` and `data.message` say where and why, and `data.log` holds what the script logged before it stopped. **Fix.** For a report you wrote, fix the script at that line. For a built-in report, the options are probably unusual: reset them and report the failure. **Code:** `3000` · **Name:** `report-script` --- *red-ale Manual, `error/report-script`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # save-verification The file written did not read back as the same book, so it was removed. **Cause.** After writing, red-ale reads the new file back and compares it with the book in memory. They differed, so it removed the new file and kept the old one: the book on disk is unchanged. For an SQLite book the save's SQL transaction was rolled back. **Fix.** Your changes are still in memory. Try [book.save](method/book.save) again, perhaps to a better disk; if it keeps failing, report it with the book, because red-ale found that it could not write something faithfully. **Code:** `1010` · **Name:** `save-verification` ## Related - [book.save](method/book.save) --- *red-ale Manual, `error/save-verification`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # sql-book The book is on a database server, which red-ale does not open. **Cause.** The path is a `mysql://`, `postgres://` or `postgresql://` URI. red-ale reads XML and SQLite books only, and refuses a server book before touching it. **Fix.** Open a copy of the book as a file: in GnuCash, use File > Save As to write an XML or SQLite book, then open that. Changes made to the copy are not reflected in the server's book. **Code:** `1004` · **Name:** `sql-book` --- *red-ale Manual, `error/sql-book`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # unbalanced A transaction would not balance, so nothing was changed. **Cause.** A transaction's split values must sum to exactly zero in its currency, and the call would have left one that does not. `data.imbalance` is how far off it is, the sum of the values, and `data.currency` the transaction's currency. The book is unchanged: no part of the call was applied. **Fix.** Make the values sum to zero: correct the amount that is wrong, or add a split for the difference. GnuCash would put the difference in an `Imbalance-` account; red-ale refuses instead, so nothing lands there unnoticed. **Code:** `2002` · **Name:** `unbalanced` ## Related - [transaction.post](method/transaction.post) --- *red-ale Manual, `error/unbalanced`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # unsaved-changes The book has changes not yet saved. **Cause.** `book.close` was called on a book with unsaved changes and with neither `save` nor `discard`. The book stays open. **Fix.** Call [book.close](method/book.close) with `save: true` to write the changes, or `discard: true` to drop them. **Code:** `1012` · **Name:** `unsaved-changes` ## Related - [book.close](method/book.close) - [book.save](method/book.save) --- *red-ale Manual, `error/unsaved-changes`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # unsupported-uri The path is a URI scheme red-ale does not use. **Cause.** A book path may be a plain path, `file://`, `xml://` or `sqlite3://`. Any other scheme is refused. **Fix.** Pass a file path, or one of those URIs. **Code:** `1005` · **Name:** `unsupported-uri` --- *red-ale Manual, `error/unsupported-uri`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Accounts and the Actions menu GnuCash's Edit and Actions menus for Accounts mapped to methods - New Account, Edit Account, Delete Account, Cascade, Renumber Subaccounts, Transfer, Reconcile, Auto clear, Check and Repair, View Lots. Find Account, Open Account and the New Account Hierarchy assistant have no counterpart. The Account tree window's **Edit** and **Actions** menus are about Accounts. Scheduled transactions, budgets, stock splits and the other assistants are on [Tools and scheduled transactions](gnucash/tools-menu) and [Stock assistants](gnucash/stock-assistants). ## Edit menu | GnuCash | red-ale | |---|---| | Edit Account | [`account.update`](method/account.update): name, type, commodity, code, description, notes, placeholder, hidden, colour, tax flag, balance limits, associated Accounts. A type may change only to a compatible one when the Account has Splits. [`account.get`](method/account.get) reads what is there | | Delete Account... | [`account.delete`](method/account.delete). An Account with Transactions needs a choice: delete them (whole Transactions go) or `moveTo` another Account of the same type. The same for a sub-account, of which at most one is allowed. GnuCash, given no choice, deletes the Splits and leaves `Imbalance` ones; red-ale never does | | Cascade Account Properties... | [`account.cascade`](method/account.cascade): colour, placeholder or hidden on an Account and all below it | | Renumber Subaccounts... | [`account.renumber`](method/account.renumber): a prefix, an interval and a number of digits | | Find Account | [`account.list`](method/account.list) or [`account.tree`](method/account.tree), filtered by you | | Open Account, Open Subaccount | [`transaction.list`](method/transaction.list) for that Account and a date range; for its sub-accounts too, list each. [`account.balance`](method/account.balance) gives its balance, with `includeSubaccounts` for the subtree's | | Find... | [`transaction.find`](method/transaction.find) | | Cut, Copy, Paste | Not provided. Move an Account with [`account.move`](method/account.move) | | Preferences, Style Sheets | [From GnuCash: Preferences and book options](gnucash/preferences-and-book-options), [Reports](gnucash/reports-menu) | | Tax Report Options | [`account.update`](method/account.update) with `taxRelated` and the US tax-code fields. The flag and codes are kept so GnuCash's tax reports still work on the book; red-ale has no tax report | ## Actions menu | GnuCash | red-ale | |---|---| | New Account... | [`account.create`](method/account.create). Give `name`, `type` and `commodity`; `parent` defaults to the root. `openingBalance` adds the opening balance Transaction against the opening-balance Account ([`account.openingBalanceAccount`](method/account.openingBalanceAccount)). It also takes the Account's SCU, notes, colour, balance limits and the Accounts it remembers for dividends and gains | | New Account Hierarchy... | **Not provided.** There are no Account templates ([File menu](gnucash/file-menu)) | | Transfer... | [`transaction.transfer`](method/transaction.transfer), with a `rate` or `toAmount` when the Accounts' Commodities differ | | Reconcile... | [`reconcile.start`](method/reconcile.start), `reconcile.status`, `reconcile.finish` and `reconcile.postpone`: see [Reconciliation](concept/reconciliation) | | Auto clear... | [`reconcile.findAutoClear`](method/reconcile.findAutoClear), then [`reconcile.autoClear`](method/reconcile.autoClear) | | Stock Split... | [`stock.split`](method/stock.split): see [Stock assistants](gnucash/stock-assistants) | | View Lots... | [`lot.list`](method/lot.list), [`lot.get`](method/lot.get); see [Tools](gnucash/tools-menu) | | Check & Repair > Check & Repair Account | [`scrub.checkAndRepair`](method/scrub.checkAndRepair) with `account` | | Check & Repair > Check & Repair Subaccounts | The same with `subaccounts: true` | | Check & Repair > Check & Repair All | The same with no Account | | Reset Warnings... | Not provided. red-ale asks nothing | | Rename Page | Not provided | | Online Actions (Get Balance, Get Transactions, Issue SEPA Transaction...) | **Not supported.** See [Not in red-ale](gnucash/not-in-red-ale) | | Scheduled Transactions, Budget | [Tools and scheduled transactions](gnucash/tools-menu) | **Check & Repair** runs only when you ask. GnuCash also scrubs a book as it loads; red-ale does not ([Imbalance, orphans and scrubs](concept/imbalance-and-scrubs)). Add `lots: true` to include the Lot scrub. Each repair is reported in `repairs`. ## Other things the New Account dialog did | GnuCash | red-ale | |---|---| | Security/Currency Select... | `commodity` as `USD` or `NASDAQ::AAPL`; make a new security first with [`commodity.create`](method/commodity.create) ([Commodities and currencies](concept/commodities-and-currencies)) | | Get Online Quotes (on a security) | `quoteFlag` and `quoteSource` on the Commodity; see [Prices and exchange rates](concept/prices-and-exchange-rates) | | Placeholder, Hidden | `placeholder`, `hidden` | | Show hidden accounts, Filter by... | `excludeHidden` on `account.list` and `account.tree` | ## Related - [The chart of accounts](concept/chart-of-accounts) - [Account types](concept/account-types) - [Reconciliation](concept/reconciliation) - [Imbalance, orphans and scrubs](concept/imbalance-and-scrubs) - [account.create](method/account.create) - [account.update](method/account.update) - [account.delete](method/account.delete) - [reconcile.start](method/reconcile.start) - [scrub.checkAndRepair](method/scrub.checkAndRepair) - [Set up accounts](guide/set-up-accounts) - [Reconcile an account](guide/reconcile-an-account) --- *red-ale Manual, `gnucash/account-menu`. Adapted from GnuCash's documentation, `manual/ch_GUIMenus.docbook#AccTree-actions-menu`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Business menu GnuCash's Business menu mapped to methods - Customers, Vendors, Employees, Jobs, Invoices, Bills, Expense Vouchers, Process Payment, due reminders, Sales Tax Tables and Billing Terms. Find windows are list methods; printing is report.run. GnuCash's **Business** menu has a submenu for each kind of Owner. red-ale has the same objects, each with `create`, `get`, `list` and `update` methods, and a "Find" window is a `list` method. See [Business documents](concept/business-documents) for the model. ## Customer | GnuCash | red-ale | |---|---| | Customers Overview | [`customer.list`](method/customer.list) | | New Customer... | [`customer.create`](method/customer.create): ID (from the next counter if you leave it out), name, address, terms, tax settings, credit limit. Edit with [`customer.update`](method/customer.update); [`customer.get`](method/customer.get) reads one | | Find Customer... | [`customer.list`](method/customer.list), filtered by you | | New Invoice... | [`invoice.create`](method/invoice.create) for the Customer, then [`invoice.addEntry`](method/invoice.addEntry) for each line. Make a credit note with `creditNote: true` | | Edit Invoice | [`invoice.update`](method/invoice.update), [`invoice.updateEntry`](method/invoice.updateEntry) and [`invoice.removeEntry`](method/invoice.removeEntry), while it is unposted. [`invoice.totals`](method/invoice.totals) gives the subtotal, tax and total | | Post (in the invoice window) | [`invoice.post`](method/invoice.post): the A/Receivable Account, the posting date, an optional due date | | Unpost | [`invoice.unpost`](method/invoice.unpost) | | Duplicate Invoice | [`invoice.duplicate`](method/invoice.duplicate) | | Find Invoice... | [`invoice.list`](method/invoice.list) | | New Job..., Find Job... | [`job.create`](method/job.create), [`job.list`](method/job.list) | | Process Payment... | [`payment.openItems`](method/payment.openItems) lists what can be paid, then [`payment.process`](method/payment.process); one document: [`invoice.pay`](method/invoice.pay) | | Invoices Due Reminder | [`invoice.due`](method/invoice.due) | ## Vendor | GnuCash | red-ale | |---|---| | Vendors Overview, Find Vendor... | [`vendor.list`](method/vendor.list), [`vendor.get`](method/vendor.get) | | New Vendor... | [`vendor.create`](method/vendor.create), [`vendor.update`](method/vendor.update) | | New Bill..., Find Bill... | [`invoice.create`](method/invoice.create) for the Vendor, [`invoice.list`](method/invoice.list). Everything above for invoices applies to bills; post to an A/Payable Account | | New Job..., Find Job... | [`job.create`](method/job.create), [`job.list`](method/job.list) | | Process Payment... | [`payment.process`](method/payment.process) | | Bills Due Reminder | [`invoice.due`](method/invoice.due) | ## Employee | GnuCash | red-ale | |---|---| | Employees Overview, Find Employee... | [`employee.list`](method/employee.list), [`employee.get`](method/employee.get) | | New Employee... | [`employee.create`](method/employee.create), [`employee.update`](method/employee.update) | | New Expense Voucher..., Find Expense Voucher... | [`invoice.create`](method/invoice.create) for the Employee, [`invoice.list`](method/invoice.list) | | Process Payment... | [`payment.process`](method/payment.process) | ## The rest of the menu | GnuCash | red-ale | |---|---| | Sales Tax Table | [`taxTable.create`](method/taxTable.create), `.get`, `.list`, `.update` and `.delete`. A table in use cannot be deleted | | Billing Terms Editor | [`billTerm.create`](method/billTerm.create), `.get`, `.list`, `.update` and `.delete` | | Business Linked Documents | [`docLink.documents`](method/docLink.documents) | | Orders | [`order.create`](method/order.create), [`order.addEntry`](method/order.addEntry), [`order.close`](method/order.close) and the rest of `order.*` | | File > Properties > Counters tab | [`counter.list`](method/counter.list), [`counter.set`](method/counter.set) | | File > Properties > Business tab | [`book.options`](method/book.options), [`book.setOptions`](method/book.setOptions): the company details, the default invoice report | ## Printing an invoice GnuCash's File > Print Invoice runs the Book's **Default Invoice Report** for the document, falling back to the [Printable Invoice](report/printable-invoice) when that setting is not an invoice report. In red-ale that is [`report.run`](method/report.run) (or [`report.export`](method/report.export) for HTML) with the invoice report and its **Invoice Number** option set to the document's GUID: 1. Read `defaultInvoiceReport` from [`book.options`](method/book.options). 2. If it names an invoice report red-ale has, run that. If it is empty, or names one red-ale does not have (the Easy or Fancy Invoice, say), run the Printable Invoice, as GnuCash falls back to it. 3. Pass `{"General": {"Invoice Number": ""}}` as `options`. The company details printed on it are the book's Business options. The Easy, Fancy, Tax and Australian Tax invoices and the Receipt are not ported; see [Reports menu](gnucash/reports-menu). ## What is not here GnuCash has no payroll system and neither has red-ale. The customer, vendor, employee and job reports, aging reports and the Customer Summary are not ported: write them as [User reports](concept/report-scripts). ## Related - [Business documents](concept/business-documents) - [Account types](concept/account-types) - [Reports menu and the report window](gnucash/reports-menu) - [customer.create](method/customer.create) - [invoice.create](method/invoice.create) - [invoice.post](method/invoice.post) - [payment.process](method/payment.process) - [taxTable.create](method/taxTable.create) - [billTerm.create](method/billTerm.create) --- *red-ale Manual, `gnucash/business-menu`. Adapted from GnuCash's documentation, `manual/ch_GUIMenus.docbook#AccTree-business-menu`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # File menu and the New File assistant GnuCash's File menu mapped to methods - File > New File is book.create, Open is book.open, Save is book.save, Revert is book.close with discard, Export is the export methods, Properties is book.options. There is no Save As, no Print and no Account templates. GnuCash's **File** menu opens, saves and exports books. In red-ale every item is a method, and there is no window to start from. | GnuCash | red-ale | |---|---| | File > New File | [`book.create`](method/book.create) makes an empty book (just the root Account) at a path that must be free: `format` is `xml` (the default, gzipped unless `compressed: false`) or `sqlite`. See below for the New Account Hierarchy assistant | | File > Open... | [`book.open`](method/book.open). Pass `readOnly: true` to look without taking the lock. [`book.info`](method/book.info) says what you opened | | File > Open > recently opened files | Not provided; keep your own list of paths | | File > Import > ... | [From GnuCash: Import and Export](gnucash/import-and-export) | | File > Import > Replay GnuCash .log file... | [`book.replayJournal`](method/book.replayJournal), to recover work from a journal after a crash | | File > Save | [`book.save`](method/book.save): backs up the previous file, writes the book, reads it back to check, starts a new journal | | File > Save As... | **Not provided.** `book.save` writes the book to the path it was opened from. To keep a copy, copy the file when the book is saved and closed. To change an XML book from gzipped to plain, pass `compressed` to `book.save`. To change between XML and SQLite use GnuCash | | File > Revert | [`book.close`](method/book.close) with `discard: true`, then `book.open` again. Unsaved changes are lost | | File > Print, Page Setup | Not provided. A report is exported as HTML ([`report.export`](method/report.export)) and printed from a browser, or turned into PDF with a converter ([Reports](concept/reports)) | | File > Export > Export Account Tree to CSV | [`export.csvTree`](method/export.csvTree) | | File > Export > Export Transactions to CSV | [`export.csvTransactions`](method/export.csvTransactions) | | File > Export > Export Active Register to CSV... | [`export.csvTransactions`](method/export.csvTransactions) for that one Account | | File > Export > Export Accounts | [`export.accounts`](method/export.accounts): a new book with the Account tree and Commodities and no Transactions | | File > Properties | [`book.options`](method/book.options) and [`book.setOptions`](method/book.setOptions); numbering in [`counter.list`](method/counter.list) and [`counter.set`](method/counter.set). See [Preferences and book options](gnucash/preferences-and-book-options) | | File > Close | [`book.close`](method/book.close). With unsaved changes it refuses unless you pass `save` or `discard` | | File > Quit | Stop the process: `red-ale serve` and `red-ale mcp` end with the signal or the closed connection. Close the book first, so its lock is released | ## Starting a book GnuCash's New File runs the **New Account Hierarchy Setup** assistant, which builds a starting tree of Accounts from a localised template (a checkbook, a business...). **red-ale has no Account templates and no such assistant.** Build the tree yourself with [`account.create`](method/account.create) ([The chart of accounts](concept/chart-of-accounts)), import one from CSV ([Import and Export](gnucash/import-and-export)), or start from another book's tree with [`export.accounts`](method/export.accounts). Opening balances go in with the Account: [`account.create`](method/account.create) takes an `openingBalance`, and [`account.openingBalanceAccount`](method/account.openingBalanceAccount) finds the equity Account that holds them. ## The first run GnuCash's Welcome screen, Tip of the Day, tabs and toolbars have no counterpart. You do not "run" red-ale and see a window: you call `book.create` or `book.open` and then the other methods. See [Windows, registers and the Account tree](gnucash/windows-and-registers). ## Moving a book you have Copy your `.gnucash` file, open the copy, and read or change it. GnuCash opens the result. GnuCash and red-ale never write one book at once: the second to open is told it is locked ([`book-locked`](error/book-locked)). See [Coming from GnuCash](concept/coming-from-gnucash). ## Related - [Books and files](concept/books-and-files) - [Read-only books](concept/read-only-books) - [The Configuration](concept/configuration) - [Import and export](gnucash/import-and-export) - [Windows and registers](gnucash/windows-and-registers) - [book.create](method/book.create) - [book.open](method/book.open) - [book.save](method/book.save) - [book.close](method/book.close) - [Set up accounts](guide/set-up-accounts) --- *red-ale Manual, `gnucash/file-menu`. Adapted from GnuCash's documentation, `manual/ch_GUIMenus.docbook#AccTree-file-menu`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Import and export GnuCash's File > Import and File > Export mapped to methods - QIF, CSV transactions, accounts, prices, bills and invoices, and customers and vendors through import.preview and import.apply; exports through the export methods. OFX, QFX, MT940 and the AqBanking formats are not supported. GnuCash imports through assistants that ask you questions as they go. red-ale always works in two steps: a **preview** that reads the file and changes nothing, then an **apply** or a **discard**. The answer to the preview is the Import proposal. See [Importing and matching](concept/importing-and-matching) for how it matches and what you can change. ## Import | GnuCash | red-ale | |---|---| | File > Import > Import QIF... | [`import.preview`](method/import.preview) with `format` `qif`. Only QIF takes several files. Which Account each QIF category goes to is a Configuration setting, `import.qifAccountMap` | | File > Import > Import Transactions from CSV... | `format` `csvTransactions`, with a `layout`: the separator, the date and number formats, and what each column is. A saved layout is named in the Configuration (`import.csvLayouts.*`). Only this format goes through the duplicate matcher | | File > Import > Import Accounts from CSV... | `format` `csvAccounts` | | File > Import > Import Prices from CSV... | `format` `csvPrices` | | File > Import > Import Bills & Invoices... | `format` `csvDocuments` | | File > Import > Import Customers & Vendors... | `format` `csvOwners` | | The assistant's final page: Finish, or Cancel | [`import.apply`](method/import.apply) with your choices for each Transaction (`add`, `clear`, `update` or `skip`), or [`import.discard`](method/import.discard) | | The Match Picker and the Import Map Editor | `matches` in the proposal, and [`importMap.list`](method/importMap.list), [`importMap.delete`](method/importMap.delete) ([Tools](gnucash/tools-menu)) | | File > Import > Import Log Replayer... | [`book.replayJournal`](method/book.replayJournal), for the `.log` journal GnuCash writes beside a book | The file goes in the call as text; there is no path to read. A proposal that does not balance is not refused, as in GnuCash: applying it adds an `Imbalance-` split, which is flagged in the proposal beforehand. Rows that cannot be imported are listed in `errors` and left out of the apply. ## Export | GnuCash | red-ale | |---|---| | File > Export > Export Transactions to CSV... | [`export.csvTransactions`](method/export.csvTransactions): Accounts, a date range, `layout` of `complex` (one line per Split) or `simple` (one line per Transaction). The text comes back in the result; no file is written | | File > Export > Export Active Register to CSV... | The same with the one Account | | File > Export > Export Account Tree to CSV... | [`export.csvTree`](method/export.csvTree) | | File > Export > Export Accounts (a new book with the Account tree and no Transactions) | [`export.accounts`](method/export.accounts). It never overwrites a file | | Report > Export Report... | [`report.export`](method/report.export) ([Reports menu](gnucash/reports-menu)) | ## Not supported Open Financial Exchange (OFX and QFX), the AqBanking formats (MT940, MT942, MT535, DTAUS, CAMT 052, and the others), online banking and the HBCI setup are not in red-ale. Convert such a file to QIF or CSV first, or see [Not in red-ale](gnucash/not-in-red-ale). ## Related - [Importing and matching](concept/importing-and-matching) - [File menu and the New File assistant](gnucash/file-menu) - [Not in red-ale](gnucash/not-in-red-ale) - [import.preview](method/import.preview) - [import.apply](method/import.apply) - [import.discard](method/import.discard) - [export.csvTransactions](method/export.csvTransactions) - [export.csvTree](method/export.csvTree) - [export.accounts](method/export.accounts) - [book.replayJournal](method/book.replayJournal) - [Import transactions](guide/import-transactions) --- *red-ale Manual, `gnucash/import-and-export`. Adapted from GnuCash's documentation, `guide/ch_importing.docbook#chapter_importing`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Not in red-ale What GnuCash does that red-ale does not, and what to do instead - the GUI, online banking, OFX and the AqBanking formats, Finance::Quote, PDF export, MySQL and PostgreSQL books, the Python and Guile interfaces, and the business and tax reports that are not ported. red-ale aims at GnuCash's behaviour on your file, driven by a program. Anything that is a window, needs a bank or a service outside red-ale, or is too narrow to carry is left out. Your file is not affected: anything in the book that red-ale does not use is kept and written back unchanged. This page lists what is left out and what to use instead. ## The graphical interface | GnuCash | Instead | |---|---| | Windows, tabs, toolbars, summary bars | The methods ([Windows and registers](gnucash/windows-and-registers)) | | Account registers and their styles, autocompletion | [`transaction.list`](method/transaction.list), [`transaction.post`](method/transaction.post) ([Transaction](gnucash/transaction-menu)) | | Window state file (`.gcm`), Tip of the Day, Reset Warnings | None | | Check printing and check formats | None. Export the data and print cheques with another tool | | New Account Hierarchy assistant, Account templates | Build the tree with `account.create`, or import it from CSV ([File menu](gnucash/file-menu)) | | Financial Calculator, Loan Repayment Calculator | [Loans and interest](concept/loans-and-interest) gives the formula; [`scheduledTransaction.loan`](method/scheduledTransaction.loan) works out a loan's payment | | Stock Transaction assistant | Each of its transactions is a [`transaction.post`](method/transaction.post) ([Stock assistants](gnucash/stock-assistants)) | | Autosave | None. Call [`book.save`](method/book.save) when you want the file written | ## Banks and files from banks Online banking through AqBanking (HBCI, FinTS, SEPA, Get Balance, Get Transactions), the Online Banking preferences and setup, OFX and QFX import, and the AqBanking file formats (MT940, MT942, MT535, DTAUS, CAMT 052, Q45, Swiss YellowNet, Olympic ERI) are not supported. Convert a statement to QIF or CSV with another tool, then [import it](gnucash/import-and-export). ## Online quotes GnuCash fetches quotes through Finance::Quote, a Perl library. red-ale does not use it. It has its own quote services, off until you turn on `quotes.network`, and [`price.fetchQuotes`](method/price.fetchQuotes) fetches into the price database ([Prices and exchange rates](concept/prices-and-exchange-rates)). A Commodity's quote source in the book is kept. ## Reports - **PDF export.** [`report.export`](method/report.export) writes HTML. Turn it into PDF with `pandoc` or any HTML-to-PDF converter. - **Business reports.** The Customer, Vendor, Employee, Owner and Job reports, Receivable and Payable Aging, the Customer Summary, the Easy, Fancy and Tax invoices and the Receipt are not ported. The Printable Invoice is ([Business](gnucash/business-menu)). - **Tax and regional reports.** The US income tax report and TXF export, the German income tax report and the Income and GST Statement. - **Sample and other reports.** Hello World, Sample Graphs, the Lot Viewer, the Register report, and the eguile Balance Sheet (the [Balance Sheet](report/balance-sheet) gives its figures). Where you need one of these, write it as a User report: a short script in red-ale's report language, run with [`report.run`](method/report.run) like the built-in ones. See [Report scripts](concept/report-scripts). ## Books on a server MySQL, MariaDB and PostgreSQL books are not opened: [`book.open`](method/book.open) refuses them with [`sql-book`](error/sql-book) before it touches anything. In GnuCash, use **File > Save As...** to save the book as SQLite or XML, then open that file. XML and SQLite books are supported. ## Programming interfaces | GnuCash | Instead | |---|---| | Python bindings and the REST API example built on them | JSON-RPC, MCP, or `red-ale exec` ([Coming from GnuCash](concept/coming-from-gnucash)) | | Guile scripting and Scheme reports | Reports are red-ale's own scripts; red-ale never runs Guile ([Report scripts](concept/report-scripts)) | | `gnucash-cli`: quotes, reports from the command line | `red-ale exec` with `price.fetchQuotes`, `report.run` and the other methods | ## Book currency GnuCash has a book currency flag that upstream never implemented. red-ale does not implement it either. ## Related - [Report scripts](concept/report-scripts) - [Coming from GnuCash](concept/coming-from-gnucash) - [Importing and matching](concept/importing-and-matching) - [Stock assistants](gnucash/stock-assistants) - [Reports menu and the report window](gnucash/reports-menu) - [Import and export](gnucash/import-and-export) - [sql-book](error/sql-book) - [report.export](method/report.export) - [price.fetchQuotes](method/price.fetchQuotes) - [Set up accounts](guide/set-up-accounts) - [Record prices and commodities](guide/record-prices) --- *red-ale Manual, `gnucash/not-in-red-ale`. Adapted from GnuCash's documentation, `guide/ch_python_bindings.docbook#ch_python_bindings`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Preferences and book options GnuCash's Edit > Preferences become Configuration settings read with config.get and changed with config.set; File > Properties (Book Options) become book.options and book.setOptions, with counters in counter.list and counter.set. Preferences about windows, registers and printing have no counterpart. GnuCash keeps two kinds of settings. **Preferences** belong to the person and live in GSettings (dconf, the registry or a plist). **Book options** belong to the book and live in the file. red-ale keeps the same split: the **Configuration** is a file of the person's settings, and the book options stay in the book, where GnuCash reads them. See [Configuration](concept/configuration). ## Edit > Preferences [`config.schema`](method/config.schema) lists every setting with its type and default, [`config.get`](method/config.get) reads one or all, and [`config.set`](method/config.set) changes several at once, all or none. They work with no book open. | GnuCash tab | red-ale | |---|---| | Accounting Period | `accountingPeriod.start`, `.end` and `.fiscalYearEnd`. [`period.get`](method/period.get), [`period.set`](method/period.set) and [`period.dates`](method/period.dates) read, change and work out the dates ([Closing the books and the accounting period](concept/closing-the-books-and-accounting-period)). | | Accounts | Not provided. Colours, columns and the Account tree's filter are display. `excludeHidden` is a parameter of `account.list` and `account.tree` | | Business | The invoice and bill defaults are book options (below). Reminder days and the like are not provided | | General | Not provided: red-ale does not autosave, warn before saving or show a Tip of the Day. The date and number conventions are under Numbers, Date, Time | | Import | `import.settings.*` for the matcher's thresholds, `import.csvLayouts.*` for saved CSV layouts and `import.qifAccountMap` for QIF ([Importing and matching](concept/importing-and-matching)) | | Numbers, Date, Time | `locale` for the number, date and currency conventions (`C` by default, or a POSIX name such as `fr_FR`), `defaultCurrency`, and `reports.dateFormat` for reports | | Online Banking | Not supported ([Not in red-ale](gnucash/not-in-red-ale)) | | Online Quotes | `quotes.network` (off by default), `quotes.services.*` and `quotes.sources.*` ([Prices and exchange rates](concept/prices-and-exchange-rates)) | | Printing | Not provided: export the HTML of a report and print it from a browser | | Register, Register Defaults | Not provided: there is no register | | Reports | `reports.directory` (your own scripts), `reports.currency`, `reports.weekStart`, `reports.reverseBalancedAccounts` and `reports.limits.*` ([Reports](concept/reports)) | | Scheduled Transactions | Not provided. red-ale never runs scheduled transactions on its own; you ask with `scheduledTransaction.sinceLastRun` and then `.apply` ([Tools](gnucash/tools-menu)) | | Windows | Not provided | Document links have one setting, `docLinks.pathHead`, which [`docLink.pathHead`](method/docLink.pathHead) reads and [`docLink.setPathHead`](method/docLink.setPathHead) changes: it is the folder that relative links start from. It is in the Configuration, never in the book. red-ale has no GSettings. A setting you leave alone has its default. A key in the Configuration file that red-ale does not know is kept and listed in `unknown`. ## File > Properties (Book Options) [`book.options`](method/book.options) reads the options in the book and [`book.setOptions`](method/book.setOptions) changes them. An option you leave out is left alone. | GnuCash tab | red-ale | |---|---| | Accounts: Use Trading Accounts | `useTradingAccounts` ([Trading accounts](concept/trading-accounts)) | | Accounts: Day Threshold for Read-Only Transactions | `autoReadOnlyDays`; 0 turns it off ([Read-only books](concept/read-only-books)) | | Accounts: Use Split Action Field for Number | `splitActionForNum`. Turning it on adds the Book feature `Number Field Source` ([Books and files](concept/books-and-files)) | | Budgeting: Default Budget | `defaultBudget` ([Budgets](concept/budgets)) | | Business: company name, address, contact, phone, fax, email, website, company ID, tax number | `companyName`, `companyAddress`, `companyContactPerson`, `companyPhoneNumber`, `companyFaxNumber`, `companyEmailAddress`, `companyWebsiteUrl`, `companyId`, `taxNumber` | | Business: Default Invoice Report (and the layout, title and footer of invoices) | `defaultInvoiceReport` ([Business](gnucash/business-menu)) | | Counters | [`counter.list`](method/counter.list), [`counter.set`](method/counter.set). **⚠** The counter is the last number issued; the next document gets one more | Options that red-ale does not know are kept in the book as they are, and written back unchanged. ## Related - [The Configuration](concept/configuration) - [Closing the books and the accounting period](concept/closing-the-books-and-accounting-period) - [Importing and matching](concept/importing-and-matching) - [Prices and exchange rates](concept/prices-and-exchange-rates) - [File menu and the New File assistant](gnucash/file-menu) - [config.get](method/config.get) - [config.set](method/config.set) - [config.schema](method/config.schema) - [book.options](method/book.options) - [book.setOptions](method/book.setOptions) - [Set up the business features](guide/set-up-business) - [Configure red-ale](guide/configure-red-ale) --- *red-ale Manual, `gnucash/preferences-and-book-options`. Adapted from GnuCash's documentation, `manual/ch_Customize.docbook#set-prefs`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Reports menu and the report window GnuCash's Reports menu mapped to report names for report.run, and the report window's File and Edit menus mapped to report.saveConfiguration, report.export and report.styleSheets. The business and tax reports that are not ported are written as User reports. Every GnuCash report is a menu entry that opens a window. In red-ale a report is a name and some options given to [`report.run`](method/report.run), which returns the figures. [`report.list`](method/report.list) lists the names and [`report.options`](method/report.options) the options of one. See [Reports](concept/reports). ## Assets and liabilities, income and expense | GnuCash | red-ale | |---|---| | Assets & Liabilities > Balance Sheet | [Balance Sheet](report/balance-sheet) | | Assets & Liabilities > Balance Sheet (Multicolumn) | [Balance Sheet (Multicolumn)](report/balance-sheet-multicolumn) | | Assets & Liabilities > Net Worth Barchart, Net Worth Linechart | [Net Worth Barchart](report/net-worth-barchart), [Net Worth Linechart](report/net-worth-linechart) | | Assets & Liabilities > Asset Chart, Asset Piechart | [Assets over time](report/assets-over-time), [Assets](report/assets) | | Assets & Liabilities > Liability Chart, Liability Piechart | [Liabilities over time](report/liabilities-over-time), [Liabilities](report/liabilities) | | Assets & Liabilities > Advanced Portfolio | [Advanced Portfolio](report/advanced-portfolio) | | Assets & Liabilities > Investment Portfolio | [Investment Portfolio](report/investment-portfolio) | | Assets & Liabilities > Investment Lots | [Investment Lots](report/investment-lots) | | Assets & Liabilities > IFRS Weighted Average Cost Basis | [IFRS weighted average cost basis](report/ifrs-weighted-average-cost-basis-report) | | Assets & Liabilities > Average Balance | [Average Balance](report/average-balance) | | Assets & Liabilities > Price Scatterplot | [Price Scatterplot](report/price-scatterplot) | | Assets & Liabilities > Security Piechart | [Securities](report/securities) | | Income & Expense > Profit & Loss | [Profit & Loss](report/profit-loss) | | Income & Expense > Income Statement | [Income Statement](report/income-statement) | | Income & Expense > Income Statement (Multicolumn) | [Income Statement (Multicolumn)](report/income-statement-multicolumn) | | Income & Expense > Cash Flow, Cash Flow Barchart | [Cash Flow](report/cash-flow), [Cash Flow Barchart](report/cash-flow-barchart) | | Income & Expense > Income Chart, Income Piechart | [Income over time](report/income-over-time), [Income accounts](report/income-accounts) | | Income & Expense > Expense Chart, Expense Piechart | [Expense over time](report/expense-over-time), [Expense accounts](report/expense-accounts) | | Income & Expense > Income & Expense Barchart, Linechart | [Income & Expense chart](report/income-expense-chart), [Income & Expense linechart](report/income-expense-linechart) | | Income & Expense > Income vs. Day of Week, Expenses vs. Day of Week | [Income vs day of week](report/income-vs-day-of-week), [Expenses vs day of week](report/expenses-vs-day-of-week) | ## Budget, transaction and other reports | GnuCash | red-ale | |---|---| | Budget > Budget Report | [Budget Report](report/budget-report) | | Budget > Budget Balance Sheet, Budget Income Statement | [Budget Balance Sheet](report/budget-balance-sheet), [Budget Income Statement](report/budget-income-statement) | | Budget > Budget Profit & Loss | [Budget Profit & Loss](report/budget-profit-loss) | | Budget > Budget Chart, Budget Flow | [Budget chart](report/budget-chart), [Budget flow](report/budget-flow) | | Transaction Report | [Transaction Report](report/transaction-report) | | Transaction Report > Transaction Breakdown | [Transaction Breakdown](report/transaction-breakdown-report) | | General Journal | [General Journal](report/general-journal) | | General Ledger | [General Ledger](report/general-ledger) | | Trial Balance | [Trial Balance](report/trial-balance) | | Equity Statement | [Equity Statement](report/equity-statement) | | Account Summary | [Account Summary](report/account-summary) | | Reconciliation Report | [Reconciliation Report](report/reconciliation-report) | | Balance Forecast | [Balance Forecast](report/balance-forecast) | | Future Scheduled Transactions Summary | [Future Scheduled Transactions Summary](report/future-scheduled-transactions-summary) | | Custom Multicolumn Report | [Multicolumn View](report/multicolumn-view) | | Dashboard | [Dashboard](report/dashboard), a saved configuration built in | ## Business reports | GnuCash | red-ale | |---|---| | Print Invoice (File menu of an invoice) | [`report.run`](method/report.run) with the Book's **Default Invoice Report**, else the [Printable Invoice](report/printable-invoice). Set its **Invoice Number** option to the document's GUID: `{"General": {"Invoice Number": ""}}`. Details in [Business](gnucash/business-menu) | | Business > Customer Report, Vendor Report, Employee Report, Job Report | Not ported. Write them as a [User report](concept/report-scripts) | | Business > Receivable Aging, Payable Aging | Not ported: a [User report](concept/report-scripts) | | Business > Customer Summary | Not ported: a [User report](concept/report-scripts) | | Easy Invoice, Fancy Invoice, Tax Invoice, Australian Tax Invoice, Receipt | Not ported. Use the Printable Invoice, or a [User report](concept/report-scripts) | ## Tax and other reports not ported The Tax Schedule Report and TXF Export, the US and German income tax reports, and the Income and GST Statement are not in red-ale. The tax flags on Accounts are kept in the book (see [Accounts](gnucash/account-menu)), so GnuCash still has them. The Lot Viewer, Hello World, Sample Graphs and Welcome reports are not ported either. The Register report (Account Report) is the [Transaction Report](report/transaction-report) with one Account. Write the rest as [User reports](concept/report-scripts); see [Not in red-ale](gnucash/not-in-red-ale). ## The report window | GnuCash | red-ale | |---|---| | Options... | The `options` of [`report.run`](method/report.run), by option page and name, as [`report.options`](method/report.options) lists them | | File > Save Report Configuration, Save Report Configuration As | [`report.saveConfiguration`](method/report.saveConfiguration); change one with [`report.updateConfiguration`](method/report.updateConfiguration), rename with [`report.renameConfiguration`](method/report.renameConfiguration), delete with [`report.deleteConfiguration`](method/report.deleteConfiguration) | | File > Export Report... | [`report.export`](method/report.export) writes HTML; [`report.exportCsv`](method/report.exportCsv) gives CSV | | File > Print Report, Page Setup | Not provided. Export the HTML and print it from a browser | | Edit > Style Sheets... | [`report.styleSheets`](method/report.styleSheets), with [`report.createStyleSheet`](method/report.createStyleSheet), [`report.updateStyleSheet`](method/report.updateStyleSheet) and [`report.deleteStyleSheet`](method/report.deleteStyleSheet) | | Reload, Stop, Back, Forward, Refresh | Not needed. Call `report.run` again | ## Related - [Reports](concept/reports) - [Report scripts](concept/report-scripts) - [Business menu](gnucash/business-menu) - [Not in red-ale](gnucash/not-in-red-ale) - [report.run](method/report.run) - [report.export](method/report.export) - [report.saveConfiguration](method/report.saveConfiguration) - [report.styleSheets](method/report.styleSheets) - [Dashboard](report/dashboard) - [Print an invoice](guide/print-an-invoice) - [Write your own report](guide/write-your-own-report) --- *red-ale Manual, `gnucash/reports-menu`. Adapted from GnuCash's documentation, `manual/ch_GUIMenus.docbook#AccTree-reports-menu`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Stock assistants Actions > Stock Split is stock.split. The Stock Transaction assistant (Buy, Sell, Dividend, Return of Capital, Notional Distribution, Reverse Split) is not provided; each of its transactions is a transaction.post, and the recipes below say how. GnuCash has two assistants for investments, both in **Actions** when the register is a Stock or Mutual Fund Account. ## Stock Split | GnuCash | red-ale | |---|---| | Actions > Stock Split... | [`stock.split`](method/stock.split) | | Date, Shares, Description | `date`, `shares` (the number of shares **added**, not the ratio; negative for a reverse split: a 2-for-1 split of 90 shares is `"90"`), `description` | | New Price, Currency | `price` records the new price per share (source `user:stock-split`), in `priceCurrency`; `currency` is the Transaction's | | Cash in lieu | `cash`, the amount, with `assetAccount` (the Bank, Cash or Asset Account that receives it) and `incomeAccount` (the Account it comes from) | The result's `priceStatus` is `none`, `added`, `duplicate` or `rejected`. A same-day price from a higher-ranked source blocks the new one (`blockingPrice`), and the split is still recorded. The account must be `STOCK`, `MUTUAL` or `CURRENCY`. A stock split has value zero, so the holding changes and the cost does not; it never joins a Lot and produces no gain ([Lots and capital gains](concept/lots-and-capital-gains)). ## Stock Transaction assistant The Stock Transaction assistant walks through a Buy, Sell, Dividend, Return of Capital, Notional Distribution, Stock Split or Reverse Split. **red-ale does not provide it.** Its pages ask for a date, a type, the shares traded, the value net of fees, the cash Account, fees (capitalised or expensed) and gain; each becomes a Split of a [`transaction.post`](method/transaction.post). It calculates nothing for you, so you lose no calculation. | Transaction | Splits to post | |---|---| | Buy | Stock Account: `amount` shares, `value` the price paid (add the fees if you capitalise them). Cash Account: minus the total. Fees expensed: a Split in an expense Account | | Sell | Stock Account: `amount` minus the shares, `value` minus the cost. Cash Account: the proceeds net of fees. The gain or loss in an income Account, or leave it to [`lot.computeGains`](method/lot.computeGains) | | Dividend (cash) | Cash Account: the amount. Income Account (`Income:Dividends`): minus the amount. Fees if any | | Dividend (reinvested) | The assistant cannot do this in one transaction. Post the dividend to the Income Account against the stock Account, with the new shares as `amount` | | Return of Capital | A Split in the stock Account of amount `0` and negative `value` for the capital returned, against a debit to the cash Account. `stock.split` does not do this | | Notional Distribution | A Split with amount `0` in the stock Account against the Income Account | | Reverse Split | `stock.split` with negative `shares` | For a sale, see [Investments](concept/investments) for gross and net pricing of commissions. If you use Lots to compute gains, leave the gain Split out and run [`lot.scrubAccount`](method/lot.scrubAccount) or [`lot.computeGains`](method/lot.computeGains). If a non-zero price slips into a record that should not have one, check the price database for a Price it should not have made ([`price.list`](method/price.list), [`price.delete`](method/price.delete)). Multi-currency stock trading is not supported by GnuCash's assistant either; post those Transactions with the amounts and values in [`transaction.post`](method/transaction.post) ([Value and amount](concept/value-and-amount)). ## Related - [Investments](concept/investments) - [Lots and capital gains](concept/lots-and-capital-gains) - [Prices and exchange rates](concept/prices-and-exchange-rates) - [stock.split](method/stock.split) - [transaction.post](method/transaction.post) - [lot.computeGains](method/lot.computeGains) - [price.add](method/price.add) - [Buy and sell shares](guide/buy-and-sell-shares) - [Record dividends and return of capital](guide/record-dividends) --- *red-ale Manual, `gnucash/stock-assistants`. Adapted from GnuCash's documentation, `manual/ch_Tools_Assistants.docbook#stock-assistant`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Tools, scheduled transactions and budgets GnuCash's Tools menu and the Actions submenus for scheduled transactions and budgets mapped to methods - Find, General Journal, Price Database, Security Editor, Close Book, Lots, Import Map Editor, Since Last Run, Scheduled Transaction Editor, the loan assistant and Budget. The Loan Repayment Calculator and Online Banking Setup are not provided. ## Tools menu | GnuCash | red-ale | |---|---| | Price Database | [`price.list`](method/price.list), [`price.add`](method/price.add), [`price.update`](method/price.update), [`price.delete`](method/price.delete). The Remove Old Prices button is [`price.removeOld`](method/price.removeOld); the Get Quotes button is [`price.fetchQuotes`](method/price.fetchQuotes) ([Prices and exchange rates](concept/prices-and-exchange-rates)) | | Security Editor | [`commodity.list`](method/commodity.list), [`commodity.create`](method/commodity.create), [`commodity.update`](method/commodity.update), [`commodity.delete`](method/commodity.delete); namespaces with [`commodity.namespaces`](method/commodity.namespaces). "Show National Currencies" is [`currency.list`](method/currency.list). The display symbol is the Commodity's `userSymbol` | | Loan Repayment Calculator | **Not provided.** The arithmetic is in the formulas of scheduled transactions; [Loans and interest](concept/loans-and-interest) gives the equation. [`scheduledTransaction.loan`](method/scheduledTransaction.loan) returns the payment of a loan you set up | | Close Book | [`book.closeBooks`](method/book.closeBooks): a closing date, the equity Accounts for income and for expense, a description. Not `book.close` ([Closing the books](concept/closing-the-books-and-accounting-period)) | | Import Map Editor | [`importMap.list`](method/importMap.list), [`importMap.delete`](method/importMap.delete) | | Transaction Linked Documents | [`docLink.transactions`](method/docLink.transactions) | | General Journal | [`transaction.list`](method/transaction.list) per Account, or the [General Journal](report/general-journal) report, which lists every Transaction for a date range | | Online Banking Setup... | **Not supported** ([Not in red-ale](gnucash/not-in-red-ale)) | | Tax Report Options (Edit menu) | See [Accounts and Actions](gnucash/account-menu) | ## Find | GnuCash | red-ale | |---|---| | Edit > Find... (Find Transaction) | [`transaction.find`](method/transaction.find): criteria over Splits (text, amounts, dates, states, Accounts) combined with all, any or not. The result is Splits, like the register of the results | | Find Customer, Vendor, Employee, Job, Invoice, Bill, Voucher | The `list` methods of [Business](gnucash/business-menu) | ## Lots Editor GnuCash's **Actions > View Lots** window assigns the Splits of a stock Account to Lots and records gains. See [Lots and capital gains](concept/lots-and-capital-gains). | GnuCash | red-ale | |---|---| | The Lots in This Account panel (and "Show only open lots") | [`lot.list`](method/lot.list) with `state` of `all`, `open` or `closed`; [`lot.get`](method/lot.get) reads one with its Splits | | The Splits free panel | [`lot.freeSplits`](method/lot.freeSplits), which can show the gain each Split would realise against a Lot | | New Lot, Delete Lot | [`lot.create`](method/lot.create), [`lot.delete`](method/lot.delete) | | Title, Notes | [`lot.update`](method/lot.update) | | The >> and << buttons | [`lot.assignSplit`](method/lot.assignSplit), [`lot.removeSplit`](method/lot.removeSplit) | | Scrub Account, Scrub Lot | [`lot.scrubAccount`](method/lot.scrubAccount), [`lot.scrub`](method/lot.scrub) | | Compute capital gains | [`lot.computeGains`](method/lot.computeGains) | | Lots of invoices and payments | Created by [`invoice.post`](method/invoice.post) and the payment methods; [`lot.list`](method/lot.list) lists them too | ## Scheduled transactions | GnuCash | red-ale | |---|---| | Actions > Scheduled Transactions > Scheduled Transaction Editor | [`scheduledTransaction.list`](method/scheduledTransaction.list), `.get`, `.create`, `.update`, `.delete` | | Since Last Run... | [`scheduledTransaction.sinceLastRun`](method/scheduledTransaction.sinceLastRun) builds a proposal and changes nothing; [`scheduledTransaction.apply`](method/scheduledTransaction.apply) applies it with your choices. Never automatic: GnuCash runs it whenever a book opens, red-ale only when asked | | Mortgage & Loan Repayment... | [`scheduledTransaction.loan`](method/scheduledTransaction.loan) | | Actions > Schedule... (in a register) | [`scheduledTransaction.fromTransaction`](method/scheduledTransaction.fromTransaction) | | The window's calendar of upcoming dates | [`scheduledTransaction.occurrences`](method/scheduledTransaction.occurrences), and the [Future Scheduled Transactions Summary](report/future-scheduled-transactions-summary) report | ## Budget | GnuCash | red-ale | |---|---| | Actions > Budget > New Budget | [`budget.create`](method/budget.create) | | Open Budget | [`budget.get`](method/budget.get), [`budget.list`](method/budget.list) | | Copy Budget | [`budget.copy`](method/budget.copy) | | Delete Budget | [`budget.delete`](method/budget.delete) | | The budget window's cells | [`budget.setAmounts`](method/budget.setAmounts), [`budget.setNotes`](method/budget.setNotes) | | Options (name, period, number of periods) | [`budget.update`](method/budget.update) | | Estimate | [`budget.estimate`](method/budget.estimate) | | The sign scrub GnuCash runs when a file opens | [`budget.scrubSigns`](method/budget.scrubSigns), only when you ask | | Default budget (Book options) | [`book.options`](method/book.options), [`book.setOptions`](method/book.setOptions) `defaultBudget` | ## Related - [Scheduled transactions](concept/scheduled-transactions) - [Budgets](concept/budgets) - [Prices and exchange rates](concept/prices-and-exchange-rates) - [Lots and capital gains](concept/lots-and-capital-gains) - [Closing the books and the accounting period](concept/closing-the-books-and-accounting-period) - [transaction.find](method/transaction.find) - [price.add](method/price.add) - [commodity.create](method/commodity.create) - [book.closeBooks](method/book.closeBooks) - [lot.list](method/lot.list) - [scheduledTransaction.sinceLastRun](method/scheduledTransaction.sinceLastRun) - [Find transactions](guide/find-transactions) - [Run and export a report](guide/run-and-export-a-report) - [Schedule a transaction](guide/schedule-a-transaction) - [Record prices and commodities](guide/record-prices) - [Capital gains with lots](guide/capital-gains-with-lots) --- *red-ale Manual, `gnucash/tools-menu`. Adapted from GnuCash's documentation, `manual/ch_GUIMenus.docbook#AccTree-tools-menu`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Transaction menu and the register GnuCash's register and Transaction menu mapped to methods - entering a Transaction is transaction.post, the Transfer dialog is transaction.transfer, and Void, Unvoid, Reverse, Delete, Duplicate, document links and the register's columns each have a method or a stated replacement. GnuCash enters Transactions in an Account **register**, a ledger of one Account's Splits. red-ale has no register. You post a whole Transaction with all its Splits in one call, and read an Account's Transactions back with a list. The register's menus map as follows. ## Transaction menu | GnuCash | red-ale | |---|---| | Enter Transaction (the Enter key) | [`transaction.post`](method/transaction.post): a date, a description and two or more Splits whose values sum to zero | | Cancel Transaction | Not needed: nothing is recorded until you call `post` | | Delete Transaction | [`transaction.delete`](method/transaction.delete) | | Remove Other Splits | [`transaction.update`](method/transaction.update) with `removeSplits`; the result must still balance and keep a Split | | Void Transaction | [`transaction.void`](method/transaction.void), with a `reason` | | Unvoid Transaction | [`transaction.unvoid`](method/transaction.unvoid) | | Add Reversing Transaction | [`transaction.reverse`](method/transaction.reverse): a new Transaction with every value negated, dated today unless you give `date` | | Duplicate Transaction | **No dedicated method.** [`transaction.get`](method/transaction.get) it and [`transaction.post`](method/transaction.post) the same Splits with a new date and num | | Cut, Copy, Paste Transaction | The same: get, then post. Delete the original for a cut | | Manage Document Link... | `docLink` on [`transaction.post`](method/transaction.post) and [`transaction.update`](method/transaction.update); an empty value removes the link | | Open Linked Document | [`docLink.transactions`](method/docLink.transactions) lists the Transactions that have a link, each with the URI it opens. A link with no `scheme://` is relative to the path head ([`docLink.pathHead`](method/docLink.pathHead), [`docLink.setPathHead`](method/docLink.setPathHead)). red-ale does not open the file | | Jump to Invoice | A Transaction posted from a business document names it; [`invoice.get`](method/invoice.get) reads the document ([Business](gnucash/business-menu)) | | Edit > Assign as payment... | [`payment.fromTransaction`](method/payment.fromTransaction) | ## Actions menu of the register | GnuCash | red-ale | |---|---| | Split Transaction | Always: a Transaction carries all its Splits. A "basic ledger" two-line Transaction is two Splits | | Edit Exchange Rate | The Split `amount` and `value` ([Value and amount](concept/value-and-amount)); or [`transaction.update`](method/transaction.update) with `recordPrice` | | Schedule... | [`scheduledTransaction.fromTransaction`](method/scheduledTransaction.fromTransaction) | | Blank Transaction, Go to Date, Jump to the other account | Not needed. [`transaction.list`](method/transaction.list) takes an Account and a date range; [`transaction.find`](method/transaction.find) finds Splits | | Transfer... | [`transaction.transfer`](method/transaction.transfer), below | ## The register's columns A line of a register is a Split. Its columns map to a Split's fields: | Register | Field | |---|---| | Date | `datePosted` of the Transaction | | Num | `num` of the Transaction; with the book option `splitActionForNum` on, the Split's `action`. The Split's `number` field gives whichever applies | | Description | `description` | | Transfer | The other Splits' Accounts (`account`) | | R | `reconcileState`: `n`, `c`, `y`, `f`, `v` ([Reconciliation](concept/reconciliation)) | | Deposit, Withdrawal, and the other debit and credit labels | The `value` and `amount` of the Split: positive is a debit, negative a credit. Methods always use this raw sign. GnuCash's formal accounting labels and reversed-sign display are display preferences and are not modelled ([Double entry](concept/double-entry)) | | Balance | [`account.balance`](method/account.balance), with `asOf` for another date | | Memo, Action | `memo`, `action` of the Split | | Notes | `notes` of the Transaction | | Shares, Price (a stock register) | `amount` and `value / amount` ([Investments](concept/investments)) | Autocompletion, the Tab-through entry, Cut and Paste of Splits, and the register styles (Basic Ledger, Auto-Split Ledger, Transaction Journal) have no counterpart. The Transaction Journal is the shape of a Transaction in the API, and the [General Journal](report/general-journal) report lists them all. ## The Transfer dialog GnuCash's Transfer dialog makes a two-Split Transaction between two Accounts and, when their Commodities differ, collects an exchange rate or the amount received. [`transaction.transfer`](method/transaction.transfer) is that dialog: - `from` (the account that gives, which must hold a currency), `to`, `amount` (in the `from` currency), `date`, `description`, `num`, `notes` and `memo`; - for Accounts in different Commodities, the `rate` (units of the `to` Commodity per unit of the `from` currency) or the `toAmount` received, or neither to use the price database's rate for the date. With no price at all the transfer is refused; - `recordPrice` (default true) records the rate as a Price, as the dialog does. The result gives the Transaction, the amount received, the rate and what happened to the Price. Entering a transfer fee is a Split you add by posting the Transaction yourself, as it is in GnuCash. The dialog's Fetch Rate button is [`price.fetchQuotes`](method/price.fetchQuotes) ([Prices and exchange rates](concept/prices-and-exchange-rates)). ## Read-only Transactions The register greys out Transactions it will not let you edit. Those that the methods refuse (`conflict`) are voided ones, ones posted from a business document, and those before the book's auto read-only threshold ([Transactions and Splits](concept/transactions-and-splits)). ## Related - [Transactions and Splits](concept/transactions-and-splits) - [Value and amount](concept/value-and-amount) - [Double entry](concept/double-entry) - [Windows and registers](gnucash/windows-and-registers) - [transaction.post](method/transaction.post) - [transaction.update](method/transaction.update) - [transaction.transfer](method/transaction.transfer) - [transaction.void](method/transaction.void) - [transaction.reverse](method/transaction.reverse) - [Transfer between accounts](guide/transfer-between-accounts) --- *red-ale Manual, `gnucash/transaction-menu`. Adapted from GnuCash's documentation, `manual/ch_GUIMenus.docbook#Trans-transaction-menu`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Windows and registers GnuCash's main windows mapped to methods - the Account tree window is account.tree, an Account register is transaction.list and transaction.post, the Reconcile window is reconcile.*, and the report, scheduled transaction, budget and business windows are their own methods. Tabs, toolbars and summary bars have no counterpart. red-ale has no windows. Each window of GnuCash is a view of the book, and a view is a method that returns the same information. The menus of each window are on their own pages; this page says where each window went. | GnuCash window | red-ale | |---|---| | Account tree (the main window, its Accounts page) | [`account.tree`](method/account.tree) gives the tree with balances; [`account.list`](method/account.list) a flat list; [`account.get`](method/account.get) one Account; [`account.balance`](method/account.balance) a balance, as of a date if you like. The menus are on [Accounts](gnucash/account-menu). `account.balance` includes the cleared and reconciled balances. Column choices are not modelled | | Account register (General Journal, Receivable, Payable and the others) | [`transaction.list`](method/transaction.list) for an Account and a date range, [`transaction.find`](method/transaction.find) for a search, [`transaction.post`](method/transaction.post) to enter. Entry and columns are on [Transaction](gnucash/transaction-menu) | | Reconcile window | [`reconcile.start`](method/reconcile.start), [`reconcile.status`](method/reconcile.status), [`reconcile.setState`](method/reconcile.setState), [`reconcile.finish`](method/reconcile.finish), [`reconcile.postpone`](method/reconcile.postpone). The Reconcile Information dialog is [`reconcile.info`](method/reconcile.info) and [`reconcile.setInfo`](method/reconcile.setInfo) ([Reconciliation](concept/reconciliation)) | | Report window | [`report.run`](method/report.run), [`report.export`](method/report.export) ([Reports](gnucash/reports-menu)) | | Scheduled Transaction Editor, Since Last Run | `scheduledTransaction.*` ([Tools](gnucash/tools-menu)) | | Budget window | `budget.*` ([Tools](gnucash/tools-menu)) | | Price Database, Security Editor | `price.*` and `commodity.*` ([Tools](gnucash/tools-menu)) | | Lots window | `lot.*` ([Tools](gnucash/tools-menu)) | | Customer, Vendor, Employee, Job, Invoice and Bill windows | `customer.*`, `vendor.*`, `employee.*`, `job.*` and `invoice.*` ([Business](gnucash/business-menu)) | | Find Transaction window | [`transaction.find`](method/transaction.find) | | Preferences, Book Options | [Preferences and book options](gnucash/preferences-and-book-options) | ## What has no counterpart - **Tabs, panes, toolbars, status bar, summary bar** and the *Window* menu. - **The saved window state.** GnuCash writes which pages were open into a `.gcm` file so that it can restore them. red-ale does not. - **Account tree filters and column choices.** Ask for what you want: `excludeHidden`, or filter the result yourself. - **Register styles** (Basic Ledger, Auto-Split, Transaction Journal), autocompletion, the double-line mode, sort and filter by. A list returns every Split in date order for you to filter. - **The summary bar** of Profit and Total Assets: run the [Balance Sheet](report/balance-sheet) or [Profit & Loss](report/profit-loss) for the same figures. - **Help.** The Manual you are reading is available through `help.topics`, `help.search` and `help.get`. ## Related - [The chart of accounts](concept/chart-of-accounts) - [Transactions and Splits](concept/transactions-and-splits) - [Reconciliation](concept/reconciliation) - [Transaction menu and the register](gnucash/transaction-menu) - [Accounts and the Actions menu](gnucash/account-menu) - [Reports menu and the report window](gnucash/reports-menu) - [account.tree](method/account.tree) - [transaction.list](method/transaction.list) - [reconcile.start](method/reconcile.start) - [Record deposits and withdrawals](guide/record-deposits-and-withdrawals) --- *red-ale Manual, `gnucash/windows-and-registers`. Adapted from GnuCash's documentation, `manual/ch_GUIMenus.docbook#gui-windows`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Back up and recover a book Every save backs up the previous file; a .log journal records changes between saves, and book.replayJournal puts them back after a crash. red-ale protects your book the way GnuCash does, with two safety nets. Each save first copies the old file to a timestamped backup. Between saves, every change is also written to a `.log` journal beside the book. If a session ends before you save, the journal still has the changes, and you can replay them onto the last saved file. ## Steps 1. **Save as usual** with [book.save](method/book.save). The result's `backup` is the path of the copy of the previous file (`book.gnucash` becomes `book.gnucash..gnucash`), and `removed` lists old backups and journals that passed their retention. `red-ale exec --retention-days 30` sets how long they are kept (30 by default); `--keep-backups-forever` keeps them all. 2. **Find the journal.** [book.info](method/book.info) gives its path as `journal`: a file named `..log`, written while the book is open. 3. **After a crash**, open the last saved book (not a backup, unless you mean to go back in time) and call [book.replayJournal](method/book.replayJournal) with the journal's `path`. It creates, updates or deletes each transaction by GUID. `created`, `updated` and `deleted` list what it touched, and `notFound` lists records whose transaction was missing. 4. **Check and save.** Look at the result and at [book.info](method/book.info), then call [book.save](method/book.save) to keep the recovered work. 5. **To go back to an older state**, close the book and copy a backup over it, or open the backup directly. A backup is an ordinary book file. Replay changes transactions only, not accounts. If a journal record needs an account the book no longer has, the replay refuses that record unless you pass `skipInvalid: true`, which skips and lists it. ## Example Saving after a change returns the path of the backup; replaying a journal that does not exist is refused cleanly. *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Savings","type":"BANK","parent":"Root:Asset","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"book.save","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "backup": "…", "removed": [], "compressed": false } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"book.replayJournal","params":{"path":"lost-session.log"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "error": { "code": 1008, "message": "…", "data": { "path": "…", "help": "error/io-error" } } } ``` ## Related - [book.save](method/book.save) - [book.info](method/book.info) - [book.replayJournal](method/book.replayJournal) - [io-error](error/io-error) - [file-format](error/file-format) - [Books and files](concept/books-and-files) --- *red-ale Manual, `guide/back-up-and-recover`. Adapted from GnuCash's documentation, `guide/ch_basics.docbook#basics-backup1`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Buy and sell shares Set up a security and a brokerage account, record a purchase with its commission, record a sale with the realised gain, and keep the share price up to date. Shares are a commodity that is not a currency. A holding of shares is an account of type `STOCK` whose commodity is the security, so its balance counts shares, not dollars. In a transaction, the share account's split has an *amount* in shares and a *value* in the transaction's currency: ten shares at 150.00 are an amount of 10 and a value of 1,500.00. ## Steps 1. **Create the security** with [commodity.create](method/commodity.create): a `namespace` (the exchange, such as `NASDAQ`), a `mnemonic` (the ticker) and a `fullname`. 2. **Create the accounts.** A brokerage placeholder (`ASSET`), a cash account for it (`BANK`), a `STOCK` account per security with `commodity` set to the security's ID (`NASDAQ::AAPL`), an expense for commissions and an income account for realised gains. 3. **Buy.** [transaction.post](method/transaction.post) in the cash account's currency (set `currency`, since the first split may be in shares): the share account `+value` with `amount` in shares, the commission expense `+`, and the cash account `-` for the total. 4. **Record the price** with [price.add](method/price.add), the commodity priced in the currency, so reports can value the holding. A buy or sell in the register records its price too if you pass `recordPrice: true`. 5. **Sell.** The cash account gets the proceeds less commission. The share account is credited at what the shares cost (the shares' amount negative, their value the cost basis). The difference between proceeds and cost is the realised gain, credited to the gains income account, or debited if it is a loss. 6. **Check** the number of shares with [account.balance](method/account.balance); the balance is in shares. For which shares were sold, with several purchases at different prices, see [Capital gains with lots](guide/capital-gains-with-lots). ## Example Buy 10 shares at 150.00 with a 9.95 commission, then sell 4 at 160.00. The cost of the 4 is 600.00; they are sold for 640.00, a gain of 40.00. *Example: with a new, empty book open as `book.gnucash`, at 2024-07-31T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"commodity.create","params":{"namespace":"NASDAQ","mnemonic":"AAPL","fullname":"Apple Inc"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "id": "NASDAQ::AAPL", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Brokerage","type":"ASSET","commodity":"USD","placeholder":true}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"account.create","params":{"name":"Cash","type":"BANK","parent":"Brokerage"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"account.create","params":{"name":"AAPL","type":"STOCK","parent":"Brokerage","commodity":"NASDAQ::AAPL"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "commodity": "NASDAQ::AAPL", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"account.create","params":{"name":"Commissions","type":"EXPENSE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":6,"method":"account.create","params":{"name":"Realised gains","type":"INCOME","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 6, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":7,"method":"account.create","params":{"name":"Opening Balances","type":"EQUITY","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 7, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":8,"method":"transaction.post","params":{"datePosted":"2024-07-01","description":"Deposit","splits":[{"account":"Brokerage:Cash","value":"5000.00"},{"account":"Opening Balances","value":"-5000.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 8, "result": { "balanced": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":9,"method":"transaction.post","params":{"datePosted":"2024-07-02","description":"Buy AAPL","currency":"USD","splits":[{"account":"Brokerage:AAPL","value":"1500.00","amount":"10"},{"account":"Commissions","value":"9.95"},{"account":"Brokerage:Cash","value":"-1509.95"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 9, "result": { "balanced": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":10,"method":"price.add","params":{"commodity":"NASDAQ::AAPL","currency":"USD","value":"160.00","date":"2024-07-15"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 10, "result": { "outcome": "added", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":11,"method":"transaction.post","params":{"datePosted":"2024-07-15","description":"Sell AAPL","currency":"USD","splits":[{"account":"Brokerage:Cash","value":"630.05"},{"account":"Commissions","value":"9.95"},{"account":"Brokerage:AAPL","value":"-600.00","amount":"-4"},{"account":"Realised gains","value":"-40.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 11, "result": { "balanced": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":12,"method":"account.balance","params":{"account":"Brokerage:AAPL"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 12, "result": { "balances": { "commodity": "NASDAQ::AAPL", "balance": { "num": "60000", "denom": "10000" }, "…": "…" }, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":13,"method":"account.balance","params":{"account":"Brokerage:Cash"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 13, "result": { "balances": { "commodity": "CURRENCY::USD", "balance": { "num": "412010", "denom": "100" }, "…": "…" }, "…": "…" } } ``` ## Related - [commodity.create](method/commodity.create) - [account.create](method/account.create) - [transaction.post](method/transaction.post) - [price.add](method/price.add) - [account.balance](method/account.balance) - [lot.assignSplit](method/lot.assignSplit) - [Investments](concept/investments) - [Stock assistants](gnucash/stock-assistants) --- *red-ale Manual, `guide/buy-and-sell-shares`. Adapted from GnuCash's documentation, `guide/ch_invest.docbook#chapter_invest`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Capital gains with lots Match each sale of shares to the purchases it came from by putting them in lots, so the book records the realised gain of every sale as GnuCash does. When you buy the same security several times at different prices and sell part of it, the gain depends on *which* shares you sold. A **lot** is a group of splits in one security account that opens with a purchase and closes when its shares are all sold. Putting each sale's shares into the lots they came from fixes the cost of each, and so the gain, a figure tax rules often ask for. The usual rule is first in, first out (FIFO): a sale uses the oldest lot first. The gain is written into the book as a split of its own in an income account, in the same transaction as the sale, so the books keep balancing in dollars. ## Steps 1. **Record the buys and the sale** as in [Buy and sell shares](guide/buy-and-sell-shares). At this point the sale's value is its proceeds; no gain is recorded anywhere. 2. **Assign by FIFO** with [lot.scrubAccount](method/lot.scrubAccount). It puts the account's splits into lots, splits a sale that spans two lots into one piece per lot, and calculates the gains. It lists the lots, transactions and accounts it created or changed; the gains go to an income account it creates, `Orphaned Gains-USD`. 3. **Look at the lots** with [lot.list](method/lot.list): each lot's open and close dates, its remaining shares (`balance`), whether it is `closed`, and its `realizedGains`. 4. **Choose the lots yourself?** Create a lot with [lot.create](method/lot.create), put splits in it one at a time with [lot.assignSplit](method/lot.assignSplit) and its `lot` (a split larger than the lot needs is cut into pieces and the rest is returned as `rest`), and compute its gains with [lot.computeGains](method/lot.computeGains). To fix a lot after other edits, use [lot.scrub](method/lot.scrub). 5. **Use your own gains account.** Pass `gainsAccount` to [lot.computeGains](method/lot.computeGains) to credit an income account you made, instead of `Orphaned Gains-USD`. ## Example Twenty shares are bought in two lots, at 150.00 and at 170.00, and fifteen are sold for 2,700.00 (180.00 each). FIFO sells all of the first lot, a gain of 300.00, and five of the second, a gain of 50.00. *Example: with a new, empty book open as `book.gnucash`, at 2024-07-01T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"commodity.create","params":{"namespace":"NASDAQ","mnemonic":"AAPL","fullname":"Apple Inc"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Brokerage","type":"ASSET","commodity":"USD","placeholder":true}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"account.create","params":{"name":"Cash","type":"BANK","parent":"Brokerage"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"account.create","params":{"name":"AAPL","type":"STOCK","parent":"Brokerage","commodity":"NASDAQ::AAPL"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"account.create","params":{"name":"Opening Balances","type":"EQUITY","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":6,"method":"transaction.post","params":{"datePosted":"2024-01-02","description":"Deposit","splits":[{"account":"Brokerage:Cash","value":"10000.00"},{"account":"Opening Balances","value":"-10000.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 6, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":7,"method":"transaction.post","params":{"datePosted":"2024-02-01","description":"Buy 10 AAPL","currency":"USD","splits":[{"account":"Brokerage:AAPL","value":"1500.00","amount":"10"},{"account":"Brokerage:Cash","value":"-1500.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 7, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":8,"method":"transaction.post","params":{"datePosted":"2024-03-01","description":"Buy 10 AAPL","currency":"USD","splits":[{"account":"Brokerage:AAPL","value":"1700.00","amount":"10"},{"account":"Brokerage:Cash","value":"-1700.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 8, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":9,"method":"transaction.post","params":{"datePosted":"2024-06-03","description":"Sell 15 AAPL","currency":"USD","splits":[{"account":"Brokerage:Cash","value":"2700.00"},{"account":"Brokerage:AAPL","value":"-2700.00","amount":"-15"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 9, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":10,"method":"lot.scrubAccount","params":{"account":"Brokerage:AAPL"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 10, "result": { "lotsCreated": [ "…", "…" ], "accountsCreated": [ "…" ], "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":11,"method":"lot.list","params":{"account":"Brokerage:AAPL"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 11, "result": [ { "closed": true, "openDate": "2024-02-01", "closeDate": "2024-06-03", "realizedGains": { "num": "30000", "denom": "100" }, "…": "…" }, { "closed": false, "openDate": "2024-03-01", "realizedGains": { "num": "5000", "denom": "100" }, "…": "…" } ] } ``` To choose lots by hand, create one and assign a split to it: *Example: with a copy of the `reports/investment-lots` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"lot.create","params":{"account":"Root:Assets:Broker:AAPL"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "closed": false, "splitCount": 0, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"lot.assignSplit","params":{"split":"d0000000000000000000000000000001"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "pieces": [ { "split": "d0000000000000000000000000000001", "lot": "…" } ], "rest": null, "newLots": [ "…" ] } } ``` ## Related - [lot.scrubAccount](method/lot.scrubAccount) - [lot.create](method/lot.create) - [lot.assignSplit](method/lot.assignSplit) - [lot.computeGains](method/lot.computeGains) - [lot.list](method/lot.list) - [lot.scrub](method/lot.scrub) - [Buy and sell shares](guide/buy-and-sell-shares) - [Lots and capital gains](concept/lots-and-capital-gains) - [Tools, scheduled transactions and budgets](gnucash/tools-menu) --- *red-ale Manual, `guide/capital-gains-with-lots`. Adapted from GnuCash's documentation, `guide/ch_invest.docbook#invest-sell1`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Check and repair a book Find and fix splits with no account, unbalanced transactions and broken lots with scrub.checkAndRepair, and know what each repair changed. A book that came from another program, an import with mistakes, or an old file can contain transactions that do not balance, or splits that point at an account that no longer exists. red-ale refuses to create these, but it can open a book that has them. A *scrub* finds them and repairs them in the way GnuCash's Check & Repair does, so GnuCash agrees with the result. Every repair is reported, so you can see what was changed before you save. ## What the scrubs do - **Orphans.** A split with no account is moved to an account called `Orphan-`, which is created if needed. ([scrub.orphans](method/scrub.orphans)) - **Imbalances.** A transaction whose values do not sum to zero gets one more split, in an account called `Imbalance-`, for the difference. The books then balance, and the Imbalance account shows what still needs a real home. ([scrub.imbalance](method/scrub.imbalance)) - **Lots.** Splits of a security account are assigned to lots and each lot's capital gains recomputed. ([lot.scrub](method/lot.scrub), [lot.scrubAccount](method/lot.scrubAccount)) See [Capital gains with lots](guide/capital-gains-with-lots). ## Steps 1. **Back up first.** A repair changes the book in memory, but you will want a copy of the file you started from. Save only after you have looked at the result. 2. **Run it** with [scrub.checkAndRepair](method/scrub.checkAndRepair). With no parameters it checks every transaction. Narrow it with `account` (and `subaccounts`) or a single `transaction`. Add `lots: true` to repair lots too, which GnuCash does not do by default. 3. **Read the `repairs`.** Each has a `kind` (`accountCreated`, `balanceSplitAdded`, and so on) and the transaction, split and account involved. An empty list means the book was clean. 4. **Finish the job by hand.** An `Imbalance-USD` account is a to-do list, not an answer. For each split in it, decide what the money really was, move the split to the right account with [transaction.update](method/transaction.update), and delete the Imbalance account when it is empty ([account.delete](method/account.delete)). 5. **Run it again.** A second run reports no repairs. 6. **Save** with [book.save](method/book.save). To repair just one transaction, call [scrub.imbalance](method/scrub.imbalance) with its `transaction` GUID. ## Example This GnuCash test book has an unbalanced transaction. The first run adds an Imbalance account and a balancing split; the second finds nothing to do. *Example: with a copy of the `gnucash/taxreport` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"scrub.checkAndRepair","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "repairs": [ { "kind": "accountCreated", "name": "Imbalance-USD", "commodity": "CURRENCY::USD", "…": "…" }, { "kind": "balanceSplitAdded", "…": "…" }, "…" ] } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"scrub.checkAndRepair","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "repairs": [] } } ``` ## Related - [scrub.checkAndRepair](method/scrub.checkAndRepair) - [scrub.imbalance](method/scrub.imbalance) - [scrub.orphans](method/scrub.orphans) - [scrub.currency](method/scrub.currency) - [lot.scrub](method/lot.scrub) - [lot.scrubAccount](method/lot.scrubAccount) - [book.save](method/book.save) --- *red-ale Manual, `guide/check-and-repair`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Close the books At the end of a period, move the income and expense balances into equity with book.closeBooks, so those accounts start the next period at zero. At the end of an accounting year, accountants *close the books*: the year's income and expenses are moved into equity (retained earnings) and the income and expense accounts return to zero. The reports for the new year then start clean, and the balance sheet shows the profit you kept. Closing does not stop you editing; it adds transactions. Not to be confused with [book.close](method/book.close), which closes the *file*. ## Steps 1. **Finish the period.** Enter every transaction up to the closing date, reconcile your accounts ([Reconcile an account](guide/reconcile-an-account)) and run [Check and repair](guide/check-and-repair). 2. **Save a copy** of the book first ([Back up and recover](guide/back-up-and-recover)). Closing adds transactions you cannot easily tell from your own. 3. **Choose the equity accounts** that take the income and the expenses; they may be one account. Create them if needed ([Set up accounts](guide/set-up-accounts)). 4. **Close** with [book.closeBooks](method/book.closeBooks): the closing `date`, `incomeTotalAccount`, `expenseTotalAccount` and a `description`. It posts, for each currency, one transaction for income and one for expenses, marked as closing transactions so reports can leave them out. A sub-account named after the currency is made under the equity account when more than one currency is closed. 5. **Check** with [account.balance](method/account.balance) and `asOf` the closing date: the income and expense accounts are zero at the end of that day. 6. **Save.** Run it once per period: it does not remember the date. An income or expense balance held in a security rather than a currency is refused. ## Example *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"book.closeBooks","params":{"date":"2024-03-31","incomeTotalAccount":"Root:Equity","expenseTotalAccount":"Root:Equity","description":"Close"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "transactions": [ { "guid": "…", "kind": "income", "currency": "CURRENCY::USD", "equityAccount": "…", "total": { "num": "-257300", "denom": "100" } }, "…" ], "createdAccounts": [ "…", "…" ] } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.balance","params":{"account":"Root:Income","asOf":"2024-03-31"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "balances": { "balance": { "num": "0", "denom": "100" }, "…": "…" }, "…": "…" } } ``` ## Related - [book.closeBooks](method/book.closeBooks) - [account.balance](method/account.balance) - [book.save](method/book.save) - [book.close](method/book.close) --- *red-ale Manual, `guide/close-the-books`. Adapted from GnuCash's documentation, `manual/ch_Tools_Assistants.docbook#tool-close-book`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Configure red-ale Change red-ale's own settings (accounting period, report directory, network) with config.set, and the settings stored in the book with book.setOptions. There are two places where settings live, and it matters which you change. - **The Configuration** belongs to you and your machine: the accounting period that reports default to, the folder of your User reports, whether the network may be used for online quotes, import settings and limits. It is a JSON file (by default `~/.config/red-ale/config.json`), shared by every book you open. This is what GnuCash calls *preferences*. - **Book options** belong to the book and travel with it: the company's name and details, whether to use trading accounts, the auto read-only threshold, which source the number field uses, the default budget. GnuCash stores them in the file, so GnuCash sees them too. ## Steps 1. **See what can be set** with [config.schema](method/config.schema): every setting, its type, default and description. [config.get](method/config.get) returns the current values; give a `path` such as `quotes.network` for one. Secrets (such as quote service keys) are shown only as set or unset. 2. **Change settings** with [config.set](method/config.set): `changes` maps a path to its new value, and `null` restores a default. The whole call is checked first: a bad path or value changes nothing and the error names it ([invalid-params](error/invalid-params)). Neither call needs a book to be open. Over MCP the network setting cannot be changed. 3. **Set the accounting period** with [period.set](method/period.set): `start` and `end`, each a relative choice (`year`, `previous-month`, `fiscal-year`, ...) or a date, and `fiscalYearEnd` as `MM-DD` for the fiscal-year choices. [period.get](method/period.get) reads it, and [period.dates](method/period.dates) shows the first and last day it works out to for today, or a date you give. Reports use it for relative dates. 4. **Point to your report scripts** with `reports.directory` ([Write your own report](guide/write-your-own-report)). 5. **Allow the network** only if you want online quotes ([Record prices and commodities](guide/record-prices)): `{"changes": {"quotes.network": true}}`. 6. **Change book options** with [book.setOptions](method/book.setOptions) and read them with [book.options](method/book.options). Set only the ones you want to change. For the business options, see [Set up the business features](guide/set-up-business). The changes are made in memory and kept when you save the book. 7. **Use another file for a run** with `red-ale --config ` or `--no-config` on the command line, which keeps the settings in memory for that process only. ## Example *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`, at 2024-07-01T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"config.schema","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "title": "red-ale Configuration", "type": "object", "properties": { "…": "…" }, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"config.set","params":{"changes":{"quotes.network":true}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "values": { "quotes.network": true }, "clearedKeys": [], "configFile": null } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"config.get","params":{"path":"quotes.network"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "path": "quotes.network", "value": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"period.set","params":{"start":"fiscal-year","end":"fiscal-year","fiscalYearEnd":"03-31"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "start": "fiscal-year", "end": "fiscal-year", "fiscalYearEnd": "03-31", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"book.setOptions","params":{"autoReadOnlyDays":30}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": { "autoReadOnlyDays": 30, "readOnlyThreshold": "2024-06-01", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":6,"method":"book.options","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 6, "result": { "autoReadOnlyDays": 30, "useTradingAccounts": false, "…": "…" } } ``` ## Related - [config.get](method/config.get) - [config.set](method/config.set) - [config.schema](method/config.schema) - [book.options](method/book.options) - [book.setOptions](method/book.setOptions) - [period.get](method/period.get) - [period.set](method/period.set) - [period.dates](method/period.dates) - [invalid-params](error/invalid-params) - [The Configuration](concept/configuration) - [Closing the books and the accounting period](concept/closing-the-books-and-accounting-period) - [Preferences and book options](gnucash/preferences-and-book-options) --- *red-ale Manual, `guide/configure-red-ale`. Adapted from GnuCash's documentation, `guide/ch_configuring.docbook#chapter_configuring`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Create a budget Plan income and spending per account and period, fill the amounts by hand or estimate them from past transactions, and compare plan with actuals in the Budget Report. A budget is a plan: how much you expect each account to receive or spend in each period. Comparing it with what actually happened tells you where the money went. A budget has a number of periods (for example 12 months) that start on a date, and an amount for any account in any period. ## Steps 1. **Create the budget** with [budget.create](method/budget.create): a `name`, `numPeriods` (1 to 60) and a `recurrence` saying how long a period is and when the first starts. The first budget becomes the default one. 2. **Set amounts** with [budget.setAmounts](method/budget.setAmounts): a list of `{account, period, amount}`. Periods count from 0. Amounts keep the account's natural sign: income is negative (a credit), expenses positive. One call is atomic, so a bad period leaves the budget unchanged. 3. **Or estimate them** with [budget.estimate](method/budget.estimate): it fills the periods of the accounts you name from what happened in the past, either period by period from a `startDate`, or as an average (`useAverage`). It overwrites those accounts' amounts, so use it on a budget you have not filled yet. 4. **Add notes** to cells with [budget.setNotes](method/budget.setNotes). 5. **Read it back** with [budget.get](method/budget.get), and list budgets with [budget.list](method/budget.list). 6. **Compare with actuals.** Run the Budget Report with [report.run](method/report.run): it shows, per account and period, the budget, the actual and the difference ([Budget Report](report/budget-report)). Other budget reports are listed by [report.list](method/report.list). Set the budget it uses in the `General/Budget` option. ## Example A three-month budget for rent and salary, with rent estimated from two past months. *Example: with a new, empty book open as `book.gnucash`, at 2024-04-15T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Rent","type":"EXPENSE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"account.create","params":{"name":"Salary","type":"INCOME","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"transaction.post","params":{"datePosted":"2024-01-05","description":"Rent","splits":[{"account":"Rent","value":"750.00"},{"account":"Checking","value":"-750.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"transaction.post","params":{"datePosted":"2024-02-05","description":"Rent","splits":[{"account":"Rent","value":"812.50"},{"account":"Checking","value":"-812.50"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":6,"method":"budget.create","params":{"name":"Spring","numPeriods":3,"recurrence":{"mult":1,"periodType":"month","start":"2024-04-01"}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 6, "result": { "name": "Spring", "numPeriods": 3, "isDefault": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":7,"method":"budget.setAmounts","params":{"budget":"00ed000000000000000000000000000a","amounts":[{"account":"Salary","period":0,"amount":"-3000.00"},{"account":"Salary","period":1,"amount":"-3000.00"},{"account":"Salary","period":2,"amount":"-3000.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 7, "result": { "set": 3, "unset": 0, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":8,"method":"budget.estimate","params":{"budget":"00ed000000000000000000000000000a","accounts":["Rent"],"startDate":"2024-01-01","significantDigits":2}} ``` Response: ```json { "jsonrpc": "2.0", "id": 8, "result": { "amounts": [ { "accountName": "Rent", "period": 0, "amount": { "num": "750", "denom": "1" }, "…": "…" }, { "period": 1, "amount": { "num": "813", "denom": "1" }, "…": "…" }, { "period": 2, "amount": { "num": "0", "denom": "1" }, "…": "…" } ], "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":9,"method":"report.run","params":{"report":"Budget Report"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 9, "result": { "title": "…", "sections": "…", "…": "…" } } ``` ## Related - [budget.create](method/budget.create) - [budget.setAmounts](method/budget.setAmounts) - [budget.setNotes](method/budget.setNotes) - [budget.estimate](method/budget.estimate) - [budget.get](method/budget.get) - [budget.list](method/budget.list) - [report.run](method/report.run) - [Budget Report](report/budget-report) - [Budgets](concept/budgets) --- *red-ale Manual, `guide/create-a-budget`. Adapted from GnuCash's documentation, `guide/ch_budgets.docbook#chapter_budgets`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Create, open and save a book Make a new book as XML or SQLite, open an existing one (read-only if you only want to look), save it with a backup, and close it so its lock is released. A book is the file that holds all your accounts and transactions. red-ale keeps one book open at a time. You create it or open it, change it in memory, save it, and close it. Opening takes the book's lock so that GnuCash and red-ale never write the same file at once; closing releases it. ## Steps 1. **Create a book** with [book.create](method/book.create). The default is a gzip-compressed XML book, which is what GnuCash writes. Pass `compressed: false` for plain XML, or `format: "sqlite"` (or a `sqlite3://` path) for an SQLite book. The path must not exist yet: an existing file is refused with [file-exists](error/file-exists). 2. **Look at it** with [book.info](method/book.info): the format, whether it is read-only and why, whether there are unsaved changes (`dirty`), and counts of accounts, transactions and prices. 3. **Change it** with the methods in the other guides. Nothing reaches the file yet; `dirty` becomes `true`. 4. **Save it** with [book.save](method/book.save). Before overwriting, red-ale copies the previous file to `..gnucash` and returns that path as `backup`. A brand-new book has no previous file, so it has no backup. 5. **Close it** with [book.close](method/book.close). With unsaved changes it refuses ([unsaved-changes](error/unsaved-changes)); say `save: true` or `discard: true`. 6. **Open it again** with [book.open](method/book.open). To look without any risk, pass `readOnly: true`: the lock is not taken and nothing can be changed. A book can also open read-only because it uses a GnuCash feature that red-ale does not implement; `readOnlyReasons` says why. From the command line, `red-ale exec --book book.gnucash ''` does steps 6, 3, 4 and 5 for one call, and `--create` makes the book first. ## Example Create a plain XML book, add an account, save, close and open it again. *Example: with no book.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"book.create","params":{"path":"household.gnucash","compressed":false}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "path": "…", "guid": "…", "rootAccount": "…", "readOnly": false, "format": "xml", "compressed": false, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"book.info","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "dirty": true, "readOnly": false, "format": "xml", "counts": "…", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"book.save","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"book.close","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": { "saved": false, "discarded": false } } ``` Request: ```json {"jsonrpc":"2.0","id":6,"method":"book.open","params":{"path":"household.gnucash","readOnly":true}} ``` Response: ```json { "jsonrpc": "2.0", "id": 6, "result": { "readOnly": true, "readOnlyReasons": [ { "code": "requested", "message": "opened read-only on request" } ], "…": "…" } } ``` ## Related - [book.create](method/book.create) - [book.open](method/book.open) - [book.info](method/book.info) - [book.save](method/book.save) - [book.close](method/book.close) - [unsaved-changes](error/unsaved-changes) - [file-exists](error/file-exists) - [Books and files](concept/books-and-files) - [Read-only books](concept/read-only-books) --- *red-ale Manual, `guide/create-open-and-save-a-book`. Adapted from GnuCash's documentation, `guide/ch_basics.docbook#basics-files1`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Credit cards Record charges, payments, refunds and interest on a credit card as a liability account, and know what the sign of its balance means. A credit card is money you owe, so it belongs in a liability account of type `CREDIT`, not in your assets. Every charge makes the debt larger; every payment makes it smaller. Keeping the card as an account of its own lets you see what you owe at any moment and reconcile it against each monthly statement. ## Signs A `CREDIT` account has a credit balance when you owe money, which is a negative number in the book's raw sign. A charge is a credit to the card (`-`) and a debit to the expense (`+`). A payment is the reverse: a debit to the card (`+`) and a credit to the bank (`-`). So a balance of `-185.00` means you owe 185.00. ## Steps 1. **Create the card account** with [account.create](method/account.create), type `CREDIT`, in the card's currency. Create an expense account for the interest the card charges. 2. **Record each charge** with [transaction.post](method/transaction.post): the expense `+`, the card `-`. 3. **Record a refund** as the opposite of a charge: the card `+`, the expense `-`. 4. **Record interest and fees** from the statement: the interest expense `+`, the card `-`. 5. **Record a payment**: the card `+`, the bank account `-`. 6. **Check what you owe** with [account.balance](method/account.balance). 7. **Reconcile** against the statement as in [Reconcile an account](guide/reconcile-an-account), with the statement's ending balance given in the card's raw sign (negative for money owed). ## Example *Example: with a new, empty book open as `book.gnucash`, at 2024-07-31T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Visa","type":"CREDIT","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"account.create","params":{"name":"Groceries","type":"EXPENSE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"account.create","params":{"name":"Card interest","type":"EXPENSE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"transaction.post","params":{"datePosted":"2024-07-03","description":"Supermarket","splits":[{"account":"Groceries","value":"120.00"},{"account":"Visa","value":"-120.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": { "balanced": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":6,"method":"transaction.post","params":{"datePosted":"2024-07-10","description":"Supermarket","splits":[{"account":"Groceries","value":"80.00"},{"account":"Visa","value":"-80.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 6, "result": { "balanced": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":7,"method":"transaction.post","params":{"datePosted":"2024-07-12","description":"Returned goods","splits":[{"account":"Visa","value":"30.00"},{"account":"Groceries","value":"-30.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 7, "result": { "balanced": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":8,"method":"transaction.post","params":{"datePosted":"2024-07-20","description":"Interest","splits":[{"account":"Card interest","value":"15.00"},{"account":"Visa","value":"-15.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 8, "result": { "balanced": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":9,"method":"account.balance","params":{"account":"Visa"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 9, "result": { "balances": { "commodity": "CURRENCY::USD", "balance": { "num": "-18500", "denom": "100" }, "…": "…" }, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":10,"method":"transaction.post","params":{"datePosted":"2024-07-25","description":"Card payment","splits":[{"account":"Visa","value":"100.00"},{"account":"Checking","value":"-100.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 10, "result": { "balanced": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":11,"method":"account.balance","params":{"account":"Visa"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 11, "result": { "balances": { "balance": { "num": "-8500", "denom": "100" }, "…": "…" }, "…": "…" } } ``` ## Related - [account.create](method/account.create) - [transaction.post](method/transaction.post) - [account.balance](method/account.balance) - [reconcile.start](method/reconcile.start) - [reconcile.finish](method/reconcile.finish) - [Account types](concept/account-types) --- *red-ale Manual, `guide/credit-cards`. Adapted from GnuCash's documentation, `guide/ch_cc.docbook#chapter_cc`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Depreciate an asset Spread the cost of equipment over its useful life with a monthly scheduled transaction that moves an equal amount into a depreciation expense. Equipment loses value as it is used. Rather than count the whole price as an expense the day you buy it, accountants spread it over the years it will last. This is *depreciation*. The simplest way is the straight line: if a 1,200.00 machine will last 12 months, 100.00 a month is charged as an expense. The books keep the machine at what you paid, in one account, and the total depreciation so far in a second asset account ("accumulated depreciation"). Together they give the machine's current worth. Each month's charge goes to a depreciation expense account, which reduces your profit. ## Steps 1. **Create the accounts** ([Set up accounts](guide/set-up-accounts)): `Equipment` and `Accumulated depreciation` (both `ASSET`), `Depreciation` (`EXPENSE`) and the bank account you paid from. 2. **Record the purchase**: Equipment `+`, bank `-`, for the price. 3. **Schedule the charge** with [scheduledTransaction.create](method/scheduledTransaction.create): a monthly `schedule` from the first date, and a template transaction with two splits, Depreciation as a `debitFormula` of `100` and Accumulated depreciation as a `creditFormula` of `100`. Add `end` to stop after 12 occurrences. 4. **Check the dates** with [scheduledTransaction.occurrences](method/scheduledTransaction.occurrences), which lists future occurrences of a schedule without creating anything. 5. **Create what is due** each time you open the book: [scheduledTransaction.sinceLastRun](method/scheduledTransaction.sinceLastRun) proposes every missed occurrence and changes nothing; [scheduledTransaction.apply](method/scheduledTransaction.apply) with the proposal's `id` creates the transactions. See [Schedule a transaction](guide/schedule-a-transaction). 6. **Check** the expense with [account.balance](method/account.balance). A declining-balance method changes the formula each period, or is entered by hand with [transaction.post](method/transaction.post) from your own calculation. ## Example Buy the machine, schedule the charge, see that three months are due on 15 October, and create them. *Example: with a new, empty book open as `book.gnucash`, at 2024-10-15T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Equipment","type":"ASSET","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"account.create","params":{"name":"Accumulated depreciation","type":"ASSET","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"account.create","params":{"name":"Depreciation","type":"EXPENSE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"transaction.post","params":{"datePosted":"2024-08-01","description":"Buy machine","splits":[{"account":"Equipment","value":"1200.00"},{"account":"Checking","value":"-1200.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": { "balanced": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":6,"method":"scheduledTransaction.create","params":{"name":"Depreciate machine","startDate":"2024-08-01","schedule":[{"mult":1,"periodType":"month"}],"end":{"occurrences":12},"templateTransactions":[{"description":"Depreciation","splits":[{"account":"Depreciation","debitFormula":"100"},{"account":"Accumulated depreciation","creditFormula":"100"}]}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 6, "result": { "name": "Depreciate machine", "enabled": true, "startDate": "2024-08-01", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":7,"method":"scheduledTransaction.occurrences","params":{"schedule":[{"mult":1,"periodType":"month"}],"startDate":"2024-08-01","count":3}} ``` Response: ```json { "jsonrpc": "2.0", "id": 7, "result": { "occurrences": [ { "date": "2024-08-01", "…": "…" }, { "date": "2024-09-01", "…": "…" }, { "date": "2024-10-01", "…": "…" } ] } } ``` Request: ```json {"jsonrpc":"2.0","id":8,"method":"scheduledTransaction.sinceLastRun","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 8, "result": { "id": "slr-1", "summary": { "toCreate": 3, "…": "…" }, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":9,"method":"scheduledTransaction.apply","params":{"proposal":"slr-1"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 9, "result": { "created": [ { "index": 0, "date": "2024-08-01", "transactions": [ "…" ], "…": "…" }, { "index": 1, "date": "2024-09-01", "transactions": [ "…" ], "…": "…" }, { "index": 2, "date": "2024-10-01", "transactions": [ "…" ], "…": "…" } ], "ignored": [], "postponed": [], "reminders": [], "schedules": [ "…" ], "imbalanceSplits": [], "warnings": [] } } ``` The Depreciation account then has a balance of 300.00 and Accumulated depreciation of -300.00, and the machine is worth 1,200.00 less 300.00. ## Related - [scheduledTransaction.create](method/scheduledTransaction.create) - [scheduledTransaction.occurrences](method/scheduledTransaction.occurrences) - [scheduledTransaction.sinceLastRun](method/scheduledTransaction.sinceLastRun) - [scheduledTransaction.apply](method/scheduledTransaction.apply) - [transaction.post](method/transaction.post) - [account.balance](method/account.balance) - [Other assets and depreciation](concept/other-assets-and-depreciation) --- *red-ale Manual, `guide/depreciate-an-asset`. Adapted from GnuCash's documentation, `guide/ch_dep.docbook#chapter_dep`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Edit, void and reverse transactions Correct a transaction in place, void it while keeping a record, undo it with a reversing transaction, or delete it; attach a document link to a receipt. Mistakes happen, and a bookkeeper has four tools for them, from lightest to heaviest. Which to use depends on whether you want the history to show the mistake. | You want to | Use | |-------------|-----| | Fix a typo or a wrong date or account, as if it had never been wrong | [transaction.update](method/transaction.update) | | Keep the transaction in the book but count it as nothing | [transaction.void](method/transaction.void) | | Cancel its effect with an equal and opposite transaction on a later date | [transaction.reverse](method/transaction.reverse) | | Remove it altogether | [transaction.delete](method/transaction.delete) | ## Steps 1. **Find the transaction** and its GUID with [transaction.list](method/transaction.list) or [transaction.find](method/transaction.find) (see [Find transactions](guide/find-transactions)). 2. **Edit it** with [transaction.update](method/transaction.update): description, notes, date, num, currency and splits. The result must still balance, or the change is refused. 3. **Void it** with [transaction.void](method/transaction.void), giving a `reason`. The splits' values are zeroed and the old values kept in slots, so the book remembers what was voided and why. [transaction.unvoid](method/transaction.unvoid) restores it. A voided transaction is read-only until then. 4. **Reverse it** with [transaction.reverse](method/transaction.reverse): it posts a new transaction on the `date` you give, with every value negated. Use it when the original belongs to a closed period and must stay as it was. A transaction can be reversed once; a second call is refused as a conflict. 5. **Delete it** with [transaction.delete](method/transaction.delete) when it should never have existed. Deleting cannot be undone, short of restoring a backup. 6. **Link a document.** To keep a receipt with its transaction, set the book's path head once with [docLink.setPathHead](method/docLink.setPathHead) (the folder your documents live in), then put a `docLink` on the transaction with [transaction.update](method/transaction.update). A relative link is resolved against the path head; [docLink.transactions](method/docLink.transactions) lists the links and the full paths they resolve to. A transaction older than the book's auto read-only threshold, may be refused; the error says why. ## Example *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`, at 2024-07-01T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"transaction.update","params":{"guid":"c0000000000000000000000000000005","description":"Fuel","notes":"corrected"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "description": "Fuel", "notes": "corrected", "balanced": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"transaction.void","params":{"guid":"c0000000000000000000000000000000","reason":"Duplicate"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "void": true, "voidReason": "Duplicate", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"transaction.unvoid","params":{"guid":"c0000000000000000000000000000000"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "void": false, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"transaction.reverse","params":{"guid":"c0000000000000000000000000000003","date":"2024-07-01"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "datePosted": "2024-07-01", "splits": [ { "accountName": "Root:Asset:Bank", "value": { "num": "1500", "denom": "100" }, "…": "…" }, { "accountName": "Root:Expenses", "value": { "num": "-1500", "denom": "100" }, "…": "…" } ], "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"docLink.setPathHead","params":{"pathHead":"/home/me/receipts"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":6,"method":"transaction.update","params":{"guid":"c0000000000000000000000000000005","docLink":"2024/fuel.pdf"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 6, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":7,"method":"docLink.transactions","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 7, "result": { "links": [ { "transaction": "c0000000000000000000000000000005", "docLink": "2024/fuel.pdf", "relative": true, "…": "…" } ], "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":8,"method":"transaction.delete","params":{"guid":"c0000000000000000000000000000006"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 8, "result": {} } ``` ## Related - [transaction.update](method/transaction.update) - [transaction.delete](method/transaction.delete) - [transaction.void](method/transaction.void) - [transaction.unvoid](method/transaction.unvoid) - [transaction.reverse](method/transaction.reverse) - [transaction.get](method/transaction.get) - [docLink.setPathHead](method/docLink.setPathHead) - [docLink.transactions](method/docLink.transactions) - [docLink.documents](method/docLink.documents) --- *red-ale Manual, `guide/edit-void-and-reverse-transactions`. Adapted from GnuCash's documentation, `manual/ch_Transactions.docbook#trans-assoc`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Employees, vouchers and payroll Add an employee, record expenses they paid as an expense voucher and reimburse them, and record payroll with ordinary accounts and transactions. red-ale has two things for people who work for you. The first is the **employee** record, with its **expense vouchers**: what the employee spent for the business and you owe back. The second is payroll, which GnuCash does not calculate; you record it yourself with accounts and ordinary transactions. ## Expense vouchers An employee spends 40.00 on a taxi. The voucher records it as an expense and as money you owe the employee, until you pay it back. 1. **Add the employee** with [employee.create](method/employee.create): `name`, `currency`, optionally an hourly `rate`, and a `creditCardAccount` (an account of type `CREDIT`) if the employee uses a company card. 2. **Create the voucher** with [invoice.create](method/invoice.create), giving the employee as `owner`. It is an expense voucher. 3. **Add the lines** with [invoice.addEntry](method/invoice.addEntry): the expense `account`, `quantity`, `price`, and for each line `payment`: `cash` if the employee paid, or `card` if the company card did. A line to a client can be marked `billable`. 4. **Post it** with [invoice.post](method/invoice.post) to your Payable account. 5. **Reimburse the employee** with [payment.process](method/payment.process), with the owner type `employee`. ## Payroll Payroll is a set of accounts and a routine. A common layout: - expense accounts for gross wages and employer taxes; - liability accounts for tax withheld and for amounts owed to the tax office or a pension fund; - the bank account that pays the net wage. Each pay day, record one transaction with [transaction.post](method/transaction.post) (see [Split transactions](guide/split-transactions)): wages expense `+` for the gross pay; the liabilities `-` for each withholding; the bank `-` for the net pay. When you pay the tax office, post a second transaction: the liability `+`, the bank `-`. For a routine pay day, make the first transaction a [scheduled transaction](guide/schedule-a-transaction). ## Example Add an employee, and record and post a 40.00 taxi voucher for the existing employee Jane Doe. *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`, at 2024-03-10T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"employee.create","params":{"name":"John Roe","currency":"EUR","rate":"30.00"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "name": "John Roe", "rate": { "num": "3000", "denom": "100" }, "active": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"employee.list","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "employees": [ { "name": "John Roe", "…": "…" }, { "name": "Jane Doe", "…": "…" } ] } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"invoice.create","params":{"owner":"7f0d801fdccd48198abec7b197e55581"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "type": "expenseVoucher", "posted": false, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"invoice.addEntry","params":{"invoice":"00ed0000000000000000000000000002","description":"Taxi","quantity":"1","price":"40.00","account":"Expenses","payment":"cash"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "description": "Taxi", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"invoice.post","params":{"invoice":"00ed0000000000000000000000000002","account":"Liabilities:Payable","postDate":"2024-03-10"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": { "transaction": "…", "lot": "…", "due": "…" } } ``` ## Related - [employee.create](method/employee.create) - [employee.list](method/employee.list) - [invoice.create](method/invoice.create) - [invoice.addEntry](method/invoice.addEntry) - [invoice.post](method/invoice.post) - [payment.process](method/payment.process) - [transaction.post](method/transaction.post) - [Business documents](concept/business-documents) --- *red-ale Manual, `guide/employees-and-payroll`. Adapted from GnuCash's documentation, `guide/ch_bus_features.docbook#bus_payroll`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Export data Get transactions out as CSV, in GnuCash's simple or complex layout, and the account tree as CSV or as a file of accounts and commodities. To use your data in a spreadsheet, send it to an accountant, or load it into another book, export it. red-ale has three exports. None changes the book. | Export | Gives | Format | |--------|-------|--------| | [export.csvTransactions](method/export.csvTransactions) | Transactions of chosen accounts and dates | CSV text in the result | | [export.csvTree](method/export.csvTree) | The account tree: type, name, code, commodity, flags | CSV text in the result | | [export.accounts](method/export.accounts) | The accounts and their commodities, to be imported as a new book's chart | A file of a book with no transactions | ## Steps 1. **Transactions.** Call [export.csvTransactions](method/export.csvTransactions) with the `accounts` to export (a transaction appears under the first of them it has a split in), optionally `from` and `to`, and a `layout`: `simple`, one line per split with the other account in the line, or `complex` (the default), GnuCash's full layout with one line per split and its memo, action and price. `separator` and `quotes` shape the CSV; `locale` decides how dates and numbers are written. The CSV is in the result as `csv`. From the command line, `--output transactions.csv` writes it to a file. 2. **The account tree.** [export.csvTree](method/export.csvTree) gives one row per account in the layout that [Import transactions](guide/import-transactions) and GnuCash's account import read. 3. **A chart of accounts.** [export.accounts](method/export.accounts) writes the accounts and commodities, without the transactions, to a new book at `path`. It refuses a path that exists. Use it to start a new year's book with the same chart. 4. **A report's figures.** Reports with a CSV export give theirs through [report.exportCsv](method/report.exportCsv) (see [Run and export a report](guide/run-and-export-a-report)). ## Example *Example: with a new, empty book open as `book.gnucash`, at 2024-07-01T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Food","type":"EXPENSE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"transaction.post","params":{"datePosted":"2024-06-03","description":"Coffee","splits":[{"account":"Food","value":"3.50"},{"account":"Checking","value":"-3.50"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"export.csvTransactions","params":{"accounts":["Checking"],"layout":"simple"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "csv": "Date,Account Name,Number,Description,Full Category Path,Reconcile,Amount With Sym,Amount Num.,Value With Sym,Value Num.,Rate/Price\r\n06/03/24,Checking,,Coffee,Food,n,-$3.50,-3.50,-$3.50,-3.50,1.00\r\n", "transactions": 1, "lines": 1 } } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"export.csvTree","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": { "csv": "Type,Full Account Name,Account Name,Account Code,Description,Account Color,Notes,Symbol,Namespace,Hidden,Tax Info,Placeholder\r\nEXPENSE,Food,Food,,,,,USD,CURRENCY,F,F,F\r\nBANK,Checking,Checking,,,,,USD,CURRENCY,F,F,F\r\n", "rows": 2 } } ``` Request: ```json {"jsonrpc":"2.0","id":6,"method":"export.accounts","params":{"path":"chart"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 6, "result": { "path": "…", "accounts": 3, "commodities": "…" } } ``` ## Related - [export.csvTransactions](method/export.csvTransactions) - [export.csvTree](method/export.csvTree) - [export.accounts](method/export.accounts) - [report.exportCsv](method/report.exportCsv) --- *red-ale Manual, `guide/export-data`. Adapted from GnuCash's documentation, `manual/ch_Transactions.docbook#trans-export`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Find transactions Search for transactions by description, date, amount or account with transaction.find; list an account's register with transaction.list; find business documents with invoice.list. There are two ways to look at transactions. [transaction.list](method/transaction.list) is a register: all transactions, or those of one account and a date range, in GnuCash's order. [transaction.find](method/transaction.find) is GnuCash's Find Transaction dialog: it matches splits against criteria you combine. ## Steps 1. **To read an account**, call [transaction.list](method/transaction.list) with `account` and, if you like, `from` and `to`. With no parameters it lists the whole book, which is GnuCash's General Journal. 2. **To search**, call [transaction.find](method/transaction.find) with a `query`. A query is a criterion or a group of criteria: `{"all": [...]}` means every one must match, `{"any": [...]}` means at least one, `{"not": ...}` negates. Criteria include `description`, `notes`, `memo`, `num`, `datePosted`, `value`, `amount`, `reconcile`, `void` and `accounts`; the reference page lists them with their operators. Add `limit` to keep only the last matches. 3. **Read the matches.** Each is a split (`split`) with its `transaction` and `account`. Several matches may belong to one transaction; pass its GUID to [transaction.get](method/transaction.get) for the whole thing. 4. **Business documents** are found with [invoice.list](method/invoice.list), filtered by `type` (`invoice`, `bill`, `expenseVoucher`, `creditNote`), `posted` and owner. See [Invoices and bills](guide/invoices-and-bills). ## Example *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"transaction.list","params":{"account":"Root:Asset:Wallet","from":"1971-01-01","to":"1971-12-31"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "transactions": [ { "guid": "c0000000000000000000000000000007", "description": "$100bank -> $80expenses + $20wallet", "…": "…" } ] } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"transaction.find","params":{"query":{"all":[{"description":{"text":"$22 expense"}},{"datePosted":{"op":"before","date":"1978-03-01"}}]}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "matches": [ { "transaction": "c000000000000000000000000000000d", "split": "…", "account": "…" }, "…" ] } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"invoice.list","params":{"posted":false}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "invoices": [] } } ``` ## Related - [transaction.find](method/transaction.find) - [transaction.list](method/transaction.list) - [transaction.get](method/transaction.get) - [invoice.list](method/invoice.list) - [Tools, scheduled transactions and budgets](gnucash/tools-menu) --- *red-ale Manual, `guide/find-transactions`. Adapted from GnuCash's documentation, `manual/ch_Transactions.docbook#general-journal`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Import business data Load customers or vendors, and invoices or bills with their lines, from CSV files in GnuCash's layouts, with a preview before anything changes. If your customers and invoices live in a spreadsheet or another program, you can bring them in with the business imports. They work as other imports do: **preview** shows what would be created or updated, and **apply** does it. The files use GnuCash's fixed column layouts, because red-ale reads the same files GnuCash does. ## Customers and vendors 1. Make a CSV with one owner on each line and 19 fields, in this order: `id`, `company`, `name`, `addr1` to `addr4`, `phone`, `fax`, `email`, `notes`, then a shipping address (`shipname`, `shipaddr1` to `shipaddr4`, `shipphone`, `shipfax`, `shipemail`). An empty `id` takes the next number from the counter. An empty `company` takes the `name`. There is no header row, and a header is imported as a row. 2. Call [import.preview](method/import.preview) with `format: "csvOwners"`, the file in `files`, `ownerKind` (`customer` or `vendor`) and the `separator` (`comma`, `semicolon`, ...). The proposal's `owners` say, per row, `add` or `update` (an owner with that `id` exists), and which fields would change. 3. Apply with [import.apply](method/import.apply). A row can be skipped with `changes`. There is no employee import; GnuCash has none. ## Invoices and bills 1. The customer or vendor must exist already (its `id` is in the file). 2. Make a CSV with one line per entry and 22 fields: `id`, `date_opened`, `owner_id`, `billing_id`, `notes`, `date`, `desc`, `action`, `account`, `quantity`, `price`, `disc_type`, `disc_how`, `discount`, `taxable`, `taxincluded`, `tax_table`, `date_posted`, `due_date`, `account_posted`, `memo_posted`, `accu_splits`. Lines with the same `id` are the entries of one document. Fill `date_posted` and `account_posted` to post it as well. 3. Call [import.preview](method/import.preview) with `format: "csvDocuments"`, `documentKind` (`invoice` or `bill`, the default) and `dateFormat` (`iso` for `2024-03-01`). Each document in the proposal has its entries, its totals as they would be, and, if it would be posted, whether it `willPost` and why not if it will not. A row with an error drops its whole document, and the error is GnuCash's own message. 4. Apply with [import.apply](method/import.apply). `changes` can only set a document's `action` to `skip`. The proposal `id` counts up from `imp-1` in each server process, as in [Import transactions](guide/import-transactions). ## Example Import one customer, then preview and import one invoice for them. *Example: with a new, empty book open as `book.gnucash`, at 2024-03-10T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"import.preview","params":{"format":"csvOwners","files":[{"name":"customers.csv","text":"C1,Acme Ltd,Wile E,1 Main St,,,,555-1234,,billing@acme.example,,,,,,,,,\n"}],"separator":"comma"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "id": "imp-1", "format": "csvOwners", "owners": [ { "index": 0, "kind": "customer", "id": "C1", "action": "add", "…": "…" } ], "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"import.apply","params":{"proposal":"imp-1"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"account.create","params":{"name":"Income","type":"INCOME","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"import.preview","params":{"format":"csvDocuments","files":[{"name":"invoices.csv","text":"B1,2024-03-01,C1,PO-1,,2024-03-01,Design,,Income,2,50,,,,,,,,,,,\n"}],"documentKind":"invoice","dateFormat":"iso","separator":"comma"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "id": "imp-2", "format": "csvDocuments", "documents": [ { "id": "B1", "type": "invoice", "action": "add", "…": "…" } ], "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"import.apply","params":{"proposal":"imp-2"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": "…" } ``` ## Related - [import.preview](method/import.preview) - [import.apply](method/import.apply) - [import.discard](method/import.discard) - [customer.create](method/customer.create) - [invoice.list](method/invoice.list) --- *red-ale Manual, `guide/import-business-data`. Adapted from GnuCash's documentation, `guide/ch_import_business_data.docbook#ch_import_bus_data`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Import transactions Bring bank transactions in from a CSV or QIF file: preview what would happen, choose the accounts, apply the proposal, and let red-ale learn which account a description belongs to. Most banks let you download your transactions as a file. Importing saves typing them, and red-ale checks each against what is already in the book so that a transaction is not entered twice. Nothing changes until you have seen what would happen: import is always two steps, **preview** and **apply**. ## Steps 1. **Create the account** the file belongs to, a bank or credit card account in the file's currency ([Set up accounts](guide/set-up-accounts)). 2. **Preview** with [import.preview](method/import.preview). `format` is `csvTransactions` or `qif`. The file's content goes in `files` as `text` (or `base64`); the server never reads a path you name. From the command line, `red-ale exec --file bank.csv import.preview '{...}'` reads the file on your side and adds it to `files`. - For CSV, give a `layout`: the separator, how many lines to skip, the date and number formats, the `baseAccount` and what each column is (`Date`, `Description`, `Amount`, `Account`, and so on). - For QIF, the dates and the accounts the file names are read for you. 3. **Read the proposal.** Its `id` names it. `transactions` lists what would be done to each row: `add` it, `clear` an existing transaction it matches, `update` one, or `skip`. A row that matches an existing transaction lists the `matches`. `errors` are rows that cannot be imported and are left out. A transaction with no account to balance it is marked `imbalance`. 4. **Apply** with [import.apply](method/import.apply) and the proposal `id`. In `changes` give the `account` that balances a row, or change a row's action. `skipErrors: true` applies the good rows when others have errors. Applying changes the book in one step: everything or nothing. 5. **Or discard** the proposal with [import.discard](method/import.discard). Proposals are kept in memory only, so one made before the book was opened is gone. 6. **Learn.** When you give a transfer account for a description, red-ale remembers it, so that the next import suggests it. [importMap.list](method/importMap.list) shows what it has learned and [importMap.delete](method/importMap.delete) forgets an entry. 7. **Save** with [book.save](method/book.save). The proposal's `id` counts up from `imp-1` in each server process. ## Example A bank's CSV with two rows. The preview adds both and notes that neither is balanced yet. Applying it names Food as the account that balances the first row; the second is balanced against `Imbalance-USD`. *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Food","type":"EXPENSE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"import.preview","params":{"format":"csvTransactions","files":[{"name":"bank.csv","text":"Date,Description,Amount\n2024-06-03,Coffee,-3.50\n2024-06-04,Lunch,-12.00\n"}],"layout":{"format":"csv","separators":",","skipStartLines":1,"dateFormat":"y-m-d","currencyFormat":"period","encoding":"utf-8","baseAccount":"Checking","columns":["Date","Description","Amount"]}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "id": "imp-1", "format": "csvTransactions", "summary": { "add": 2, "imbalanced": 2, "errors": 0, "…": "…" }, "transactions": [ { "index": 0, "description": "Coffee", "datePosted": "2024-06-03", "action": "add", "…": "…" }, { "index": 1, "description": "Lunch", "action": "add", "…": "…" } ], "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"import.apply","params":{"proposal":"imp-1","changes":[{"index":0,"account":"Food"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "added": [ { "index": 0, "transaction": "…" }, { "index": 1, "transaction": "…" } ], "skipped": [], "imbalanceSplits": [ { "index": 1, "account": "…", "value": { "num": "1200", "denom": "100" }, "…": "…" } ], "learned": "…", "warnings": "…", "…": "…" } } ``` ## Related - [import.preview](method/import.preview) - [import.apply](method/import.apply) - [import.discard](method/import.discard) - [importMap.list](method/importMap.list) - [importMap.delete](method/importMap.delete) - [account.create](method/account.create) - [book.save](method/book.save) - [Importing and matching](concept/importing-and-matching) - [Import and export](gnucash/import-and-export) --- *red-ale Manual, `guide/import-transactions`. Adapted from GnuCash's documentation, `guide/ch_importing.docbook#chapter_importing`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Invoices and bills Add a customer or vendor, optionally a job, then create an invoice or bill, add its lines, post it to Receivable or Payable, and unpost or duplicate it. An **invoice** is what you send a customer to ask for payment; a **bill** is what a vendor sends you. Both are *documents*: a list of lines (entries) with prices, taxes and discounts, which you edit freely until you **post** it. Posting turns it into a transaction against your Accounts Receivable (invoice) or Accounts Payable (bill), and opens a lot that [payments](guide/process-payments) will close. Before this, set the book up as in [Set up the business features](guide/set-up-business). ## Steps 1. **Add the other party** with [customer.create](method/customer.create) or [vendor.create](method/vendor.create): a `name`, a `currency`, and optionally billing `terms`, a `taxTable` and a `discount`. Its ID comes from the counter unless you give one. 2. **Add a job** with [job.create](method/job.create) if the work is for a particular project; its `rate` becomes the default price of its lines. A job's documents belong to the job's owner. 3. **Create the document** with [invoice.create](method/invoice.create). The `owner` decides what it is: a customer makes an invoice, a vendor a bill, an employee an expense voucher, a job whatever its owner is. Give `billingId` (your customer's order number, or the vendor's invoice number). The number comes from the counter. 4. **Add lines** with [invoice.addEntry](method/invoice.addEntry): description, `quantity`, `price`, `account` (the income or expense account) and, on invoices, `discount` and tax. A line takes the owner's tax table and discount unless it says otherwise. 5. **Check the figures** with [invoice.totals](method/invoice.totals): subtotal, tax per tax account, and total. 6. **Post it** with [invoice.post](method/invoice.post): the Receivable or Payable `account` in the document's currency, and the `postDate`. The due date comes from the billing term unless you give `dueDate`. The result names the transaction and the lot. 7. **Posted by mistake?** [invoice.unpost](method/invoice.unpost) deletes the transaction and makes the document editable again, as long as no payment has been applied. 8. **Another one like it?** [invoice.duplicate](method/invoice.duplicate) copies a document's lines to a new, unposted one. 9. **Find documents** with [invoice.list](method/invoice.list) and read one with [invoice.get](method/invoice.get). ## Example An invoice and a bill, in a book that already has a customer, a vendor, tax tables and Receivable and Payable accounts. *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`, at 2024-03-10T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"customer.create","params":{"name":"Globex","currency":"EUR","terms":"Net30"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "id": "000002", "name": "Globex", "currency": "CURRENCY::EUR", "active": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"invoice.create","params":{"owner":"5b22073fa4e34411b07c14a77147ce6b","billingId":"PO-5"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "id": "000003", "type": "invoice", "posted": false, "billingId": "PO-5", "entryCount": 0, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"invoice.addEntry","params":{"invoice":"00ed0000000000000000000000000002","description":"Design","quantity":"4","price":"90.00","account":"Income"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "description": "Design", "quantity": { "num": "4", "denom": "1" }, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"invoice.totals","params":{"invoice":"00ed0000000000000000000000000002"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"invoice.post","params":{"invoice":"00ed0000000000000000000000000002","account":"Assets:Receivable","postDate":"2024-03-10"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": { "transaction": "…", "lot": "…", "due": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":6,"method":"invoice.create","params":{"owner":"9697710198334d558a9bfde219bb1e41","billingId":"INV-8841"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 6, "result": { "id": "000002", "type": "bill", "posted": false, "…": "…" } } ``` ## Related - [customer.create](method/customer.create) - [vendor.create](method/vendor.create) - [job.create](method/job.create) - [invoice.create](method/invoice.create) - [invoice.addEntry](method/invoice.addEntry) - [invoice.post](method/invoice.post) - [invoice.unpost](method/invoice.unpost) - [invoice.duplicate](method/invoice.duplicate) - [invoice.get](method/invoice.get) - [invoice.totals](method/invoice.totals) - [invoice.list](method/invoice.list) - [Account types](concept/account-types) - [Business documents](concept/business-documents) --- *red-ale Manual, `guide/invoices-and-bills`. Adapted from GnuCash's documentation, `guide/ch_expenses.docbook#expenses-other`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Migrate from GnuCash Open a copy of your GnuCash file in red-ale, check that it opens as you expect, and bring over data from other tools with CSV and QIF imports. red-ale reads and writes GnuCash's own files, so there is nothing to convert. Your existing `.gnucash` file, XML (plain or compressed) or SQLite, is the book. What changes is how you work with it: through JSON-RPC, MCP or the command line instead of windows. ## Steps 1. **Work on a copy.** Close GnuCash, copy the file somewhere safe, and open the copy. Your original stays exactly as it was, and red-ale takes a backup before every save anyway ([Back up and recover](guide/back-up-and-recover)). 2. **Open it** with [book.open](method/book.open). red-ale will not open a book that GnuCash or another red-ale has locked for writing. Try `readOnly: true` first if you only want to look. 3. **Check the result.** `readOnlyReasons` says why a book opened read-only, for example because it uses a GnuCash feature red-ale does not implement. Such a book is never written, so you cannot damage it. [book.info](method/book.info) shows the format and the counts of accounts, transactions and prices. 4. **Look around.** [account.tree](method/account.tree) shows the chart, [transaction.list](method/transaction.list) a register, and the reports run as in GnuCash ([Run and export a report](guide/run-and-export-a-report)). For where GnuCash's menus have gone, search the manual with `help.search`. 5. **Carry settings over.** GnuCash's preferences are not read from its files. Set the equivalents with [config.set](method/config.set) ([Configure red-ale](guide/configure-red-ale)); book options are already in the book. Saved report configurations and style sheets from GnuCash's own files can be imported with [report.importConfigurations](method/report.importConfigurations) and [report.importStyleSheets](method/report.importStyleSheets). 6. **Save** with [book.save](method/book.save). GnuCash opens the result with nothing lost. 7. **Go back and forth.** The same file opens in both programs, one at a time. Close one before opening it in the other. ## Data from elsewhere - **Bank files:** [Import transactions](guide/import-transactions) reads CSV and QIF. - **Customers, vendors and invoices:** [Import business data](guide/import-business-data). - **OFX, AqBanking and MT940** are not supported. Convert such files to CSV or QIF first. - **A spreadsheet or another book's accounts:** [Export data](guide/export-data) produces CSV in GnuCash's layouts, and [export.accounts](method/export.accounts) starts a new book from your chart. - **XML to SQLite or back:** create a new book in the other format with [book.create](method/book.create), and move the data with CSV exports and imports or with GnuCash's Save As. red-ale saves a book in the format it was opened in. ## Example Open a GnuCash test book read-only and look at it. *Example: with a copy of the `gnucash/sample1` example book saved as `book.gnucash`, not open.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"book.open","params":{"path":"book.gnucash","readOnly":true}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "readOnly": true, "readOnlyReasons": [ { "code": "requested", "message": "opened read-only on request" } ], "format": "xml", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"book.info","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "readOnly": true, "dirty": false, "format": "xml", "counts": "…", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"account.tree","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` ## Related - [book.open](method/book.open) - [book.info](method/book.info) - [book.save](method/book.save) - [import.preview](method/import.preview) - [export.csvTransactions](method/export.csvTransactions) - [export.accounts](method/export.accounts) - [Import transactions](guide/import-transactions) - [Coming from GnuCash](concept/coming-from-gnucash) --- *red-ale Manual, `guide/migrate-from-gnucash`. Adapted from GnuCash's documentation, `guide/ch_basics.docbook#basics-migrate-settings`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Multiple currencies Keep an account in a foreign currency, buy that currency, spend it, and record the exchange rate, with each split's value in the transaction currency and its amount in the account's. If you hold money in a foreign currency, give it an account in that currency. The book then keeps two numbers for every split, and they are not the same thing: - the split's **value** is in the *transaction's currency*, the one the transaction as a whole is in; - the split's **amount** is in the *account's commodity*, which can be another currency. For a purchase of 100.00 EUR for 108.50 USD, the euro account's split has an amount of 100.00 (euros) and a value of 108.50 (dollars); the dollar account's split has both equal to 108.50. The values sum to zero, and the ratio of value to amount is the exchange rate. ## Steps 1. **Create the account** with [account.create](method/account.create), with `commodity` set to the currency's code (`EUR`). The currencies GnuCash knows are in [currency.list](method/currency.list); you do not create them. 2. **Say which currency the transaction is in.** [transaction.post](method/transaction.post) uses the first split's account commodity unless you set `currency`, so when the first split is in the foreign currency, pass `currency` explicitly. A split whose account is in another commodity than the transaction needs its `amount`. 3. **Buy the currency**: post the transaction in your home currency, with the euro split carrying both `value` and `amount`. For a simple move between your own accounts, [transaction.transfer](method/transaction.transfer) with a `rate` does the same, and records the rate. 4. **Record the rate** for reports with [price.add](method/price.add), so that balances can be shown in one currency. `transaction.post` records a price from a priced split when you pass `recordPrice: true`. 5. **Spend the currency**: a transaction in USD whose euro split has `value: -54.25` and `amount: -50.00` takes 50.00 EUR out of the euro account for a 54.25 USD expense. 6. **Check** with [account.balance](method/account.balance). A balance is in the account's own commodity; the [price.list](method/price.list) shows the rates the book has. If your book uses trading accounts, see [Use trading accounts](guide/use-trading-accounts). ## Example *Example: with a new, empty book open as `book.gnucash`, at 2024-07-15T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Euro Bank","type":"BANK","commodity":"EUR"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "commodity": "CURRENCY::EUR", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"account.create","params":{"name":"Travel","type":"EXPENSE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"transaction.post","params":{"datePosted":"2024-07-02","description":"Buy euros","currency":"USD","splits":[{"account":"Euro Bank","value":"108.50","amount":"100.00"},{"account":"Checking","value":"-108.50"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "currency": "CURRENCY::USD", "balanced": true, "splits": [ { "accountName": "Euro Bank", "value": { "num": "10850", "denom": "100" }, "amount": { "num": "10000", "denom": "100" }, "…": "…" }, { "accountName": "Checking", "…": "…" } ], "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"price.add","params":{"commodity":"EUR","currency":"USD","value":"1.0850","date":"2024-07-02"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": { "outcome": "added", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":6,"method":"transaction.post","params":{"datePosted":"2024-07-10","description":"Hotel in Lyon","currency":"USD","splits":[{"account":"Travel","value":"54.25"},{"account":"Euro Bank","value":"-54.25","amount":"-50.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 6, "result": { "balanced": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":7,"method":"account.balance","params":{"account":"Euro Bank"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 7, "result": { "balances": { "commodity": "CURRENCY::EUR", "balance": { "num": "5000", "denom": "100" }, "…": "…" }, "…": "…" } } ``` ## Related - [account.create](method/account.create) - [price.add](method/price.add) - [transaction.post](method/transaction.post) - [transaction.transfer](method/transaction.transfer) - [account.balance](method/account.balance) - [price.list](method/price.list) - [currency.list](method/currency.list) --- *red-ale Manual, `guide/multiple-currencies`. Adapted from GnuCash's documentation, `guide/ch_currency.docbook#currency_manual`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Print an invoice Put your company's details in the book, run the Printable Invoice report for a document, and export it as a single HTML page to print or send. red-ale has no print dialog. A document is printed by running the **Printable Invoice** report on it, which gives its figures exactly, and exporting that as one HTML page. Open the page in a browser to print it, or [turn it into a PDF](guide/report-to-pdf). The same report prints invoices, bills, credit notes and expense vouchers. ## Steps 1. **Set your company's details** once with [book.setOptions](method/book.setOptions): `companyName`, `companyAddress`, `companyContactPerson`, phone, fax, email, website, `companyId` and `taxNumber`. They fill the header of the printout. 2. **Find the document's GUID** with [invoice.list](method/invoice.list). The report is told which document to print by its GUID, not its number. 3. **Run the report** with [report.run](method/report.run), report `Printable Invoice`, and the option `{"General": {"Invoice Number": ""}}`. You get the report result: the entries, net price, tax, total, payments and amount due, as exact figures with their display forms. A document may be posted or not. 4. **Adjust the layout** if you like. [report.options](method/report.options) lists the options: which entry columns show (Display Columns), whether the due date, billing terms and payments print, a custom title, extra notes at the foot, and the CSS. 5. **Export it** with [report.export](method/report.export), with the same options. The result's `html` is a complete, self-contained page. From the command line, `red-ale exec --output invoice.html --book book.gnucash report.export '{...}'` writes it to a file instead of printing it. 6. **To print as GnuCash does,** read `defaultInvoiceReport` with [book.options](method/book.options). If the book names an invoice report that red-ale has, run that one; otherwise use the Printable Invoice, which is what GnuCash falls back to. The [Printable Invoice](report/printable-invoice) page has the details. ## Example *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`, at 2024-03-25T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"book.setOptions","params":{"companyName":"Acme Ltd","companyAddress":"1 Main St\nSpringfield","companyEmailAddress":"billing@acme.example"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "companyName": "Acme Ltd", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"report.run","params":{"report":"Printable Invoice","options":{"General":{"Invoice Number":"aa210b7131de44c48b8513cd27c00e95"}}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "report": { "name": "Printable Invoice", "…": "…" }, "sections": "…", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"report.export","params":{"report":"Printable Invoice","options":{"General":{"Invoice Number":"aa210b7131de44c48b8513cd27c00e95"}}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "title": "…", "html": "…" } } ``` ## Related - [Printable Invoice](report/printable-invoice) - [report.run](method/report.run) - [report.export](method/report.export) - [report.options](method/report.options) - [book.setOptions](method/book.setOptions) - [book.options](method/book.options) - [invoice.list](method/invoice.list) - [invoice.get](method/invoice.get) - [Reports menu and the report window](gnucash/reports-menu) - [Report scripts](concept/report-scripts) --- *red-ale Manual, `guide/print-an-invoice`. Adapted from GnuCash's documentation, `guide/ch_reports.docbook#rpt_grp_business`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Process payments Record a customer's payment (full, part or over-payment) against open invoices, pay a vendor's bills, turn an existing deposit into a payment, and write off a bad debt. Posting an invoice records that a customer owes you money, in a lot on your Receivable account. A **payment** is the transaction that settles it: money arrives in the bank and the Receivable lot shrinks. For bills it is the other way round: money leaves the bank, and the Payable lot shrinks. A payment can cover one document, part of one, several, or more than is owed. What is left over from an over-payment stays with the customer as a pre-payment, which a later document can use. ## Steps 1. **See what is open** for the party with [payment.openItems](method/payment.openItems): the owner and the Receivable or Payable account. It lists each open document, with its balance, and any pre-payments. 2. **Pay one document in full or in part** with [invoice.pay](method/invoice.pay): the document, the `transferAccount` (your bank account), the `amount` and the `date`. A smaller amount leaves the rest open. 3. **Pay several at once** with [payment.process](method/payment.process): the `owner` (`{"type": "customer", "id": ...}`), the `account`, the `transferAccount`, the `amount`, the `date`, and optionally `applyTo`, the documents to apply it to in order. Without `applyTo` it pays the oldest first only if you set `autoPay`; otherwise the amount waits as a pre-payment. The result's `paymentLot` is set when a pre-payment is left. 4. **Over-payment.** Pay more than is owed and the extra remains as a pre-payment lot, shown by [payment.openItems](method/payment.openItems), ready to be applied to the next document. 5. **Vendors and employees.** Use the same calls with the owner type `vendor` or `employee`. The `amount` is signed: positive when a customer pays you or when you pay a vendor or an employee, as the reference page for [payment.process](method/payment.process) explains. 6. **A deposit already in the book.** If a transaction was entered as a plain deposit, turn it into a payment with [payment.fromTransaction](method/payment.fromTransaction), naming the owner and the documents. 7. **Bad debt.** When a customer will not pay, pay the rest of the invoice with [invoice.pay](method/invoice.pay), with an expense account such as `Bad debts` as the `transferAccount`. The invoice closes and the expense records the loss. ## Example *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`, at 2024-03-25T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"payment.openItems","params":{"owner":{"type":"customer","id":"5b22073fa4e34411b07c14a77147ce6b"},"account":"Assets:Receivable"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "items": [ { "invoice": "aa210b7131de44c48b8513cd27c00e95", "balance": { "num": "87300", "denom": "100" }, "…": "…" } ] } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"payment.process","params":{"owner":{"type":"customer","id":"5b22073fa4e34411b07c14a77147ce6b"},"account":"Assets:Receivable","transferAccount":"Assets:Bank","amount":"300.00","date":"2024-03-25","applyTo":["aa210b7131de44c48b8513cd27c00e95"]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "transaction": "…", "paymentLot": null } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"payment.openItems","params":{"owner":{"type":"customer","id":"5b22073fa4e34411b07c14a77147ce6b"},"account":"Assets:Receivable"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "items": [ { "invoice": "aa210b7131de44c48b8513cd27c00e95", "balance": { "num": "57300", "denom": "100" }, "…": "…" } ] } } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"invoice.pay","params":{"invoice":"95e2e7416db94eb3a7de7433f3e7875f","transferAccount":"Assets:Bank","amount":"20.00","date":"2024-03-25","memo":"Part payment"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "transaction": "…", "paymentLot": null } } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"payment.process","params":{"owner":{"type":"vendor","id":"9697710198334d558a9bfde219bb1e41"},"account":"Liabilities:Payable","transferAccount":"Assets:Bank","amount":"10.00","date":"2024-03-25"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": { "transaction": "…", "paymentLot": "…" } } ``` ## Related - [payment.openItems](method/payment.openItems) - [payment.process](method/payment.process) - [payment.fromTransaction](method/payment.fromTransaction) - [invoice.pay](method/invoice.pay) - [invoice.get](method/invoice.get) - [invoice.list](method/invoice.list) --- *red-ale Manual, `guide/process-payments`. Adapted from GnuCash's documentation, `manual/ch_Business.docbook#busnss-ar-payment`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Reconcile an account Match an account to a bank or card statement: start with the statement date and ending balance, tick the splits that appear on it, and finish when the difference is zero, or postpone. Reconciling checks your books against the statement the bank sends. You tick every split that appears on the statement; when the ticked splits bring the account to the statement's ending balance, the difference is zero and you finish. The ticked splits become *reconciled* (`y`), and the next reconciliation starts from there. Each split is in one of three states: not cleared (`n`), cleared (`c`, ticked but not final) or reconciled (`y`). red-ale keeps no reconcile window. Each call is complete in itself: you carry the statement date, the ending balance and the list of ticked splits from call to call. ## Steps 1. **Start** with [reconcile.start](method/reconcile.start): the `account`, the `statementDate` and the `endingBalance` from the statement. It changes nothing. It returns the splits to consider, with the cleared ones already ticked, the `startingBalance` (what was reconciled last time), the `tickedBalance` and the `difference` still to explain. Amounts use the account's raw sign, so for a credit card the balance is negative. Leave out the date and balance to get GnuCash's defaults, or a postponed reconciliation's. 2. **Tick** splits. Try a selection with [reconcile.status](method/reconcile.status), passing `mark`: the splits you would tick, and it returns the new balances without keeping anything. To keep a split cleared between calls, set it with [reconcile.setState](method/reconcile.setState), state `c`. 3. **Let red-ale find a selection** with [reconcile.autoClear](method/reconcile.autoClear): give the `clearedBalance` the ticked splits must reach, and it finds the uncleared splits that make up the difference, as GnuCash's Auto-clear does. It refuses when no subset reaches that balance (reason `unreachable`). 4. **Finish** with [reconcile.finish](method/reconcile.finish), passing the same statement and the list of `ticked` splits. It is refused unless the difference is zero. The ticked splits become reconciled; the date and balance are remembered for next time ([reconcile.info](method/reconcile.info)). 5. **Cannot finish today?** [reconcile.postpone](method/reconcile.postpone) saves your ticks as cleared and remembers the statement; the next [reconcile.start](method/reconcile.start) picks it up (`resumedPostponed: true`). 6. **Find the cause of a difference** by checking amounts and dates against the statement, and look for a transaction entered twice or not at all. If a transaction is missing, post it ([Record deposits and withdrawals](guide/record-deposits-and-withdrawals)) and start again. ## Example *Example: with a copy of the `reports/reconcile` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"reconcile.start","params":{"account":"Root:Asset:Bank","statementDate":"1970-03-01","endingBalance":"21.00"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "statementDate": "1970-03-01", "endingBalance": { "num": "2100", "denom": "100" }, "resumedPostponed": false, "difference": { "num": "0", "denom": "100" }, "ticked": [ "d0000000000000000000000000000005" ], "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"reconcile.status","params":{"account":"Root:Asset:Bank","statementDate":"1970-03-01","endingBalance":"21.00","mark":["d0000000000000000000000000000006"]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "tickedBalance": { "num": "1400", "denom": "100" }, "difference": { "num": "1500", "denom": "100" }, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"reconcile.finish","params":{"account":"Root:Asset:Bank","statementDate":"1970-03-01","endingBalance":"21.00","ticked":["d0000000000000000000000000000005"]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "reconciled": [ { "split": "d0000000000000000000000000000005", "from": "c", "to": "y", "…": "…" } ], "difference": { "num": "0", "denom": "100" }, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"reconcile.info","params":{"account":"Root:Asset:Bank"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "lastDate": "…", "postponeDate": null, "…": "…" } } ``` A statement that does not match is refused, and nothing is reconciled: *Example: with a copy of the `reports/reconcile` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"reconcile.finish","params":{"account":"Root:Asset:Bank","statementDate":"1970-03-01","endingBalance":"9.00","ticked":[]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": 2001, "message": "…", "data": { "help": "error/invalid" } } } ``` ## Related - [reconcile.start](method/reconcile.start) - [reconcile.status](method/reconcile.status) - [reconcile.setState](method/reconcile.setState) - [reconcile.autoClear](method/reconcile.autoClear) - [reconcile.finish](method/reconcile.finish) - [reconcile.postpone](method/reconcile.postpone) - [reconcile.info](method/reconcile.info) - [reconcile.setInfo](method/reconcile.setInfo) - [invalid](error/invalid) - [Accounts and the Actions menu](gnucash/account-menu) - [Reconciliation](concept/reconciliation) --- *red-ale Manual, `guide/reconcile-an-account`. Adapted from GnuCash's documentation, `guide/ch_cbook.docbook#chapter_cbook`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Record deposits and withdrawals Enter income, expenses and cash withdrawals as balanced transactions, then check the balance and list what you have entered. Day-to-day bookkeeping is a sequence of transactions: your pay arrives in the bank, you buy groceries, you take cash out of a machine. In double-entry bookkeeping each one is a date, a description and two or more splits whose values sum to exactly zero. A *value* is in the transaction's currency; positive values are debits, negative values credits. ## The sign rule The account you name decides what a sign means. A positive value on a bank account is a deposit, a negative one a withdrawal. On an income account the signs run the other way, because income is a credit: pay of 2,500.00 is `+2500.00` on the bank account and `-2500.00` on the income account. An expense is `+` on the expense account and `-` on the account you paid from. ## Steps 1. **Make the accounts** the transaction needs (see [Set up accounts](guide/set-up-accounts)): a bank account, a cash account, an income account and an expense account. 2. **Record a deposit**: [transaction.post](method/transaction.post) with `datePosted`, `description` and two splits, the bank account `+` and the income account `-`. 3. **Record an expense**: the expense account `+` and the account that paid `-`. 4. **Record a cash withdrawal**: a transfer from the bank account to the cash account, `-` and `+`. It is neither income nor expense, so no category is involved. 5. **Check** the balance with [account.balance](method/account.balance), and review the entries with [transaction.list](method/transaction.list), optionally for one account and a date range. If the splits do not sum to zero the call fails with [unbalanced](error/unbalanced) and nothing is recorded, so a typing slip never leaves a half-entered transaction. ## Example *Example: with a new, empty book open as `book.gnucash`, at 2024-07-15T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Wallet","type":"CASH","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"account.create","params":{"name":"Salary","type":"INCOME","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"account.create","params":{"name":"Groceries","type":"EXPENSE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"transaction.post","params":{"datePosted":"2024-07-01","description":"July pay","splits":[{"account":"Checking","value":"2500.00"},{"account":"Salary","value":"-2500.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": { "description": "July pay", "balanced": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":6,"method":"transaction.post","params":{"datePosted":"2024-07-03","description":"ATM","splits":[{"account":"Wallet","value":"100.00"},{"account":"Checking","value":"-100.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 6, "result": { "balanced": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":7,"method":"transaction.post","params":{"datePosted":"2024-07-05","description":"Market","splits":[{"account":"Groceries","value":"63.40"},{"account":"Wallet","value":"-63.40"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 7, "result": { "balanced": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":8,"method":"account.balance","params":{"account":"Checking"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 8, "result": { "balances": { "commodity": "CURRENCY::USD", "balance": { "num": "240000", "denom": "100" }, "…": "…" }, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":9,"method":"account.balance","params":{"account":"Wallet"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 9, "result": { "balances": { "balance": { "num": "3660", "denom": "100" }, "…": "…" }, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":10,"method":"transaction.list","params":{"account":"Wallet"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 10, "result": { "transactions": [ { "description": "ATM", "…": "…" }, { "description": "Market", "…": "…" } ] } } ``` ## Related - [transaction.post](method/transaction.post) - [account.balance](method/account.balance) - [transaction.list](method/transaction.list) - [account.create](method/account.create) - [unbalanced](error/unbalanced) - [Windows and registers](gnucash/windows-and-registers) --- *red-ale Manual, `guide/record-deposits-and-withdrawals`. Adapted from GnuCash's documentation, `guide/ch_basics.docbook#basics-together1`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Record dividends and return of capital Record a cash dividend as income, a reinvested dividend as new shares, and a return of capital as a reduction in cost. A company that shares its profit pays a *dividend*. You can take it as cash, or have it reinvested in more shares. A *return of capital* looks the same on the statement but is not income: it hands part of your original investment back, so it lowers the cost you paid for the shares. All three are ordinary transactions. You need the accounts of [Buy and sell shares](guide/buy-and-sell-shares) and an income account for dividends. ## Steps 1. **Cash dividend.** The dividend is income, so credit an income account, and the cash lands in your brokerage cash account: cash `+`, `Dividends` `-`. 2. **Reinvested dividend.** The dividend is income and you spend it at once on shares: the share account `+` with its `amount` in shares and its `value` in dollars, and `Dividends` `-`. No cash moves. Set `currency`, since the first split may be in shares. 3. **Return of capital.** Cash arrives and the cost of the shares falls: cash `+`, and the share account `-` with a value and an `amount` of `0`. The shares are the same; they cost less. 4. **Foreign withholding tax or fees** are further expense splits in the same transaction. 5. **Check** with [account.balance](method/account.balance). ## Example *Example: with a new, empty book open as `book.gnucash`, at 2024-07-31T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"commodity.create","params":{"namespace":"NASDAQ","mnemonic":"AAPL","fullname":"Apple Inc"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Cash","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"account.create","params":{"name":"AAPL","type":"STOCK","commodity":"NASDAQ::AAPL"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"account.create","params":{"name":"Dividends","type":"INCOME","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"account.create","params":{"name":"Opening Balances","type":"EQUITY","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":6,"method":"transaction.post","params":{"datePosted":"2024-06-01","description":"Opening","currency":"USD","splits":[{"account":"AAPL","value":"1500.00","amount":"10"},{"account":"Opening Balances","value":"-1500.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 6, "result": { "balanced": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":7,"method":"transaction.post","params":{"datePosted":"2024-07-10","description":"Cash dividend","splits":[{"account":"Cash","value":"24.00"},{"account":"Dividends","value":"-24.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 7, "result": { "balanced": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":8,"method":"transaction.post","params":{"datePosted":"2024-07-15","description":"Reinvested dividend","currency":"USD","splits":[{"account":"AAPL","value":"24.00","amount":"0.15"},{"account":"Dividends","value":"-24.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 8, "result": { "balanced": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":9,"method":"transaction.post","params":{"datePosted":"2024-07-20","description":"Return of capital","currency":"USD","splits":[{"account":"Cash","value":"50.00"},{"account":"AAPL","value":"-50.00","amount":"0"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 9, "result": { "balanced": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":10,"method":"account.balance","params":{"account":"AAPL"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 10, "result": { "balances": { "commodity": "NASDAQ::AAPL", "balance": { "num": "101500", "denom": "10000" }, "…": "…" }, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":11,"method":"account.balance","params":{"account":"Dividends"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 11, "result": { "balances": { "balance": { "num": "-4800", "denom": "100" }, "…": "…" }, "…": "…" } } ``` ## Related - [transaction.post](method/transaction.post) - [account.create](method/account.create) - [account.balance](method/account.balance) - [Buy and sell shares](guide/buy-and-sell-shares) - [Stock assistants](gnucash/stock-assistants) --- *red-ale Manual, `guide/record-dividends`. Adapted from GnuCash's documentation, `guide/ch_invest.docbook#invest-dividends1`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Record prices and commodities Add a security, record its price by hand, turn on online quotes, and tidy old prices out of the price database. Reports that show what your shares are worth, and accounts held in a foreign currency, need prices: how many dollars one share, or one euro, was worth on a day. The book keeps them in its **price database**, one price per commodity, currency and day. You can enter prices by hand, or let red-ale fetch them from an online quote service. ## Steps 1. **Add the commodity** with [commodity.create](method/commodity.create) (see [Buy and sell shares](guide/buy-and-sell-shares)). Currencies are already known and need no creating. 2. **Enter a price by hand** with [price.add](method/price.add): the `commodity`, the `currency` the price is in, the `value` (currency units per commodity unit, as an exact string) and the `date`. A price already stored for the same pair and day is replaced, or kept, according to which source is more trusted, as in GnuCash; `outcome` says what happened. 3. **Look at the prices** with [price.list](method/price.list), by commodity, currency and dates. 4. **Fetch prices online.** Mark the commodity with [commodity.update](method/commodity.update): `quoteFlag: true` and a `quoteSource` such as `yahoo_json`. Then switch on the network, which is off by default, with [config.set](method/config.set) (`{"changes": {"quotes.network": true}}`), and call [price.fetchQuotes](method/price.fetchQuotes). It answers at once with a fetch ID; ask [price.fetchStatus](method/price.fetchStatus) for the result per commodity. Until the network is switched on the call fails with [network-disabled](error/network-disabled) and sends nothing. Over MCP the setting cannot be changed, so a person turns it on. 5. **Tidy the database** with [price.removeOld](method/price.removeOld): choose the commodities, a `before` date, which `sources` may go (`fetched`, `user` or `app`) and what to `keep` (the last price of each week, month or quarter, or `none`). ## Example *Example: with a new, empty book open as `book.gnucash`, at 2024-07-01T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"commodity.create","params":{"namespace":"NASDAQ","mnemonic":"AAPL","fullname":"Apple Inc"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "id": "NASDAQ::AAPL", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"commodity.update","params":{"commodity":"NASDAQ::AAPL","quoteFlag":true,"quoteSource":"yahoo_json"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "quoteFlag": true, "quoteSource": "yahoo_json", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"price.add","params":{"commodity":"NASDAQ::AAPL","currency":"USD","value":"150.25","date":"2023-12-29"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "outcome": "added", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"price.add","params":{"commodity":"NASDAQ::AAPL","currency":"USD","value":"187.10","date":"2024-06-28"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "outcome": "added", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"price.list","params":{"commodity":"NASDAQ::AAPL"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": [ { "date": "2024-06-28", "value": { "num": "18710", "denom": "100" }, "…": "…" }, { "date": "2023-12-29", "value": { "num": "15025", "denom": "100" }, "…": "…" } ] } ``` Request: ```json {"jsonrpc":"2.0","id":6,"method":"price.fetchQuotes","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 6, "error": { "code": 5000, "message": "…", "data": { "help": "error/network-disabled" } } } ``` Request: ```json {"jsonrpc":"2.0","id":7,"method":"price.removeOld","params":{"commodities":["NASDAQ::AAPL"],"before":"2024-01-01","sources":["app"],"keep":"none"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 7, "result": { "removed": [ "…" ] } } ``` ## Related - [commodity.create](method/commodity.create) - [commodity.update](method/commodity.update) - [price.add](method/price.add) - [price.list](method/price.list) - [price.fetchQuotes](method/price.fetchQuotes) - [price.fetchStatus](method/price.fetchStatus) - [price.removeOld](method/price.removeOld) - [config.set](method/config.set) - [network-disabled](error/network-disabled) - [Prices and exchange rates](concept/prices-and-exchange-rates) - [Not in red-ale](gnucash/not-in-red-ale) - [Tools, scheduled transactions and budgets](gnucash/tools-menu) --- *red-ale Manual, `guide/record-prices`. Adapted from GnuCash's documentation, `guide/ch_invest.docbook#invest-stockprice1`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Turn a report into a PDF red-ale exports reports as HTML only; write the HTML to a file with report.export, then convert it with pandoc, wkhtmltopdf or a browser's print-to-PDF. GnuCash prints a report to a PDF file. red-ale does not: it has no PDF export and none is planned. A report is exported as one self-contained HTML page ([report.export](method/report.export)), and a PDF is made from that page by a program built for the job. The page has no script and no outside resources, so any converter reads it the same way. ## Steps 1. **Export the report to a file.** With the CLI, `--output` writes the page on your side: ``` red-ale exec --book book.gnucash --output report.html report.export '{"report": "Balance Sheet"}' ``` Over JSON-RPC or MCP, take the result's `html` and write it to a file yourself. 2. **Convert it** with any of these (install them from your system's packages; red-ale does not include them): - pandoc, which needs a PDF engine such as WeasyPrint or a LaTeX system installed: `pandoc report.html -o report.pdf --pdf-engine=weasyprint` - wkhtmltopdf: `wkhtmltopdf report.html report.pdf` - a headless browser: `chromium --headless --print-to-pdf=report.pdf report.html` 3. **Or print from a browser.** Open `report.html` and choose Print, then Save as PDF. 4. **Check the result.** The tools differ in how they treat wide tables and page breaks, so look at the PDF before you send it. An invoice for a customer is the usual case; see [Print an invoice](guide/print-an-invoice). ## Example The export that step 1 starts from: the page is in the result's `html`. *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`, at 2024-03-15T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"report.export","params":{"report":"Balance Sheet","options":{"General":{"Balance Sheet Date":{"absolute":"1978-12-31"}}}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "title": " Balance Sheet 12/31/78", "html": "…" } } ``` ## Related - [report.export](method/report.export) - [report.run](method/report.run) - [Run and export a report](guide/run-and-export-a-report) --- *red-ale Manual, `guide/report-to-pdf`. Adapted from GnuCash's documentation, `manual/ch_Reports.docbook#report-print`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Run and export a report Find a report, read its options, run it for exact figures, export it as HTML or CSV, save a set of options under a name, and choose a style sheet. A report summarises the book: a balance sheet, an income statement, a transaction listing. In red-ale a report is a *template* with *options*. You choose a template, set the options you care about, and run it. The result is data: every figure is exact and comes with its display form, so a program can use it and a person can read it. To read it as a page, export it as HTML. ## Steps 1. **Find the report.** [report.list](method/report.list) lists the report templates, each with its name and GUID, and any saved configurations. The reports are described in the manual's *Reports* section (for example [Balance Sheet](report/balance-sheet)). `problems` lists user scripts that did not load. 2. **Read its options.** [report.options](method/report.options) gives each option's section, name, type, default and help text, and a JSON Schema for the `options` param. 3. **Run it** with [report.run](method/report.run). Give `options` only for the ones you change, as `{"Section": {"Name": value}}`. Dates are `{"absolute": "2024-03-31"}` or `{"relative": "end-this-month"}`. "Today" is the session's clock unless you give `now`. A wrong option name or value is refused with a [report-option](error/report-option) error that names it. 4. **Export it.** [report.export](method/report.export) gives the same report as one self-contained HTML page, with no script and no outside resource. [report.exportCsv](method/report.exportCsv) gives CSV for the reports that have one. The CLI's `--output` writes either to a file on your side. 5. **Save the options** you used with [report.saveConfiguration](method/report.saveConfiguration), under a new name. This is GnuCash's saved report configuration. Run it again by name with [report.run](method/report.run). Saved configurations live in red-ale's configuration, not in the book. 6. **Choose how it looks.** The `General/Stylesheet` option names a style sheet; [report.styleSheets](method/report.styleSheets) lists them. Pass `styleSheet` to [report.export](method/report.export) to use another for one export. 7. **To print on paper,** open the HTML in a browser, or [turn it into a PDF](guide/report-to-pdf). ## Example *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`, at 2024-03-15T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"report.options","params":{"report":"Balance Sheet"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "report": { "name": "Balance Sheet", "…": "…" }, "options": "…", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"report.run","params":{"report":"Balance Sheet","options":{"General":{"Balance Sheet Date":{"absolute":"1978-12-31"}}}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "title": " Balance Sheet 12/31/78", "report": { "name": "Balance Sheet", "…": "…" }, "sections": "…", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"report.export","params":{"report":"Balance Sheet","options":{"General":{"Balance Sheet Date":{"absolute":"1978-12-31"}}}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "title": " Balance Sheet 12/31/78", "html": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"report.saveConfiguration","params":{"name":"Balance sheet 1978","report":"Balance Sheet","options":{"General":{"Balance Sheet Date":{"absolute":"1978-12-31"}}}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "name": "Balance sheet 1978", "kind": "saved", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"report.run","params":{"report":"Balance sheet 1978"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": { "title": " Balance Sheet 12/31/78", "…": "…" } } ``` A report with CSV output gives its figures as text: *Example: with a copy of the `reports/category-daily` example book open as `book.gnucash`, at 2024-03-15T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"report.exportCsv","params":{"report":"Income Over Time","options":{"Accounts":{"Accounts":["a0000000000000000000000000000003"]},"General":{"Start Date":{"absolute":"2024-03-01"},"End Date":{"absolute":"2024-03-31"},"Step Size":"WeekDelta"}}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "title": "", "csv": "\"Date\",\"account-3\"\n\"2024-03-01\",28.0\n\"2024-03-08\",77.0\n\"2024-03-15\",126.0\n\"2024-03-22\",175.0\n\"2024-03-29\",90.0" } } ``` ## Related - [report.list](method/report.list) - [report.options](method/report.options) - [report.run](method/report.run) - [report.export](method/report.export) - [report.exportCsv](method/report.exportCsv) - [report.saveConfiguration](method/report.saveConfiguration) - [report.styleSheets](method/report.styleSheets) - [Balance Sheet](report/balance-sheet) - [Reports](concept/reports) - [Tools, scheduled transactions and budgets](gnucash/tools-menu) --- *red-ale Manual, `guide/run-and-export-a-report`. Adapted from GnuCash's documentation, `guide/ch_cbook.docbook#cbook-puttoget-reports`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Schedule a transaction Set up a transaction that repeats (rent, a salary, a loan payment), see when it falls due, and create what is due with Since Last Run. Some transactions come round on a rhythm: rent on the first of the month, a salary every fortnight, a loan payment. A **scheduled transaction** keeps a template of such a transaction and a schedule, and creates the real transactions when they fall due. Nothing happens by itself in a headless program: *you* ask what is due, look at it, and apply it, usually when you open the book. GnuCash calls this *Since Last Run*. ## Steps 1. **Start from an existing transaction.** If you have already posted the first rent payment, call [scheduledTransaction.fromTransaction](method/scheduledTransaction.fromTransaction) with its GUID and a `frequency` (`monthly`, `weekly`, and so on). It returns the scheduled transaction it would make from it, to check or adjust. Or build one from scratch with [scheduledTransaction.create](method/scheduledTransaction.create): a `name`, a `startDate`, a `schedule` (a list of recurrences: `{mult: 1, periodType: "month"}`), and template transactions whose splits take a `debitFormula` or `creditFormula`. 2. **Use a formula, not just a number,** when the amount varies. A formula can use variables, which you supply when you apply the proposal. 3. **Preview the dates** with [scheduledTransaction.occurrences](method/scheduledTransaction.occurrences), for an existing schedule or for one you describe. 4. **Ask what is due** with [scheduledTransaction.sinceLastRun](method/scheduledTransaction.sinceLastRun). It lists every occurrence between the last one created and today with a state (`toCreate`, `reminder` and so on) and a proposal `id`. It changes nothing. 5. **Apply it** with [scheduledTransaction.apply](method/scheduledTransaction.apply) and that `id`. In `choices` you can change one instance's state (to `postponed` or `ignored`) or give a variable its value. All instances are checked first, so if one fails none is created. Or drop the proposal with [scheduledTransaction.discard](method/scheduledTransaction.discard). 6. **For loans**, [scheduledTransaction.loan](method/scheduledTransaction.loan) is GnuCash's Loan assistant: give the loan account, principal, annual `rate`, `length` and the accounts to pay from and charge interest to, and it makes the scheduled transaction with the payment formulas. 7. **List them** with [scheduledTransaction.list](method/scheduledTransaction.list). ## Example *Example: with a new, empty book open as `book.gnucash`, at 2024-07-01T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Rent","type":"EXPENSE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"scheduledTransaction.create","params":{"name":"Monthly rent","startDate":"2024-05-01","schedule":[{"mult":1,"periodType":"month"}],"templateTransactions":[{"description":"Rent","splits":[{"account":"Rent","debitFormula":"750"},{"account":"Checking","creditFormula":"750"}]}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "name": "Monthly rent", "enabled": true, "nextOccurrence": "2024-05-01", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"scheduledTransaction.sinceLastRun","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "id": "slr-1", "today": "2024-07-01", "summary": { "toCreate": 3, "reminders": 0, "postponed": 0, "errors": 0, "…": "…" }, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"scheduledTransaction.apply","params":{"proposal":"slr-1"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": { "created": [ { "index": 0, "date": "2024-05-01", "transactions": [ "…" ], "…": "…" }, { "index": 1, "date": "2024-06-01", "transactions": [ "…" ], "…": "…" }, { "index": 2, "date": "2024-07-01", "transactions": [ "…" ], "…": "…" } ], "ignored": [], "postponed": [], "reminders": [], "schedules": [ "…" ], "imbalanceSplits": [], "warnings": [] } } ``` The proposal's `id` is the one `sinceLastRun` gave; it counts up from `slr-1` in each server process. Applying creates the three rent transactions, 750.00 each, and moves the schedule on. A second `scheduledTransaction.sinceLastRun` then finds nothing to create until the next occurrence, 1 August. ## Related - [scheduledTransaction.create](method/scheduledTransaction.create) - [scheduledTransaction.fromTransaction](method/scheduledTransaction.fromTransaction) - [scheduledTransaction.sinceLastRun](method/scheduledTransaction.sinceLastRun) - [scheduledTransaction.apply](method/scheduledTransaction.apply) - [scheduledTransaction.discard](method/scheduledTransaction.discard) - [scheduledTransaction.loan](method/scheduledTransaction.loan) - [scheduledTransaction.occurrences](method/scheduledTransaction.occurrences) - [scheduledTransaction.list](method/scheduledTransaction.list) - [Scheduled transactions](concept/scheduled-transactions) - [Tools, scheduled transactions and budgets](gnucash/tools-menu) --- *red-ale Manual, `guide/schedule-a-transaction`. Adapted from GnuCash's documentation, `guide/ch_loans.docbook#loans_mortgage1`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Set up accounts Build a chart of accounts for a household (assets, credit cards, income, expenses), change it, renumber it, move and delete accounts, and enter opening balances. The chart of accounts is the skeleton of the book: every transaction moves value between its accounts. A household usually needs somewhere to keep money (assets), somewhere that records what is owed (liabilities), and categories for money coming in (income) and going out (expenses). This guide builds a small chart, adjusts it, and starts it off with the balances you have today. ## Steps 1. **Plan the tree.** Accounts nest: `Assets:Current Assets:Checking`. A parent that only groups its children is usually a placeholder, which cannot take transactions itself. [account.types](method/account.types) lists the types (`BANK`, `CASH`, `CREDIT`, `ASSET`, `LIABILITY`, `INCOME`, `EXPENSE`, `EQUITY`, `STOCK`, and so on); a child's type must suit its parent's. 2. **Create the parents, then the children** with [account.create](method/account.create). `parent` is the full name of the parent (the root by default) and `commodity` the currency; a child takes its parent's commodity if you leave it out. 3. **Edit** with [account.update](method/account.update): name, code, description, notes, colour, hidden, placeholder. You cannot change the commodity of an account that already has splits, or the type to one the parent does not allow. 4. **Number the accounts** with [account.renumber](method/account.renumber): give a subtree a `prefix` and an `interval`, and its accounts get codes `1-100`, `1-200` and so on. 5. **Set one property down a whole subtree** with [account.cascade](method/account.cascade), for example a colour or `hidden`. 6. **Move** an account to another parent with [account.move](method/account.move), with its sub-accounts and transactions. 7. **Delete** with [account.delete](method/account.delete). An account that has transactions is refused unless you say where they go: `transactions: {"moveTo": ""}` moves its splits, or you can delete the transactions. Sub-accounts are moved up or deleted the same way. 8. **Enter opening balances.** The money you already have when you start is recorded as a transaction against an Equity account called Opening Balances. [account.openingBalanceAccount](method/account.openingBalanceAccount) finds it. Create it with `openingBalance: true` if there is none, then post one transaction per opening balance with [transaction.post](method/transaction.post): a positive value on the asset account and the same amount, negative, on Opening Balances. For a credit card or loan, reverse the signs. 9. **Keep a copy of the chart** with [export.accounts](method/export.accounts), which writes the accounts and their commodities to a file you can import into another book. ## Example A small household chart, with an opening balance. *Example: with a new, empty book open as `book.gnucash`, at 2024-07-01T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Assets","type":"ASSET","commodity":"USD","placeholder":true}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "fullName": "Assets", "placeholder": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Checking","type":"BANK","parent":"Assets"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "fullName": "Assets:Checking", "commodity": "CURRENCY::USD", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"account.create","params":{"name":"Wallet","type":"CASH","parent":"Assets"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "fullName": "Assets:Wallet", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"account.create","params":{"name":"Expenses","type":"EXPENSE","commodity":"USD","placeholder":true}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "fullName": "Expenses", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"account.create","params":{"name":"Food","type":"EXPENSE","parent":"Expenses"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": { "fullName": "Expenses:Food", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":6,"method":"account.update","params":{"account":"Assets:Wallet","description":"Cash on hand"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 6, "result": { "fullName": "Assets:Wallet", "description": "Cash on hand", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":7,"method":"account.renumber","params":{"account":"Assets","prefix":"1","interval":100}} ``` Response: ```json { "jsonrpc": "2.0", "id": 7, "result": [ { "account": "…", "fullName": "Assets:Wallet", "code": "1-100" }, { "account": "…", "fullName": "Assets:Checking", "code": "1-200" } ] } ``` Request: ```json {"jsonrpc":"2.0","id":8,"method":"account.openingBalanceAccount","params":{"currency":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 8, "result": { "account": null, "foundBy": null, "featureUsed": false } } ``` Request: ```json {"jsonrpc":"2.0","id":9,"method":"account.create","params":{"name":"Opening Balances","type":"EQUITY","commodity":"USD","openingBalance":true}} ``` Response: ```json { "jsonrpc": "2.0", "id": 9, "result": { "fullName": "Opening Balances", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":10,"method":"transaction.post","params":{"datePosted":"2024-07-01","description":"Opening balance","splits":[{"account":"Assets:Checking","value":"1250.00"},{"account":"Opening Balances","value":"-1250.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 10, "result": { "balanced": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":11,"method":"account.move","params":{"account":"Assets:Wallet","parent":"Assets:Checking"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 11, "result": { "fullName": "Assets:Checking:Wallet", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":12,"method":"account.delete","params":{"account":"Assets:Checking:Wallet"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 12, "result": { "deletedAccounts": [ "…" ], "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":13,"method":"account.balance","params":{"account":"Assets:Checking"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 13, "result": { "balances": { "commodity": "CURRENCY::USD", "balance": { "num": "125000", "denom": "100" }, "…": "…" }, "…": "…" } } ``` ## Related - [account.create](method/account.create) - [account.update](method/account.update) - [account.renumber](method/account.renumber) - [account.cascade](method/account.cascade) - [account.move](method/account.move) - [account.delete](method/account.delete) - [account.openingBalanceAccount](method/account.openingBalanceAccount) - [export.accounts](method/export.accounts) - [transaction.post](method/transaction.post) - [account.types](method/account.types) - [Not in red-ale](gnucash/not-in-red-ale) - [Loans and interest](concept/loans-and-interest) - [Other assets and depreciation](concept/other-assets-and-depreciation) - [File menu and the New File assistant](gnucash/file-menu) - [Accounts and the Actions menu](gnucash/account-menu) - [The chart of accounts](concept/chart-of-accounts) --- *red-ale Manual, `guide/set-up-accounts`. Adapted from GnuCash's documentation, `guide/ch_basics.docbook#basics-expt-acct`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Set up the business features Prepare a book for invoices and bills: receivable and payable accounts, tax tables, billing terms, document numbering and your company's details. GnuCash's business features (customers, vendors, employees, invoices, bills and payments) rest on a few settings made once per book. This guide sets them up. Then [Invoices and bills](guide/invoices-and-bills) and [Process payments](guide/process-payments) can use them. ## Steps 1. **Accounts.** Every posted document goes to a control account: money customers owe you is in an `RECEIVABLE` account, money you owe vendors in a `PAYABLE` account, and each must be in the document's currency. Create them with [account.create](method/account.create). Also create an income account for what you sell, an expense account for what you buy, and a liability account for each tax you collect. 2. **Tax tables.** [taxTable.create](method/taxTable.create) names a tax and its lines: each line is a tax `account`, an `amount` and a `type`, either `percent` of the price or a fixed `value`. A table can have several lines, for a tax plus a levy. 3. **Billing terms.** [billTerm.create](method/billTerm.create) names a payment rule. `days`: due so many days after the posting date (`dueDays`). `proximo`: due on a day of the month, and `cutoff` says after which day of the month a document waits until the next. `discountDays` and `discount` store an early-payment discount. 4. **Numbering.** Documents, customers and others take their numbers from counters. [counter.list](method/counter.list) shows them; [counter.set](method/counter.set) sets `last` (the last number used, so the next is one more) and a `format` such as `INV-%04li`. 5. **Company details.** [book.setOptions](method/book.setOptions) sets `companyName`, `companyAddress` (lines separated by newlines), `companyContactPerson`, `companyPhoneNumber`, `companyFaxNumber`, `companyEmailAddress`, `companyWebsiteUrl`, `companyId` and `taxNumber`. They print in the header of the invoice ([Print an invoice](guide/print-an-invoice)). [book.options](method/book.options) reads them back. 6. **Defaults.** A customer or vendor can name a tax table and billing term of its own; see [customer.create](method/customer.create). ## Example The accounts for the business features, in a new book: *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Accounts Receivable","type":"RECEIVABLE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "type": "RECEIVABLE", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Accounts Payable","type":"PAYABLE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "type": "PAYABLE", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"account.create","params":{"name":"Sales Tax","type":"LIABILITY","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"taxTable.create","params":{"name":"Sales tax 8%","entries":[{"account":"Sales Tax","amount":"8","type":"percent"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "name": "Sales tax 8%", "entries": [ { "accountName": "Sales Tax", "amount": { "num": "8", "denom": "1" }, "type": "percent", "…": "…" } ], "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"billTerm.create","params":{"name":"Net14","type":"days","dueDays":14}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": { "name": "Net14", "type": "days", "dueDays": 14, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":6,"method":"counter.set","params":{"name":"gncInvoice","last":41,"format":"INV-%04li"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 6, "result": { "name": "gncInvoice", "last": 41, "format": "INV-%04li", "next": "INV-0042", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":7,"method":"book.setOptions","params":{"companyName":"Acme Ltd","companyAddress":"1 Main St\nSpringfield","companyEmailAddress":"billing@acme.example"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 7, "result": { "companyName": "Acme Ltd", "companyEmailAddress": "billing@acme.example", "…": "…" } } ``` ## Related - [account.create](method/account.create) - [taxTable.create](method/taxTable.create) - [billTerm.create](method/billTerm.create) - [counter.set](method/counter.set) - [counter.list](method/counter.list) - [book.setOptions](method/book.setOptions) - [book.options](method/book.options) - [Preferences and book options](gnucash/preferences-and-book-options) --- *red-ale Manual, `guide/set-up-business`. Adapted from GnuCash's documentation, `guide/ch_bus_features.docbook#bus_setup`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Split transactions Record one payment that is divided among several accounts (a pay slip, a shop receipt), then add, change or remove a split while keeping the transaction balanced. Most transactions have two splits: money leaves one account and arrives in another. A *split transaction* has more: your salary arrives in the bank as one deposit but is really gross pay less tax and pension; a supermarket receipt is one payment covering food and household goods. Each split names an account and a value, and the values must still sum to exactly zero. ## Steps 1. **Work out the parts.** For a 2,000.00 pay slip with 300.00 tax and 100.00 pension, the bank receives 1,600.00. The parts are: bank `+1600.00`, tax expense `+300.00`, pension expense `+100.00`, and the salary income account `-2000.00`. They sum to zero. 2. **Post it** with [transaction.post](method/transaction.post), listing every split. A split may carry a `memo`, which describes that line only. 3. **Look at it** with [transaction.get](method/transaction.get). Every split has a GUID. 4. **Change a split** with [transaction.update](method/transaction.update): `changeSplits` takes the split's `guid` and the fields to change, `addSplits` takes new splits, `removeSplits` takes GUIDs. The result must balance, so a change that leaves the transaction short is refused with [unbalanced](error/unbalanced) and nothing changes. Change two splits in one call to keep it balanced. 5. **Remove a split** by listing its GUID in `removeSplits` and changing another to take up the difference in the same call. ## Example *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Salary","type":"INCOME","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"account.create","params":{"name":"Tax","type":"EXPENSE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"account.create","params":{"name":"Pension","type":"EXPENSE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"transaction.post","params":{"datePosted":"2024-07-01","description":"July pay slip","splits":[{"account":"Checking","value":"1600.00"},{"account":"Tax","value":"300.00","memo":"Income tax"},{"account":"Pension","value":"100.00"},{"account":"Salary","value":"-2000.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": { "guid": "…", "balanced": true, "splits": [ "…", "…", "…", "…" ], "…": "…" } } ``` To change a split you need its GUID, from [transaction.get](method/transaction.get) or the result of the post. This removes the wallet split of a three-split transaction and makes the expense split take the whole 100.00, in one call: *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"transaction.update","params":{"guid":"c0000000000000000000000000000007","removeSplits":["d0000000000000000000000000000010"],"changeSplits":[{"guid":"d000000000000000000000000000000f","value":"100.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "balanced": true, "splits": [ { "accountName": "Root:Expenses", "value": { "num": "10000", "denom": "100" }, "…": "…" }, { "accountName": "Root:Asset:Bank", "value": { "num": "-10000", "denom": "100" }, "…": "…" } ], "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"transaction.update","params":{"guid":"c0000000000000000000000000000007","changeSplits":[{"guid":"d000000000000000000000000000000f","value":"90.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "error": { "code": 2002, "message": "…", "data": { "imbalance": "…", "currency": "…", "help": "error/unbalanced" } } } ``` ## Related - [transaction.post](method/transaction.post) - [transaction.update](method/transaction.update) - [transaction.get](method/transaction.get) - [unbalanced](error/unbalanced) --- *red-ale Manual, `guide/split-transactions`. Adapted from GnuCash's documentation, `guide/ch_expenses.docbook#expenses-entering`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Stock splits and mergers Record a stock split with stock.split, which adds shares at no cost; record a merger by hand with ordinary transactions. A **stock split** gives you more shares for the ones you have, without changing what the holding is worth: two-for-one doubles your shares and halves each one's price. The cost of the holding stays the same. A **merger** or takeover exchanges your shares of one company for shares of another, or for cash. ## Stock split 1. Work out how many shares you *gain*. A two-for-one split of 90 shares gives 90 more; the `shares` you pass is the increase, and a negative number records a reverse split. 2. Call [stock.split](method/stock.split) with the share `account`, the `date` and `shares`. Add `price` (the new price per share) if you want it recorded in the price database. It posts a transaction that adds shares with a value of zero, so no cash moves and the cost basis is unchanged. 3. Check the new share count with [account.balance](method/account.balance). If a different price is already stored for that day, `blockingPrice` shows it and the new price is not stored. ## Merger There is no merger method. Record one as ordinary transactions, which keeps your records easy to follow: 1. In the old share account, post a transaction that takes out the old shares at their cost: old shares `-` (value the cost, `amount` the old share count). 2. In a new share account for the new company, bring in the new shares with the same total value: new shares `+` (value the cost, `amount` the new shares). 3. If you also received cash, add a cash split, and put any gain in an income account, as in [Buy and sell shares](guide/buy-and-sell-shares). 4. Add the new company's price with [price.add](method/price.add). ## Example *Example: with a copy of the `reports/investment-lots` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"stock.split","params":{"account":"Root:Assets:Broker:AAPL","date":"2021-01-01","shares":"90","price":"55.00"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "transaction": "…", "priceStatus": "added", "price": "…", "blockingPrice": null } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.balance","params":{"account":"Root:Assets:Broker:AAPL"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "balances": { "commodity": "NASDAQ::AAPL", "balance": { "num": "180", "denom": "1" }, "…": "…" }, "…": "…" } } ``` ## Related - [stock.split](method/stock.split) - [transaction.post](method/transaction.post) - [account.balance](method/account.balance) - [price.add](method/price.add) - [Buy and sell shares](guide/buy-and-sell-shares) --- *red-ale Manual, `guide/stock-splits-and-mergers`. Adapted from GnuCash's documentation, `guide/ch_invest.docbook#invest-splitsnmergers1`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Track a loan Record a loan you owe (a car loan or mortgage) with a liability account, the asset it bought and an interest expense; split each payment into principal and interest. A loan is money you owe, so the books carry it as a liability. When you borrow to buy something, the loan and the thing you bought both appear: the liability grows and an asset grows by the same amount. Each repayment then has two parts. The *principal* reduces what you owe. The *interest* is the lender's charge and is an expense; it does not reduce the debt. The same layout serves a mortgage, a car loan, and a loan you make to a friend, with the roles reversed for the last: what the friend owes you is an asset, and the interest you receive is income. ## Steps 1. **Create the accounts** ([Set up accounts](guide/set-up-accounts)): the asset you bought (`ASSET`), the loan (`LIABILITY`), the interest expense (`EXPENSE`), and the bank account you repay from. 2. **Record the purchase.** The asset `+`, the loan `-`, both for the amount borrowed. If you also put down a deposit, a third split takes it from the bank account. 3. **Record each repayment** with [transaction.post](method/transaction.post) as one transaction with three splits: the loan `+` (principal), the interest expense `+`, and the bank account `-` (the full payment). The lender's statement gives the split between principal and interest. 4. **Check** the amount you still owe with [account.balance](method/account.balance) on the loan account. It is negative, because it is a credit balance. 5. **Reconcile** the loan account against each statement ([Reconcile an account](guide/reconcile-an-account)). 6. **Do not type every payment by hand?** [scheduledTransaction.loan](method/scheduledTransaction.loan) builds a scheduled transaction whose formulas compute the principal and interest of each payment; see [Schedule a transaction](guide/schedule-a-transaction). 7. **When you sell the asset**, record the sale as a deposit from the buyer and a withdrawal from the asset account, with any gain or loss in an income or expense account. Repay the loan with a payment of the remaining balance. ## Example A 20,000.00 car loan, and the first repayment of 450.00 (380.00 principal, 70.00 interest). *Example: with a new, empty book open as `book.gnucash`, at 2024-07-31T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Car","type":"ASSET","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"account.create","params":{"name":"Car loan","type":"LIABILITY","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"account.create","params":{"name":"Loan interest","type":"EXPENSE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"transaction.post","params":{"datePosted":"2024-07-01","description":"Buy car","splits":[{"account":"Car","value":"20000.00"},{"account":"Car loan","value":"-20000.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": { "balanced": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":6,"method":"transaction.post","params":{"datePosted":"2024-07-31","description":"Loan payment 1","splits":[{"account":"Car loan","value":"380.00"},{"account":"Loan interest","value":"70.00"},{"account":"Checking","value":"-450.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 6, "result": { "balanced": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":7,"method":"account.balance","params":{"account":"Car loan"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 7, "result": { "balances": { "commodity": "CURRENCY::USD", "balance": { "num": "-1962000", "denom": "100" }, "…": "…" }, "…": "…" } } ``` ## Related - [account.create](method/account.create) - [transaction.post](method/transaction.post) - [account.balance](method/account.balance) - [scheduledTransaction.loan](method/scheduledTransaction.loan) - [reconcile.start](method/reconcile.start) - [Loans and interest](concept/loans-and-interest) --- *red-ale Manual, `guide/track-a-loan`. Adapted from GnuCash's documentation, `guide/ch_loans.docbook#chapter_loans`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Transfer between accounts Move an amount from one account to another with transaction.transfer, including a transfer between accounts in different currencies at an exchange rate. Moving money between two of your own accounts (bank to savings, bank to cash, one currency to another) is the most common transaction, and [transaction.transfer](method/transaction.transfer) does it in one call. It is GnuCash's Transfer dialog: you name the two accounts and an amount, and red-ale builds the two splits. ## Steps 1. **Pick the accounts.** `from` is the account the amount leaves; it must hold a currency. `to` is the account it reaches. 2. **Give the amount**, in the `from` account's currency, as an exact string. Add `date`, `description`, `num`, `notes` or `memo` as needed. 3. **Same currency?** That is all. The transaction has two splits of the same value. 4. **Different currencies?** Give the `rate`: units of the `to` commodity per unit of the `from` currency. The `from` account loses 100.00 USD and the `to` account, in GBP, gains 80.00 at a rate of `0.80`. Or give `toAmount`, the amount received, and the rate is worked out from it. Giving both is refused if they disagree. 5. **The price is remembered.** Unless you pass `recordPrice: false`, the rate is added to the price database, as the dialog does, so reports can convert later. See [Multiple currencies](guide/multiple-currencies). 6. **Check** with [account.balance](method/account.balance). For anything the Transfer dialog cannot express, such as a transfer with a fee, use [transaction.post](method/transaction.post) with all the splits. ## Example *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"transaction.transfer","params":{"from":"Root:Asset:Bank","to":"Root:Asset:Wallet","amount":"40.00","date":"2024-06-09","description":"Cash for the weekend"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "transaction": { "description": "Cash for the weekend", "balanced": true, "…": "…" }, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"transaction.transfer","params":{"from":"Root:Asset:Bank","to":"Root:Asset:GBP Bank","amount":"100.00","date":"2024-06-10","description":"Top up","rate":"0.80"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "transaction": { "currency": "CURRENCY::USD", "description": "Top up", "splits": [ { "accountName": "Root:Asset:GBP Bank", "value": { "num": "10000", "denom": "100" }, "amount": { "num": "8000", "denom": "100" }, "…": "…" }, { "accountName": "Root:Asset:Bank", "value": { "num": "-10000", "denom": "100" }, "…": "…" } ], "…": "…" }, "…": "…" } } ``` ## Related - [transaction.transfer](method/transaction.transfer) - [transaction.post](method/transaction.post) - [price.add](method/price.add) - [account.balance](method/account.balance) - [Transaction menu and the register](gnucash/transaction-menu) --- *red-ale Manual, `guide/transfer-between-accounts`. Adapted from GnuCash's documentation, `manual/ch_Transactions.docbook#trans-win-enter`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Use trading accounts Turn on the Use Trading Accounts book option so every transaction that mixes currencies balances in each currency, and see the Trading accounts it creates. A transaction in two currencies balances in *value*, but each currency taken alone does not: you gave up 108.50 dollars and received 100.00 euros. Trading accounts fix that. With the option on, red-ale adds balancing splits to a hidden tree of `TRADING` accounts (`Trading:CURRENCY:USD`, `Trading:CURRENCY:EUR`), so that the splits in each currency sum to zero on their own. The Trading account for each currency then shows how much of it you have bought or sold, which is what accountants use to find a currency gain or loss. It is a book option, so it is stored in the book and GnuCash honours it when it opens the file. ## Steps 1. **Turn it on** with [book.setOptions](method/book.setOptions) and `useTradingAccounts: true`. No existing transaction changes; only transactions you post or edit afterwards get trading splits. [book.options](method/book.options) shows the current setting. 2. **Post as usual** with [transaction.post](method/transaction.post). Give the transaction's `currency`, and an `amount` on each split whose account is in another commodity (see [Multiple currencies](guide/multiple-currencies)). red-ale adds the trading splits itself. 3. **Look at the result.** The transaction has two more splits than you sent. [account.list](method/account.list) now includes the `Trading` accounts, which are placeholders: do not post to them yourself. Turning the option off stops new trading splits from being added, but keeps the ones already there. ## Example *Example: with a new, empty book open as `book.gnucash`, at 2024-07-15T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"book.setOptions","params":{"useTradingAccounts":true}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "useTradingAccounts": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"account.create","params":{"name":"Euro Bank","type":"BANK","commodity":"EUR"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"transaction.post","params":{"datePosted":"2024-07-02","description":"Buy euros","currency":"USD","splits":[{"account":"Euro Bank","value":"108.50","amount":"100.00"},{"account":"Checking","value":"-108.50"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "balanced": true, "splits": [ { "accountName": "Euro Bank", "…": "…" }, { "accountName": "Trading:CURRENCY:USD", "…": "…" }, { "accountName": "Checking", "…": "…" }, { "accountName": "Trading:CURRENCY:EUR", "value": { "num": "-10850", "denom": "100" }, "amount": { "num": "-10000", "denom": "100" }, "…": "…" } ], "…": "…" } } ``` ## Related - [book.setOptions](method/book.setOptions) - [book.options](method/book.options) - [transaction.post](method/transaction.post) - [account.list](method/account.list) - [Multiple currencies](guide/multiple-currencies) - [Trading accounts](concept/trading-accounts) --- *red-ale Manual, `guide/use-trading-accounts`. Adapted from GnuCash's documentation, `guide/ch_currency.docbook#currency_trading_accts`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Write your own report Write a User report as a .rhai script in the report directory, check that report.list shows it, then run it with report.run and export it with report.export. GnuCash comes with reports of its own, and red-ale has translated most of them. Others, such as GnuCash's business reports and the sample reports you may have written for it, are left for you to write. A **User report** is a Rhai script, a file ending in `.rhai` in the **report directory**. red-ale loads it each time a report method runs, lists it beside the built-in reports, and runs it in a sandbox: it can read the open book but cannot change it, read other files, reach the network or ask the clock. You can write one yourself, or ask an AI agent to. Either way the steps are the same, and the script is an ordinary text file. There is no method that takes a script's text, so the file must be put in the report directory by something that can write files on the machine where red-ale runs: you, your editor, or an agent with file access. ## Steps 1. **Choose the report directory** and tell red-ale where it is, with [config.set](method/config.set): `{"changes": {"reports.directory": "/home/me/red-ale-reports"}}`. [config.get](method/config.get) with the path `reports.directory` reads it back. Scripts may be in sub-directories; at most 1,000 files of at most 1 MiB are read. 2. **Write the script.** Save the one below as `asset-balances.rhai` in that directory. A script defines three functions: `templates()` names the reports it provides, `options()` declares the options a user can set, and `render()` builds the report from the book. 3. **Check that it loaded.** Call [report.list](method/report.list). The new report is in `reports` with `"kind": "user"` and its script's path. If the script has a mistake, it is not listed; instead `problems` names the file, line and column and says what is wrong ([report-load](error/report-load)). 4. **Run it** with [report.run](method/report.run), by name. You get the report result as data, with exact figures. A fault at run time is a [report-script](error/report-script) error with the line and column. Edit the file and run it again: there is nothing to restart. 5. **Export it** with [report.export](method/report.export) for a page you can read or print. 6. **Share the options.** An option you declare shows up in [report.options](method/report.options) and can be set in `options`, like those of the built-in reports. Save a favourite set with `report.saveConfiguration` ([Run and export a report](guide/run-and-export-a-report)). ## A minimal script This report lists every asset account that can hold transactions, with its balance now: ```rhai // Asset Balances: every asset account that can hold transactions, with its balance now. fn templates() { [#{ guid: "5a1e0c9d2b7a4e3f8a5b1c2d3e4f5a6b", name: "Asset Balances", menuPath: ["_Custom"] }] } fn options(params, o, book) { o.string("General", "Report Title", "a", "Title for this report.", "Asset Balances"); } fn render(params, book, opts, ctx) { let rows = book.accounts() .filter(|a| a.type == "ASSET" && !a.placeholder) .map(|a| #{ cells: [#{ text: a.fullName }, #{ number: a.balance_as_of(ctx.now), places: 2 }] }); #{ title: opts.get("General", "Report Title"), sections: [#{ blocks: [#{ kind: "table", columns: [#{ label: "Account", role: "label" }, #{ label: "Balance", role: "amount" }], rows: rows }] }] } } ``` - The `guid` is any 32 lowercase hex digits you make up, and it must be unique among the reports. Keep it when you edit the script, so saved configurations still find it. - `book.accounts()` returns the book's accounts. `a.balance_as_of(ctx.now)` is an exact rational, and the `number` cell shows it to two places. Money is never a floating-point number in a script. - `render()` returns a map of the report result: a `title` and `sections` of `blocks` (tables, text, charts). Running it on a book whose `ASSET` account `Root:Asset:Bank` holds 2,186.00 gives a table whose rows look like this (shown, not run, since an Example cannot put a file in the directory): ```json {"role": "data", "cells": [{"text": "Root:Asset:Bank"}, {"number": {"num": "2186", "denom": "1"}, "places": 2, "display": "2,186.00"}]} ``` The engine's whole interface, with the reads a script can make, the option types, the arithmetic and the limits, is on the Report scripts concept page. The built-in reports are written the same way and are worked examples. ## Example A directory that does not exist yet is reported under `problems`. Setting the directory and listing the reports works on any book. A script in the directory would appear in this list: `"kind": "builtin"` marks the reports that come with red-ale, and a User report has `"kind": "user"`. *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`, at 2024-03-15T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"config.set","params":{"changes":{"reports.directory":"reports"}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "values": { "reports.directory": "reports" }, "clearedKeys": [], "configFile": null } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"report.list","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "reports": [ { "name": "Account Summary", "kind": "builtin", "…": "…" }, "…" ], "problems": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"report.run","params":{"report":"Account Summary"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "title": "…", "report": { "name": "Account Summary", "…": "…" }, "sections": "…", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"report.export","params":{"report":"Account Summary"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "title": "…", "html": "…" } } ``` ## Related - [config.set](method/config.set) - [config.get](method/config.get) - [report.list](method/report.list) - [report.run](method/report.run) - [report.export](method/report.export) - [report.options](method/report.options) - [report-script](error/report-script) - [report-load](error/report-load) - [Report scripts](concept/report-scripts) - [Reports menu and the report window](gnucash/reports-menu) --- *red-ale Manual, `guide/write-your-own-report`. Adapted from GnuCash's documentation, `guide/ch_reports.docbook#rpt_grp_sampcust`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # GNU Free Documentation License The licence of the Manual's text: the GNU Free Documentation License, version 1.1. ```text GNU Free Documentation License Version 1.1, March 2000 Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITY If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five). C. State on the Title page the name of the publisher of the Modified Version, as the publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. H. Include an unaltered copy of this License. I. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K. In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. M. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version. N. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. 5. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements." 6. COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. 7. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate. 8. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail. 9. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 10. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. ADDENDUM: How to use this License for your documents To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page: Copyright (c) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled "GNU Free Documentation License". If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being LIST"; likewise for Back-Cover Texts. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software. ``` ## Related - [Copyright and licence notices](legal/notices) --- *red-ale Manual, `legal/gfdl`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # History The releases of the red-ale Manual, and the documents it draws on. The History section the GNU Free Documentation License asks a Modified Version to keep: an item for each release of the red-ale Manual, and, for each document it adapts text from, that document's title, year, authors and publisher and where its source is published. ## Releases - **red-ale 0.6.0**: the first release of the Manual, served through `help.*`, MCP, the CLI and the website. ## Documents drawn on Both are published by the GnuCash Documentation Team at (directories `C/guide` and `C/manual`) and are used at the tag 5.17, commit `6627658b6b47bef1e4e89afe2e2cb3af9db938cd`. The Pages that adapt them name the section in `from`; `design/gnucash-docs-checklist.md` lists every section and the Pages it went to. - **GnuCash Tutorial and Concepts Guide**, "The Didactical Documentation", release 5.17, 27 September 2026. Copyright 2001-2026. Publisher: The GnuCash Documentation Team. Principal authors, as the book names them: the GnuCash Documentation Team, Yawar Amin, Tom Bullock, Cristian Marchi, Chris Lyttle, Jon Lapham, and Carol Champagne. - **GnuCash Help Manual**, release 5.17, 27 September 2026. Copyright 2002-2026. Publisher: The GnuCash Documentation Team. Author, as the book names it: the GnuCash Documentation Team. Each release of both books lists its authors as "Multiple authors" and its publisher as the GnuCash Documentation Team. ## Related - [Copyright and licence notices](legal/notices) - [GNU Free Documentation License](legal/gfdl) --- *red-ale Manual, `legal/history`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # Copyright and licence notices Who holds the copyright in the red-ale Manual, and the licence it is under. ## The red-ale Manual Copyright © 2026 the red-ale contributors. ## Documents this Manual adapts Pages that adapt text from GnuCash's documentation name the section in their `from` field. Both books are by the GnuCash Documentation Team, published at and used here at release 5.17. **GnuCash Tutorial and Concepts Guide** (the Guide) - Copyright © 2009-2026 GnuCash Documentation Team - Copyright © 2010-2011 Yawar Amin - Copyright © 2010 Tom Bullock - Copyright © 2010-2011 Cristian Marchi - Copyright © 2006 Chris Lyttle - Copyright © 2003-2004 Jon Lapham - Copyright © 2002 Chris Lyttle - Copyright © 2001 Carol Champagne and Chris Lyttle **GnuCash Help Manual** (the Manual) - Copyright © 2002-2026 GnuCash Documentation Team The Pages of this Manual that adapt text from these books are changed from them: they describe red-ale, which is driven by methods, not windows. The authors of the books did not write or endorse this Manual. ## Licence Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation, with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A copy of the licence is the Page [GNU Free Documentation License](legal/gfdl), and the file `docs/COPYING-DOCS` of red-ale's source. The GnuCash books carry the same licence, with the further understanding that the document is provided as it is, without warranty, and that no author or contributor is liable for any damage that comes of using it. That notice goes with every Modified Version, and so with this Manual: the document and modified versions of the document are provided under the terms of the GNU Free Documentation License with the further understanding that: 1. The document is provided on an "as is" basis, without warranty of any kind, either expressed or implied, including, without limitation, warranties that the document or modified version of the document is free of defects, merchantable, fit for a particular purpose or non-infringing. The entire risk as to the quality, accuracy and performance of the document or modified version of the document is with you. Should any document or modified version prove defective in any respect, you (not the initial writer, author or any contributor) assume the cost of any necessary servicing, repair or correction. This disclaimer of warranty constitutes an essential part of this licence. No use of any document or modified version of the document is authorised hereunder except under this disclaimer. 2. Under no circumstances and under no legal theory, whether in tort (including negligence), contract or otherwise, shall the author, initial writer, any contributor, or any distributor of the document or modified version of the document, or any supplier of any of such parties, be liable to any person for any direct, indirect, special, incidental or consequential damages of any character including, without limitation, damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other damages or losses arising out of or relating to use of the document and modified versions of the document, even if such party shall have been informed of the possibility of such damages. Many of the names companies use to distinguish their products and services are claimed as trademarks. Where such names appear in this Manual, they belong to their owners. The Manual's text is the Markdown in `docs/` of red-ale's source and everything built from it. red-ale's code, including the code that builds and serves the Manual, is licensed separately, under the GNU General Public License, version 3 or later; the binary carries the two side by side. ## Related - [GNU Free Documentation License](legal/gfdl) - [History](legal/history) --- *red-ale Manual, `legal/notices`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # account.balance An account's balance, cleared and reconciled balances, optionally as of a date and with sub-accounts. Gives an account's balance, with its cleared and reconciled balances, in the account's commodity: today's, or as of a date with `asOf`, and with its sub-accounts' balances added when `includeSubaccounts` is true. Balances use the account's raw sign, debits positive and credits negative, so an income account's balance is usually negative. ## Examples *Example: with a new, empty book open as `book.gnucash`, at 2024-07-15T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Salary","type":"INCOME","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"transaction.post","params":{"datePosted":"2024-07-01","description":"Pay","splits":[{"account":"Checking","value":"2500.00"},{"account":"Salary","value":"-2500.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"account.balance","params":{"account":"Checking"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "account": "…", "includesSubaccounts": false, "balances": { "commodity": "CURRENCY::USD", "balance": { "num": "250000", "denom": "100" }, "cleared": { "num": "0", "denom": "1" }, "reconciled": { "num": "0", "denom": "1" } }, "unconverted": [], "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"account.balance","params":{"account":"Salary"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": { "balances": { "commodity": "CURRENCY::USD", "balance": { "num": "-250000", "denom": "100" }, "…": "…" }, "…": "…" } } ``` **Effect:** `read`. ## Params Params of `account.balance`. - `account` (AccountRef, required): The account. - `asOf` (Date or null): Balances at the end of this day (transactions posted before 23:59:59 local time); by default every transaction. - `includeSubaccounts` (boolean): Add the sub-accounts' balances. ## Result The result of `account.balance`. - `account` (Guid, required): The account. - `asOf` (Date or null): The date, if one was given. - `includesSubaccounts` (boolean, required): Sub-accounts are included. - `balances` (CommodityBalances or null): The balances, in the account's commodity (amounts, not values). - `unconverted` (array of CommodityBalances, required): Sub-accounts in other commodities, summed by commodity and not converted (GnuCash converts them at the latest price; red-ale v0.1 leaves that to the caller). ## Related - [transaction.post](method/transaction.post) - [account.create](method/account.create) --- *red-ale Manual, `method/account.balance`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # account.cascade Set colour, placeholder or hidden on an account and all its sub-accounts. Sets the colour, the placeholder flag or the hidden flag on an account and all its sub-accounts at once, as the account tree's "cascade" action does, and returns the GUIDs of the accounts that changed. A colour is `#rgb`, `#rrggbb` or `rgb(r,g,b)`; it is stored as `rgb(r,g,b)`. By default sub-accounts that already have a colour keep it; pass `replaceColors: true` to overwrite them. The account must have sub-accounts (`invalid` otherwise). ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.cascade","params":{"account":"Root:Asset","color":"#336699","hidden":false}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "changed": [ "…", "…", "…", "…" ] } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.get","params":{"account":"Root:Asset:Bank"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "color": "rgb(51,102,153)", "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `account.cascade`. - `account` (AccountRef, required): The account; it must have sub-accounts. - `color` (string or null): Cascade this colour (`#rrggbb`, `#rgb` or `rgb(r,g,b)`); empty cascades no colour. - `replaceColors` (boolean): Replace colours already set (GnuCash's "Replace any existing account colors"); without it only accounts with no colour change. - `placeholder` (boolean or null): Cascade the placeholder flag. - `hidden` (boolean or null): Cascade the hidden flag. ## Result The result of `account.cascade`. - `changed` (array of Guid, required): The accounts that changed: the account first, then its sub-accounts depth first. ## Related - [account.update](method/account.update) --- *red-ale Manual, `method/account.cascade`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # account.checkBalanceLimit Compare an account's balance with its balance limits, as GnuCash's account tree does to warn. Compares an account's balance with its higher and lower balance limits, as GnuCash's account tree does to show a warning icon. `state` is `above`, `below`, `shouldBeZero` or null when no limit is crossed. The balance is at the end of `asOf` (default today); with `includeSubaccountBalances` set on the account, sub-accounts are converted at their latest price, and the ones without a price are listed in `unconverted` and counted as zero. Set limits with [account.update](method/account.update) (`higherBalanceLimit`, `lowerBalanceLimit`). ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`, at 2024-07-01T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.update","params":{"account":"Root:Asset:Bank","higherBalanceLimit":"1000.00"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.checkBalanceLimit","params":{"account":"Root:Asset:Bank"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "asOf": "2024-07-01", "balance": { "num": "218600", "denom": "100" }, "higherLimit": { "num": "100000", "denom": "100" }, "lowerLimit": null, "state": "above", "…": "…" } } ``` **Effect:** `read`. ## Params Params of `account.checkBalanceLimit`. - `account` (AccountRef, required): The account. - `asOf` (Date or null): The balance at the end of this day, local time; by default today, as GnuCash checks it. ## Result The result of `account.checkBalanceLimit`. - `account` (Guid, required): The account. - `asOf` (Date, required): The day the balance is taken at the end of. - `balance` (Amount, required): The balance compared, in raw sign, with sub-accounts when the account's flag is set: those in other commodities converted at the latest price and rounded to the account commodity's fraction. - `higherLimit` (Amount or null): The higher limit, if set. - `lowerLimit` (Amount or null): The lower limit, if set. - `includesSubaccounts` (boolean, required): Sub-accounts are included. - `state` (LimitStateWire or null): The limit crossed: `above`, `below`, `shouldBeZero`; null when none is. - `unconverted` (array of Unconverted, required): Sub-accounts in other commodities that no price converts, by commodity; they add nothing to `balance`. ## Related - [account.update](method/account.update) - [account.balance](method/account.balance) --- *red-ale Manual, `method/account.checkBalanceLimit`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # account.create Create an account under a parent (the root by default). Adds an account to the open book, under the root or under the `parent` you name, as GnuCash's New Account dialog does. Give it a `name`, a `type` (`BANK`, `CASH`, `ASSET`, `CREDIT`, `LIABILITY`, `STOCK`, `MUTUAL`, `INCOME`, `EXPENSE`, `EQUITY`, …) and the `commodity` its amounts are in; a currency can be named by its code alone (`USD`). Accounts are then named by their full name, levels joined with `:`, or by the GUID this method returns. ## Examples A bank account under a new top-level asset account: *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Assets","type":"ASSET","commodity":"USD","placeholder":true}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "…", "name": "Assets", "fullName": "Assets", "placeholder": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Checking","type":"BANK","parent":"Assets","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "guid": "…", "name": "Checking", "fullName": "Assets:Checking", "type": "BANK", "parent": "…", "commodity": "CURRENCY::USD", "scu": 100, "depth": 2, "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `account.create`. - `name` (string, required): Name: not empty, without `:`, and unlike its siblings'. - `type` (string, required): Account type (see `account.types`); it must suit the parent's. - `parent` (AccountRef or null): Parent; the root by default. - `commodity` (CommodityId or null): Commodity: a currency for most types, a security for STOCK and MUTUAL. On create, defaults to the parent's when it suits the type. Cannot change once the account has splits. - `scu` (ScuParam or null): Smallest fraction. - `code` (string or null): Account code; empty clears it. - `description` (string or null): Description; empty clears it. - `notes` (string or null): Notes; empty clears them. - `placeholder` (boolean or null): Placeholder flag. - `hidden` (boolean or null): Hidden flag. - `taxRelated` (boolean or null): Tax-related flag. - `taxUsCode` (string or null): US TXF code; empty clears it. - `taxUsPayerNameSource` (string or null): US TXF payer name source (`current` or `parent`); empty clears it. - `taxUsCopyNumber` (integer (int64) or null): US TXF copy number; 0 clears it. - `color` (string or null): Account colour: `#rrggbb`, `#rgb` or `rgb(r,g,b)`, stored as `rgb(r,g,b)`; empty (or GnuCash's default `rgb(237,236,235)`) clears it. - `higherBalanceLimit` (Amount or null): Higher balance limit, in raw sign; null clears it. - `lowerBalanceLimit` (Amount or null): Lower balance limit, in raw sign; null clears it. - `includeSubaccountBalances` (boolean or null): Apply the balance limits to the balance with sub-accounts. Cleared when no limit is left. - `openingBalance` (boolean or null): Hold the opening balances of the account's commodity (EQUITY only; one per commodity; not once it has splits). Setting it declares GnuCash's opening balance account Book feature. - `associatedAccounts` (map of AccountRef or null or null): Associated accounts by tag; null removes a tag, tags not named are kept. ## Result An account. - `guid` (Guid, required): GUID. - `name` (string, required): Name. - `fullName` (string, required): Full name: ancestors' names joined by `:`, without the root. - `type` (string, required): Account type, as GnuCash writes it. - `parent` (Guid or null): Parent; none only for the root. - `commodity` (CommodityId or null): Commodity held. - `scu` (integer (int64), required): Smallest fraction the account's amounts are kept in. - `nonStandardScu` (boolean, required): The smallest fraction was chosen instead of the commodity's. - `code` (string or null): Account code. - `description` (string or null): Description. - `notes` (string or null): Notes. - `placeholder` (boolean, required): Groups other accounts; GnuCash's register refuses splits in it. - `hidden` (boolean, required): Hidden itself. - `hiddenInTree` (boolean, required): Hidden itself or through an ancestor, as GnuCash shows it. - `taxRelated` (boolean, required): Tax-related. - `taxUs` (TaxUs, required): US tax (TXF) settings. - `depth` (integer (uint), required): Levels below the root (top-level accounts are 1). - `children` (integer (uint), required): Number of immediate sub-accounts. - `hasSplits` (boolean, required): The account has splits. - `color` (string or null): Account colour (`rgb(r,g,b)` as GnuCash's dialog writes it, or as stored); null when unset or `Not Set`. - `higherBalanceLimit` (Amount or null): Higher balance limit, in raw sign (debits positive). - `lowerBalanceLimit` (Amount or null): Lower balance limit, in raw sign. - `includeSubaccountBalances` (boolean, required): The balance limits apply to the balance with sub-accounts. - `openingBalance` (boolean, required): The EQUITY account holding the opening balances of its commodity. - `associatedAccounts` (map of Guid, required): Associated accounts by tag (such as `stock-dividends`), each naming an existing account. ## Related - [transaction.post](method/transaction.post) - [account.balance](method/account.balance) --- *red-ale Manual, `method/account.create`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # 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": }`; 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`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.delete","params":{"account":"Root:Asset:Wallet"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": 2001, "message": "…", "data": { "help": "error/invalid" } } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.delete","params":{"account":"Root:Asset:Wallet","transactions":{"moveTo":"Root:Asset:Bank"}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "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. ## Related - [account.move](method/account.move) - [transaction.delete](method/transaction.delete) - [invalid](error/invalid) - [conflict](error/conflict) --- *red-ale Manual, `method/account.delete`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # account.get Describe one account. Describes one account: its type, commodity, smallest fraction (`scu`), code, flags, colour, balance limits, whether it has splits and how many sub-accounts it has. Name the account by its full name (`Assets:Checking`, levels joined with `:`, the root left out) or by GUID. An unknown name is [not-found](error/not-found); names are case-sensitive. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.get","params":{"account":"Root:Asset:Bank"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "name": "Bank", "fullName": "Root:Asset:Bank", "type": "ASSET", "commodity": "CURRENCY::USD", "scu": 100, "placeholder": false, "hasSplits": true, "children": 0, "…": "…" } } ``` **Effect:** `read`. ## Params Params naming one account. - `account` (AccountRef, required): The account. ## Result An account. - `guid` (Guid, required): GUID. - `name` (string, required): Name. - `fullName` (string, required): Full name: ancestors' names joined by `:`, without the root. - `type` (string, required): Account type, as GnuCash writes it. - `parent` (Guid or null): Parent; none only for the root. - `commodity` (CommodityId or null): Commodity held. - `scu` (integer (int64), required): Smallest fraction the account's amounts are kept in. - `nonStandardScu` (boolean, required): The smallest fraction was chosen instead of the commodity's. - `code` (string or null): Account code. - `description` (string or null): Description. - `notes` (string or null): Notes. - `placeholder` (boolean, required): Groups other accounts; GnuCash's register refuses splits in it. - `hidden` (boolean, required): Hidden itself. - `hiddenInTree` (boolean, required): Hidden itself or through an ancestor, as GnuCash shows it. - `taxRelated` (boolean, required): Tax-related. - `taxUs` (TaxUs, required): US tax (TXF) settings. - `depth` (integer (uint), required): Levels below the root (top-level accounts are 1). - `children` (integer (uint), required): Number of immediate sub-accounts. - `hasSplits` (boolean, required): The account has splits. - `color` (string or null): Account colour (`rgb(r,g,b)` as GnuCash's dialog writes it, or as stored); null when unset or `Not Set`. - `higherBalanceLimit` (Amount or null): Higher balance limit, in raw sign (debits positive). - `lowerBalanceLimit` (Amount or null): Lower balance limit, in raw sign. - `includeSubaccountBalances` (boolean, required): The balance limits apply to the balance with sub-accounts. - `openingBalance` (boolean, required): The EQUITY account holding the opening balances of its commodity. - `associatedAccounts` (map of Guid, required): Associated accounts by tag (such as `stock-dividends`), each naming an existing account. ## Related - [account.list](method/account.list) - [account.update](method/account.update) - [account.balance](method/account.balance) --- *red-ale Manual, `method/account.get`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # account.list List accounts depth first in the book's order, and names that contain the separator. Lists accounts depth first, each followed by its sub-accounts, in the order GnuCash keeps and writes them. Give `under` to list one subtree (the account itself is left out) and `excludeHidden` to skip hidden accounts. Use [account.tree](method/account.tree) when you want the nesting rather than a flat list. `nameViolations` lists accounts whose names contain the separator `:`, which GnuCash warns about when it opens such a book. red-ale refuses to create one. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.list","params":{"under":"Root:Asset"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "accounts": [ { "fullName": "Root:Asset:Bank", "type": "ASSET", "…": "…" }, { "fullName": "Root:Asset:GBP Bank", "commodity": "CURRENCY::GBP", "…": "…" }, { "fullName": "Root:Asset:Wallet", "…": "…" } ], "nameViolations": [] } } ``` **Effect:** `read`. ## Params Params of `account.list`. - `under` (AccountRef or null): List only the descendants of this account; by default every account but the root. - `excludeHidden` (boolean): Leave out accounts hidden themselves or through an ancestor. ## Result The result of `account.list`. - `accounts` (array of AccountInfo, required): Accounts, depth first: each followed by its sub-accounts, siblings in the book's order. - `nameViolations` (array of Guid, required): Accounts whose names contain the separator `:`, which makes full names ambiguous (GnuCash warns about them when it opens a book). ## Related - [account.tree](method/account.tree) - [account.get](method/account.get) --- *red-ale Manual, `method/account.list`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # account.move Move an account, with its sub-accounts, under another parent. Moves an account, with its sub-accounts, under another parent as that parent's last child. The new parent's type must allow the account's type, the parent must not be inside the moved subtree, and no sibling there may have the same name. Transactions are untouched: they follow the account. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.move","params":{"account":"Root:Asset:Wallet","parent":"Root:Asset:Bank"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "name": "Wallet", "fullName": "Root:Asset:Bank:Wallet", "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `account.move`. - `account` (AccountRef, required): The account to move, with its sub-accounts. - `parent` (AccountRef, required): The new parent; it becomes the last of the parent's children. ## Result An account. - `guid` (Guid, required): GUID. - `name` (string, required): Name. - `fullName` (string, required): Full name: ancestors' names joined by `:`, without the root. - `type` (string, required): Account type, as GnuCash writes it. - `parent` (Guid or null): Parent; none only for the root. - `commodity` (CommodityId or null): Commodity held. - `scu` (integer (int64), required): Smallest fraction the account's amounts are kept in. - `nonStandardScu` (boolean, required): The smallest fraction was chosen instead of the commodity's. - `code` (string or null): Account code. - `description` (string or null): Description. - `notes` (string or null): Notes. - `placeholder` (boolean, required): Groups other accounts; GnuCash's register refuses splits in it. - `hidden` (boolean, required): Hidden itself. - `hiddenInTree` (boolean, required): Hidden itself or through an ancestor, as GnuCash shows it. - `taxRelated` (boolean, required): Tax-related. - `taxUs` (TaxUs, required): US tax (TXF) settings. - `depth` (integer (uint), required): Levels below the root (top-level accounts are 1). - `children` (integer (uint), required): Number of immediate sub-accounts. - `hasSplits` (boolean, required): The account has splits. - `color` (string or null): Account colour (`rgb(r,g,b)` as GnuCash's dialog writes it, or as stored); null when unset or `Not Set`. - `higherBalanceLimit` (Amount or null): Higher balance limit, in raw sign (debits positive). - `lowerBalanceLimit` (Amount or null): Lower balance limit, in raw sign. - `includeSubaccountBalances` (boolean, required): The balance limits apply to the balance with sub-accounts. - `openingBalance` (boolean, required): The EQUITY account holding the opening balances of its commodity. - `associatedAccounts` (map of Guid, required): Associated accounts by tag (such as `stock-dividends`), each naming an existing account. ## Related - [account.update](method/account.update) - [account.delete](method/account.delete) --- *red-ale Manual, `method/account.move`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # account.openingBalanceAccount Find the account GnuCash would put a currency's opening balances in: by its flag, then by name. Finds the account GnuCash would put a currency's opening balances in: the equity account flagged as the opening balance account for that currency, else one named like GnuCash's `Opening Balances` account. It returns `account: null` when there is none. GnuCash creates the account when it is missing; red-ale only looks, because a read never writes. To make one, create an `EQUITY` account with `openingBalance: true`. ## Examples *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.openingBalanceAccount","params":{"currency":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "account": null, "foundBy": null, "featureUsed": false } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Opening Balances","type":"EQUITY","commodity":"USD","openingBalance":true}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"account.openingBalanceAccount","params":{"currency":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "account": { "fullName": "Opening Balances", "openingBalance": true, "…": "…" }, "featureUsed": true, "…": "…" } } ``` **Effect:** `read`. ## Params Params of `account.openingBalanceAccount`. - `currency` (CommodityId, required): The currency. ## Result The result of `account.openingBalanceAccount`. - `account` (AccountInfo or null): The account; null when GnuCash would create one. - `foundBy` (FoundByWire or null): How it was found. - `featureUsed` (boolean, required): The book declares GnuCash's opening balance account Book feature. ## Related - [account.create](method/account.create) - [account.update](method/account.update) --- *red-ale Manual, `method/account.openingBalanceAccount`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # account.renumber Renumber the codes of an account's immediate sub-accounts. GnuCash's "Renumber sub-accounts": gives an account's immediate sub-accounts codes in display order, `prefix-NNN` for `interval`, twice `interval`, and so on. The prefix defaults to the account's own code, the interval to 10 and the digits to 3. Grandchildren are not touched, and nothing checks that the codes are unique. An account with no sub-accounts is refused with `invalid`. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.renumber","params":{"account":"Root:Asset","prefix":"1","interval":100}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": [ { "account": "…", "fullName": "Root:Asset:Bank", "code": "1-100" }, { "account": "…", "fullName": "Root:Asset:GBP Bank", "code": "1-200" }, { "account": "…", "fullName": "Root:Asset:Wallet", "code": "1-300" } ] } ``` **Effect:** `write`, on the Book. ## Params Params of `account.renumber`. - `account` (AccountRef, required): The account whose immediate sub-accounts are renumbered. - `prefix` (string or null): Prefix, joined to the number by `-`; by default the account's own code. Empty means none. - `interval` (integer (int64) or null): Step between codes, 1 to 10000; default 10. - `digits` (integer (int64) or null): Minimum digits, 1 to 100; default 3. Never fewer than the largest number needs. ## Result Type: array of NewCode. ## Related - [account.update](method/account.update) --- *red-ale Manual, `method/account.renumber`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # account.tree The account tree as nested nodes, in the book's order or GnuCash's display order. Gives the account tree as nested nodes, `children` inside each node, for the whole book or for the subtree under `under`. With `sorted` the siblings come in GnuCash's display order (by code, then type, then name) instead of the order the book stores them. Pitfall: GnuCash 5.17's own type order puts BANK after TRADING, and red-ale reproduces it so the two agree. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.tree","params":{"under":"Root:Asset"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "fullName": "Root:Asset", "type": "ASSET", "children": [ { "fullName": "Root:Asset:Bank", "children": [], "…": "…" }, { "fullName": "Root:Asset:GBP Bank", "…": "…" }, { "fullName": "Root:Asset:Wallet", "…": "…" } ], "…": "…" } } ``` **Effect:** `read`. ## Params Params of `account.tree`. - `under` (AccountRef or null): The top of the tree; the root by default. - `sorted` (boolean): Order siblings as GnuCash displays them (code, type, name) instead of the book's order. - `excludeHidden` (boolean): Leave out hidden accounts and everything below them. ## Result A node of the account tree. - `guid` (Guid, required): GUID. - `name` (string, required): Name. - `fullName` (string, required): Full name. - `type` (string, required): Account type. - `code` (string or null): Account code. - `commodity` (CommodityId or null): Commodity held. - `placeholder` (boolean, required): Placeholder. - `hidden` (boolean, required): Hidden itself. - `children` (array of TreeNode, required): Sub-accounts. ## Related - [account.list](method/account.list) --- *red-ale Manual, `method/account.tree`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # account.types List the account types with GnuCash's labels and rules. Lists GnuCash's account types, with each one's label, its fundamental type (asset, liability, income, expense or equity), the kind of commodity it holds, the types it can sit under (`parentTypes`) and the types it can be changed to once it has splits (`changesWithSplits`). Call it to find out what `type` values [account.create](method/account.create) accepts. A type with `choosable: false` is deprecated and cannot be chosen. `STOCK` and `MUTUAL` hold securities; the others hold a currency. Receivable and Payable accounts cannot change type once they have splits. ## Examples *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.types","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": [ { "name": "BANK", "label": "Bank", "fundamental": "ASSET", "choosable": true, "commodity": "currency", "…": "…" }, "…" ] } ``` **Effect:** `read`. ## Params Params for methods that take none. Type: NoParams. ## Result Type: array of TypeInfo. ## Related - [account.create](method/account.create) - [account.update](method/account.update) --- *red-ale Manual, `method/account.types`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # account.update Change an account's name, type, commodity, smallest fraction, code, notes, flags, tax settings, colour, balance limits, opening balance flag or associated accounts. Changes an account's name, type, commodity, smallest fraction, code, description, notes, flags (`placeholder`, `hidden`), tax settings, colour, balance limits, opening balance flag or associated accounts. A field you leave out is kept; an empty string clears a text field. GnuCash's account dialog rules apply. The commodity can change only while the account has no splits, and a type only to one in `changesWithSplits` once it has; changing a type that sub-accounts cannot sit under needs `retypeChildren: true`. A new name must not clash with a sibling's and may not contain `:`. Existing amounts are not re-rounded when `scu` changes. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.update","params":{"account":"Root:Asset:Wallet","code":"110","description":"Cash on hand"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "fullName": "Root:Asset:Wallet", "code": "110", "description": "Cash on hand", "…": "…" } } ``` The commodity of an account with transactions cannot change: *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.update","params":{"account":"Root:Asset:Bank","commodity":"EUR"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": 2003, "message": "…", "data": { "help": "error/conflict" } } } ``` **Effect:** `write`, on the Book. ## Params Params of `account.update`. - `account` (AccountRef, required): The account. - `name` (string or null): New name. - `type` (string or null): New type. With splits, only a compatible type (see `account.types`). - `retypeChildren` (boolean): Confirm that sub-accounts whose type cannot sit under the new type take the new type too. - `commodity` (CommodityId or null): Commodity: a currency for most types, a security for STOCK and MUTUAL. On create, defaults to the parent's when it suits the type. Cannot change once the account has splits. - `scu` (ScuParam or null): Smallest fraction. - `code` (string or null): Account code; empty clears it. - `description` (string or null): Description; empty clears it. - `notes` (string or null): Notes; empty clears them. - `placeholder` (boolean or null): Placeholder flag. - `hidden` (boolean or null): Hidden flag. - `taxRelated` (boolean or null): Tax-related flag. - `taxUsCode` (string or null): US TXF code; empty clears it. - `taxUsPayerNameSource` (string or null): US TXF payer name source (`current` or `parent`); empty clears it. - `taxUsCopyNumber` (integer (int64) or null): US TXF copy number; 0 clears it. - `color` (string or null): Account colour: `#rrggbb`, `#rgb` or `rgb(r,g,b)`, stored as `rgb(r,g,b)`; empty (or GnuCash's default `rgb(237,236,235)`) clears it. - `higherBalanceLimit` (Amount or null): Higher balance limit, in raw sign; null clears it. - `lowerBalanceLimit` (Amount or null): Lower balance limit, in raw sign; null clears it. - `includeSubaccountBalances` (boolean or null): Apply the balance limits to the balance with sub-accounts. Cleared when no limit is left. - `openingBalance` (boolean or null): Hold the opening balances of the account's commodity (EQUITY only; one per commodity; not once it has splits). Setting it declares GnuCash's opening balance account Book feature. - `associatedAccounts` (map of AccountRef or null or null): Associated accounts by tag; null removes a tag, tags not named are kept. ## Result An account. - `guid` (Guid, required): GUID. - `name` (string, required): Name. - `fullName` (string, required): Full name: ancestors' names joined by `:`, without the root. - `type` (string, required): Account type, as GnuCash writes it. - `parent` (Guid or null): Parent; none only for the root. - `commodity` (CommodityId or null): Commodity held. - `scu` (integer (int64), required): Smallest fraction the account's amounts are kept in. - `nonStandardScu` (boolean, required): The smallest fraction was chosen instead of the commodity's. - `code` (string or null): Account code. - `description` (string or null): Description. - `notes` (string or null): Notes. - `placeholder` (boolean, required): Groups other accounts; GnuCash's register refuses splits in it. - `hidden` (boolean, required): Hidden itself. - `hiddenInTree` (boolean, required): Hidden itself or through an ancestor, as GnuCash shows it. - `taxRelated` (boolean, required): Tax-related. - `taxUs` (TaxUs, required): US tax (TXF) settings. - `depth` (integer (uint), required): Levels below the root (top-level accounts are 1). - `children` (integer (uint), required): Number of immediate sub-accounts. - `hasSplits` (boolean, required): The account has splits. - `color` (string or null): Account colour (`rgb(r,g,b)` as GnuCash's dialog writes it, or as stored); null when unset or `Not Set`. - `higherBalanceLimit` (Amount or null): Higher balance limit, in raw sign (debits positive). - `lowerBalanceLimit` (Amount or null): Lower balance limit, in raw sign. - `includeSubaccountBalances` (boolean, required): The balance limits apply to the balance with sub-accounts. - `openingBalance` (boolean, required): The EQUITY account holding the opening balances of its commodity. - `associatedAccounts` (map of Guid, required): Associated accounts by tag (such as `stock-dividends`), each naming an existing account. ## Related - [account.get](method/account.get) - [account.move](method/account.move) - [account.types](method/account.types) - [conflict](error/conflict) --- *red-ale Manual, `method/account.update`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # billTerm.create Create a billing term (days or proximo). Creates a billing term, the rule that says when a document is due. A `days` term is due `dueDays` after posting; a `proximo` term is due on day `dueDays` of the next month, and a document posted after day `cutoff` of the month is due a month later (a cutoff of 0 or less counts back from the end of the month). `discountDays` and `discount` (a percentage) describe an early-payment discount. They are stored and shown only: red-ale does not take the discount off a payment. The discount days may not exceed the due days. red-ale also refuses values GnuCash's dialog accepts but would compute an undefined due date from: negative days, a proximo due day outside 1-31, a cutoff outside -31 to 31, a discount outside 0-100. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"billTerm.create","params":{"name":"Net14","type":"days","dueDays":14}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "…", "name": "Net14", "type": "days", "dueDays": 14, "discountDays": 0, "refcount": 0, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"billTerm.create","params":{"name":"Bad","type":"days","dueDays":10,"discountDays":20}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "error": { "code": 2001, "message": "discount days cannot be more than due days", "data": { "help": "error/invalid" } } } ``` **Effect:** `write`, on the Book. ## Params Params of `billTerm.create`. - `name` (string, required): A name no other visible billing term has. - `description` (string): Description. - `type` (BillTermTypeWire, required): Days or proximo. - `dueDays` (integer (int64)): Days: days until due. Proximo: the day of the month it is due (1-31). - `discountDays` (integer (int64)): Days: days the early-payment discount lasts. Proximo: the day of the month it ends. Stored only. - `discount` (Amount or null): Early-payment discount percentage. Stored only. - `cutoff` (integer (int64)): Proximo only: documents posted after this day of the month are due a month later; 0 or less counts back from the end of the month. ## Result A billing term. - `guid` (Guid, required): Its GUID. - `name` (string, required): Its name; frozen copies share their parent's. - `description` (string, required): Description. - `type` (BillTermTypeWire or null): Days or proximo; absent for a term whose type was never set. - `dueDays` (integer (int64), required): Days until due, or the proximo due day. - `discountDays` (integer (int64), required): Discount days, or the proximo discount day. - `discount` (Amount, required): Discount percentage. - `cutoff` (integer (int64), required): Proximo cutoff day. - `refcount` (integer (int64), required): How many customers, vendors and documents use it (always 0 for a frozen copy). - `invisible` (boolean, required): True for frozen copies. - `parent` (Guid or null): The term it is a frozen copy of. - `child` (Guid or null): Its current frozen copy. ## Related - [billTerm.update](method/billTerm.update) - [billTerm.list](method/billTerm.list) - [invoice.dueDate](method/invoice.dueDate) --- *red-ale Manual, `method/billTerm.create`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # billTerm.delete Delete a billing term nothing uses. Deletes a visible billing term that nothing uses. One that a customer, vendor or document refers to is refused with `conflict`. Frozen copies stay in the book. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"billTerm.delete","params":{"billTerm":"Net30"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": 2003, "message": "billing term \"Net30\" is in use and cannot be deleted", "data": { "help": "error/conflict" } } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"billTerm.create","params":{"name":"Net14","type":"days","dueDays":14}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"billTerm.delete","params":{"billTerm":"Net14"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": {} } ``` **Effect:** `destructive`, on the Book. ## Params Names one billing term. - `billTerm` (BillTermRef, required): The billing term. ## Result A result with nothing to report. Type: Done. ## Related - [billTerm.list](method/billTerm.list) - [billTerm.get](method/billTerm.get) --- *red-ale Manual, `method/billTerm.delete`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # billTerm.get A billing term, with its family links. Returns one billing term, by GUID or by the name of a visible one. `refcount` counts the customers, vendors and documents using it; `parent` and `child` link it to its frozen copy (see [billTerm.list](method/billTerm.list)). ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"billTerm.get","params":{"billTerm":"Prox15"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "name": "Prox15", "type": "proximo", "dueDays": 15, "cutoff": 25, "…": "…" } } ``` **Effect:** `read`. ## Params Names one billing term. - `billTerm` (BillTermRef, required): The billing term. ## Result A billing term. - `guid` (Guid, required): Its GUID. - `name` (string, required): Its name; frozen copies share their parent's. - `description` (string, required): Description. - `type` (BillTermTypeWire or null): Days or proximo; absent for a term whose type was never set. - `dueDays` (integer (int64), required): Days until due, or the proximo due day. - `discountDays` (integer (int64), required): Discount days, or the proximo discount day. - `discount` (Amount, required): Discount percentage. - `cutoff` (integer (int64), required): Proximo cutoff day. - `refcount` (integer (int64), required): How many customers, vendors and documents use it (always 0 for a frozen copy). - `invisible` (boolean, required): True for frozen copies. - `parent` (Guid or null): The term it is a frozen copy of. - `child` (Guid or null): Its current frozen copy. ## Related - [billTerm.list](method/billTerm.list) - [billTerm.update](method/billTerm.update) --- *red-ale Manual, `method/billTerm.get`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # billTerm.list Billing terms; frozen copies made by posting only on request. Lists the visible billing terms, by name. Posting a document freezes a copy of its term, so that editing the term later leaves posted documents alone. These copies are invisible and are listed only with `includeFrozen`. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"billTerm.list","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "billTerms": [ { "name": "Net30", "type": "days", "dueDays": 30, "…": "…" }, { "name": "Prox15", "type": "proximo", "…": "…" } ] } } ``` **Effect:** `read`. ## Params Params of the lists of tax tables and billing terms. - `includeFrozen` (boolean): Include the invisible frozen copies posting makes. ## Result Billing terms. - `billTerms` (array of BillTermInfo, required): Sorted by name, then description, then GUID, as GnuCash lists them. ## Related - [billTerm.get](method/billTerm.get) - [billTerm.create](method/billTerm.create) --- *red-ale Manual, `method/billTerm.list`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # billTerm.update Change a billing term. Changes a billing term. It merges: changing only `dueDays` keeps the type and the other fields. Any change drops the cached frozen copy, so documents posted afterwards freeze the new rule; documents already posted keep the old one. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"billTerm.update","params":{"billTerm":"Net30","dueDays":45}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "name": "Net30", "type": "days", "dueDays": 45, "discountDays": 10, "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `billTerm.update`: the fields to change. - `billTerm` (BillTermRef, required): The billing term (visible ones only). - `name` (string or null): New name. - `description` (string or null): New description. - `type` (BillTermTypeWire or null): Days or proximo. - `dueDays` (integer (int64) or null): Days until due, or the proximo due day. - `discountDays` (integer (int64) or null): Discount days, or the proximo discount day. - `discount` (Amount or null): Discount percentage. - `cutoff` (integer (int64) or null): Proximo cutoff day. ## Result A billing term. - `guid` (Guid, required): Its GUID. - `name` (string, required): Its name; frozen copies share their parent's. - `description` (string, required): Description. - `type` (BillTermTypeWire or null): Days or proximo; absent for a term whose type was never set. - `dueDays` (integer (int64), required): Days until due, or the proximo due day. - `discountDays` (integer (int64), required): Discount days, or the proximo discount day. - `discount` (Amount, required): Discount percentage. - `cutoff` (integer (int64), required): Proximo cutoff day. - `refcount` (integer (int64), required): How many customers, vendors and documents use it (always 0 for a frozen copy). - `invisible` (boolean, required): True for frozen copies. - `parent` (Guid or null): The term it is a frozen copy of. - `child` (Guid or null): Its current frozen copy. ## Related - [billTerm.create](method/billTerm.create) - [billTerm.get](method/billTerm.get) --- *red-ale Manual, `method/billTerm.update`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # book.close Close the open book and release its lock. Closes the open book and releases its lock, so another program (or another [book.open](method/book.open)) can use it. If the book has unsaved changes the call is refused with [unsaved-changes](error/unsaved-changes) and the book stays open; pass `save: true` to write them first or `discard: true` to drop them. Not to be confused with [book.closeBooks](method/book.closeBooks), which is GnuCash's Close Book: it zeroes income and expense into equity and leaves the book open. ## Examples An edited book will not close until you say what to do with the edit: *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Savings","type":"BANK","parent":"Root:Asset","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"book.close","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "error": { "code": 1012, "message": "…", "data": { "help": "error/unsaved-changes" } } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"book.close","params":{"save":true}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "saved": true, "discarded": false } } ``` **Effect:** `write`, on the Book. ## Params Params of `book.close`. - `save` (boolean): Save unsaved changes first. - `discard` (boolean): Discard unsaved changes. Without `save` or `discard`, closing a book with unsaved changes is refused. ## Result What `book.close` did. - `saved` (boolean, required): The book was saved before closing. - `discarded` (boolean, required): Unsaved changes were discarded. ## Related - [book.save](method/book.save) - [book.open](method/book.open) - [unsaved-changes](error/unsaved-changes) --- *red-ale Manual, `method/book.close`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # book.closeBooks Close the books: move income and expense balances into equity at a closing date, one closing transaction per currency. Not book.close. GnuCash's Tools > Close Book: at a closing date it moves every income and expense balance into equity, one closing transaction per currency and kind, so those accounts start the next period at zero. Name the two equity accounts that take the income and the expenses (they may be the same one); a sub-account named after a currency is made under the equity account when more than one currency is closed. The book stays open and editable. It does not mark the date anywhere, so run it once per period. An income or expense balance held in a security rather than a currency is refused with `invalid`, where GnuCash would book it as money. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"book.closeBooks","params":{"date":"2024-03-31","incomeTotalAccount":"Root:Equity","expenseTotalAccount":"Root:Equity","description":"Close"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "transactions": [ { "guid": "…", "kind": "income", "currency": "CURRENCY::USD", "equityAccount": "…", "total": { "num": "-257300", "denom": "100" } }, "…" ], "createdAccounts": [ "…", "…" ] } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.balance","params":{"account":"Root:Income","asOf":"2024-03-31"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "balances": { "balance": { "num": "0", "denom": "100" }, "…": "…" }, "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `book.closeBooks`. - `date` (Date, required): The closing date; balances at the end of this day, local time, are closed. - `incomeTotalAccount` (AccountRef, required): The equity account taking the period's income (GnuCash's "Income Total"). - `expenseTotalAccount` (AccountRef, required): The equity account taking the period's expense (GnuCash's "Expense Total"); may be the same account. - `description` (string): The closing transactions' description; empty by default, as in GnuCash's dialog. ## Result The result of `book.closeBooks`. - `transactions` (array of ClosingInfo, required): The closing transactions, income first. - `createdAccounts` (array of Guid, required): Equity accounts made for a currency. ## Related - [book.close](method/book.close) - [account.balance](method/account.balance) - [period.dates](method/period.dates) --- *red-ale Manual, `method/book.closeBooks`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # book.create Create a new, empty XML or SQLite book and open it. Creates a new, empty book (a root account and nothing else) at `path` and opens it. By default it is an XML book, gzip-compressed as GnuCash writes it; pass `compressed: false` for plain XML or `format: "sqlite"` for an SQLite book (also chosen by a `sqlite3://` path). The file is written by the first [book.save](method/book.save). The path must be free: an existing file is refused with [file-exists](error/file-exists), so a book is never overwritten by accident. ## Examples *Example: with no book.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"book.create","params":{"path":"new.gnucash","compressed":false}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "path": "…", "guid": "…", "rootAccount": "…", "readOnly": false, "format": "xml", "compressed": false, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.list","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "accounts": [], "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `book.create`. - `path` (string, required): A path, or an `xml://` or `sqlite3://` URI, that does not exist yet. - `compressed` (boolean or null): XML only: write it gzip-compressed (GnuCash's default). Defaults to the server's setting. - `format` (BookFormat or null): `xml` or `sqlite`. Defaults to the one a `sqlite3://` or `xml://` URI names, else `xml`. ## Result The result of `book.open`, `book.create` and `book.info`. - `path` (string, required): The book's file. - `guid` (Guid, required): The book's GUID. - `rootAccount` (Guid, required): The root account's GUID. - `readOnly` (boolean, required): Nothing can be changed. - `readOnlyReasons` (array of ReadOnlyInfo, required): Why, when read-only. - `dirty` (boolean, required): There are unsaved changes. - `compressed` (boolean, required): The file is gzip-compressed; always false for an SQLite book. - `format` (BookFormat, required): The file's format: `xml` or `sqlite`. - `versions` (array of VersionInfo or null): SQLite books only: the `versions` table as read, in its order. - `journal` (string or null): The transaction journal being written, if any. - `features` (array of FeatureInfo, required): Book features the book declares. - `counts` (Counts, required): Entity counts. ## Related - [book.open](method/book.open) - [book.save](method/book.save) - [file-exists](error/file-exists) --- *red-ale Manual, `method/book.create`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # book.info Describe the open book: path, read-only state, features and counts. Describes the open book: its path and format, whether it is `dirty` (has unsaved changes), whether it is read-only and why, the Book features it declares, and how many accounts, transactions, prices and so on it holds. Call it after [book.open](method/book.open) to see what you opened, or to check `dirty` before closing. `counts` are the book's own totals; they include hidden accounts and read-only transactions. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"book.info","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "path": "…", "readOnly": false, "dirty": false, "format": "xml", "features": [], "counts": { "commodities": 3, "accounts": 11, "transactions": 59, "prices": 2, "…": "…" }, "…": "…" } } ``` **Effect:** `read`. ## Params Params for methods that take none. Type: NoParams. ## Result The result of `book.open`, `book.create` and `book.info`. - `path` (string, required): The book's file. - `guid` (Guid, required): The book's GUID. - `rootAccount` (Guid, required): The root account's GUID. - `readOnly` (boolean, required): Nothing can be changed. - `readOnlyReasons` (array of ReadOnlyInfo, required): Why, when read-only. - `dirty` (boolean, required): There are unsaved changes. - `compressed` (boolean, required): The file is gzip-compressed; always false for an SQLite book. - `format` (BookFormat, required): The file's format: `xml` or `sqlite`. - `versions` (array of VersionInfo or null): SQLite books only: the `versions` table as read, in its order. - `journal` (string or null): The transaction journal being written, if any. - `features` (array of FeatureInfo, required): Book features the book declares. - `counts` (Counts, required): Entity counts. ## Related - [book.open](method/book.open) - [book.save](method/book.save) - [book.options](method/book.options) --- *red-ale Manual, `method/book.info`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # book.open Open an XML or SQLite book. Some books open read-only (see readOnlyReasons). Opens an existing GnuCash book, XML or SQLite, so the other methods can read and change it. Call it first, with the book's path; a server holds one book at a time, so close the open one with `book.close` before opening another. Unless you ask for `readOnly`, it takes the book's lock, as GnuCash does, and fails with `book-locked` while GnuCash or another red-ale has the book open. A book can also open read-only without being asked: `readOnly` is then true and `readOnlyReasons` says why, for instance a Book feature red-ale does not implement. Read-only books are never locked and never written. ## Examples *Example: with a copy of the `reports/test-data` example book saved as `book.gnucash`, not open.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"book.open","params":{"path":"book.gnucash"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "path": "…", "guid": "…", "rootAccount": "…", "readOnly": false, "readOnlyReasons": [], "dirty": false, "compressed": "…", "format": "xml", "journal": "…", "features": "…", "counts": "…" } } ``` Opening it read-only leaves it free for GnuCash: *Example: with a copy of the `reports/test-data` example book saved as `book.gnucash`, not open.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"book.open","params":{"path":"book.gnucash","readOnly":true}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "readOnly": true, "readOnlyReasons": [ { "code": "requested", "message": "opened read-only on request" } ], "…": "…" } } ``` **Effect:** `read`. ## Params Params of `book.open`. - `path` (string, required): A path, or an `xml://`, `sqlite3://` or `file://` URI. - `readOnly` (boolean): Open without taking the lock; nothing can be changed. ## Result The result of `book.open`, `book.create` and `book.info`. - `path` (string, required): The book's file. - `guid` (Guid, required): The book's GUID. - `rootAccount` (Guid, required): The root account's GUID. - `readOnly` (boolean, required): Nothing can be changed. - `readOnlyReasons` (array of ReadOnlyInfo, required): Why, when read-only. - `dirty` (boolean, required): There are unsaved changes. - `compressed` (boolean, required): The file is gzip-compressed; always false for an SQLite book. - `format` (BookFormat, required): The file's format: `xml` or `sqlite`. - `versions` (array of VersionInfo or null): SQLite books only: the `versions` table as read, in its order. - `journal` (string or null): The transaction journal being written, if any. - `features` (array of FeatureInfo, required): Book features the book declares. - `counts` (Counts, required): Entity counts. ## Related - [book.create](method/book.create) - [book.info](method/book.info) - [book.save](method/book.save) - [book.close](method/book.close) - [book-locked](error/book-locked) --- *red-ale Manual, `method/book.open`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # book.options The book's num field source, auto read-only threshold (with today's threshold date), trading accounts option, default budget, business options and default invoice report. Reads the book's options from GnuCash's File > Properties dialog: whether the Num field of a transaction shows the split action instead (`splitActionForNum`), the auto read-only threshold in days (`autoReadOnlyDays`) with the `readOnlyThreshold` date it means today, whether the book uses trading accounts, the default budget, your company's details from the Business and Tax tabs, which the [Printable Invoice](report/printable-invoice) prints, and the Default Invoice Report (`defaultInvoiceReport`). ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"book.options","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "splitActionForNum": false, "autoReadOnlyDays": 0, "useTradingAccounts": false, "defaultBudget": null, "companyName": "", "companyAddress": "", "companyContactPerson": "", "companyPhoneNumber": "", "companyFaxNumber": "", "companyEmailAddress": "", "companyWebsiteUrl": "", "companyId": "", "taxNumber": "", "defaultInvoiceReport": null } } ``` **Effect:** `read`. ## Params Params for methods that take none. Type: NoParams. ## Result The book options, as `book.options` and `book.setOptions` return them. - `splitActionForNum` (boolean, required): "Use Split Action Field for Number": a split's Number is its action, and the transaction's num is the T-Num. - `autoReadOnlyDays` (integer (int64), required): "Day Threshold for Read-Only Transactions (red line)": 0 when off. - `readOnlyThreshold` (Date or null): Today minus the threshold's days: transactions posted before it are read-only. Absent when the threshold is off. - `useTradingAccounts` (boolean, required): "Use Trading Accounts": every commit keeps the trading splits of multi-commodity transactions. - `defaultBudget` (Guid or null): "Default Budget": the GUID the option holds, or null when it is unset. A GUID naming no budget is returned as stored; `budget.list` gives the default in effect. - `companyName` (string, required): The Business tab's "Company Name"; `""` when unset (v0.6). - `companyAddress` (string, required): "Company Address": lines separated by newlines (v0.6). - `companyContactPerson` (string, required): "Company Contact Person" (v0.6). - `companyPhoneNumber` (string, required): "Company Phone Number" (v0.6). - `companyFaxNumber` (string, required): "Company Fax Number" (v0.6). - `companyEmailAddress` (string, required): "Company Email Address" (v0.6). - `companyWebsiteUrl` (string, required): "Company Website URL" (v0.6). - `companyId` (string, required): "Company ID", such as a tax ID (v0.6). - `taxNumber` (string, required): The Tax tab's "Tax Number" (v0.6). - `defaultInvoiceReport` (InvoiceReport or null): "Default Invoice Report": the report GnuCash's Print Invoice runs, as GnuCash parses the slot; null when unset or unreadable. The GUID is returned as stored and may name no report red-ale has (v0.6). ## Related - [book.setOptions](method/book.setOptions) - [book.info](method/book.info) --- *red-ale Manual, `method/book.options`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # book.replayJournal Replay a GnuCash .log journal onto the open book: create, update or delete transactions by GUID. Replays a GnuCash `.log` journal onto the open book: each record creates, updates or deletes a transaction by GUID. Use it to recover work from a journal after a crash, by replaying the journal of the book you lost onto the last saved file. `created`, `updated` and `deleted` list the GUIDs touched; `notFound` lists records whose transaction was not there to update or delete. Replaying is journaled like any other change, and it changes transactions only, not accounts: records that need an account the book lacks are refused unless `skipInvalid` is true, which skips them and lists them in `skippedRecords`. The file is read on the server, so `path` is relative to where it runs. ## Examples The journal of an open book is the `journal` field of [book.info](method/book.info). A path that does not exist fails with `io-error`, and nothing is changed: *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"book.replayJournal","params":{"path":"missing.log"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": 1008, "message": "…", "data": { "path": "…", "help": "error/io-error" } } } ``` A transaction posted and then lost, because the book was closed without saving, comes back from the journal. The journal is named by the local time it was opened at, here `book.gnucash.20240701120000.log`: *Example: with a new, empty book open as `book.gnucash`, at 2024-07-01T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Rent","type":"EXPENSE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"book.save","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"transaction.post","params":{"datePosted":"2024-07-01","description":"Rent","splits":[{"account":"Checking","value":"-750.00"},{"account":"Rent","value":"750.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "guid": "…", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"book.close","params":{"discard":true}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":6,"method":"book.open","params":{"path":"book.gnucash"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 6, "result": { "counts": { "transactions": 0, "…": "…" }, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":7,"method":"book.replayJournal","params":{"path":"book.gnucash.20240701120000.log"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 7, "result": { "created": [ "…" ], "updated": [], "deleted": [], "notFound": [], "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `book.replayJournal`. - `path` (string, required): The journal: a `..log` file. - `skipInvalid` (boolean): Skip records that cannot be applied (for example an unbalanced transaction) instead of refusing the replay. ## Result What `book.replayJournal` did. - `records` (integer (uint), required): Records read. - `created` (array of Guid, required): Transactions created. - `updated` (array of Guid, required): Transactions updated. - `deleted` (array of Guid, required): Transactions deleted. - `notFound` (array of Guid, required): Deletions of transactions the book does not have. - `skippedRecords` (array of string, required): Records skipped, with why. - `skippedLines` (array of string, required): Lines that could not be read, as `line N: reason`. ## Related - [book.save](method/book.save) - [file-format](error/file-format) --- *red-ale Manual, `method/book.replayJournal`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # book.save Save the open book, backing up the previous file first (for an SQLite book, before the session's first save). Writes the open book to its file. Changes made by other methods live in memory (and in the `.log` journal) until you call this. Before overwriting, it copies the previous file to `..gnucash`, as GnuCash does, and returns the copy's path as `backup`; it then reads the new file back to check that it holds the same book. An XML book keeps its compression unless you pass `compressed`. An SQLite book is backed up before the session's first save that writes, and `compressed` is refused for it. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Savings","type":"BANK","parent":"Root:Asset","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"book.info","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "dirty": true, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"book.save","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "backup": "…", "removed": [], "compressed": false } } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"book.info","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "dirty": false, "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `book.save`. - `compressed` (boolean or null): XML only: change the file's compression; by default it is kept. ## Result What `book.save` did. - `backup` (string or null): The backup of the previous file. - `removed` (array of string, required): Old backups and journals removed by retention. - `compressed` (boolean, required): The file was written gzip-compressed; always false for an SQLite book. ## Related - [book.close](method/book.close) - [book.info](method/book.info) - [backup-failed](error/backup-failed) - [save-verification](error/save-verification) --- *red-ale Manual, `method/book.save`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # book.setOptions Set the num field source, the auto read-only threshold, trading accounts, the default budget, the business options or the default invoice report, as GnuCash's book options dialog does. Changes any of the book's options; an option you leave out is left alone. `autoReadOnlyDays` (0 to 3650) makes transactions older than that many days read-only, as GnuCash's red line does, and the result's `readOnlyThreshold` is the date it works out to today. `useTradingAccounts` switches the book to trading accounts, which changes how transactions in several currencies are recorded. Pitfall: once a threshold is set, posting a transaction dated before it is refused with `invalid`, and changing or deleting an existing one with `conflict`; both carry `data.reason` `auto-read-only`. Set it to 0 to lift it. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`, at 2024-07-01T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"book.setOptions","params":{"autoReadOnlyDays":30}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "splitActionForNum": false, "autoReadOnlyDays": 30, "readOnlyThreshold": "2024-06-01", "useTradingAccounts": false, "defaultBudget": null, "companyName": "", "companyAddress": "", "companyContactPerson": "", "companyPhoneNumber": "", "companyFaxNumber": "", "companyEmailAddress": "", "companyWebsiteUrl": "", "companyId": "", "taxNumber": "", "defaultInvoiceReport": null } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"transaction.post","params":{"datePosted":"2024-03-01","description":"Too old","splits":[{"account":"Root:Asset:Bank","value":"5.00"},{"account":"Root:Expenses","value":"-5.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "error": { "code": 2001, "message": "…", "data": { "reason": "auto-read-only", "date": "2024-03-01", "threshold": "2024-06-01", "help": "error/invalid" } } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"transaction.delete","params":{"guid":"c0000000000000000000000000000000"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "error": { "code": 2003, "message": "…", "data": { "reason": "auto-read-only", "date": "1970-01-01", "threshold": "2024-06-01", "help": "error/conflict" } } } ``` **Effect:** `write`, on the Book. ## Params Params of `book.setOptions`; an absent option is left as it is. - `splitActionForNum` (boolean or null): Use the split action as the Number. Turning it on also sets the Book feature `Number Field Source`. - `autoReadOnlyDays` (integer (int64) or null): Days after which transactions become read-only: 0 (off) to 3650. - `useTradingAccounts` (boolean or null): Balance multi-commodity transactions through trading accounts. No existing transaction changes. - `defaultBudget` (Guid or null): The default budget: a budget of the book. It cannot be unset. - `companyName` (string or null): "Company Name"; `""` clears it (v0.6). - `companyAddress` (string or null): "Company Address", lines separated by newlines (v0.6). - `companyContactPerson` (string or null): "Company Contact Person" (v0.6). - `companyPhoneNumber` (string or null): "Company Phone Number" (v0.6). - `companyFaxNumber` (string or null): "Company Fax Number" (v0.6). - `companyEmailAddress` (string or null): "Company Email Address" (v0.6). - `companyWebsiteUrl` (string or null): "Company Website URL" (v0.6). - `companyId` (string or null): "Company ID" (v0.6). - `taxNumber` (string or null): The Tax tab's "Tax Number" (v0.6). - `defaultInvoiceReport` (InvoiceReportParam or null): "Default Invoice Report": `{ guid, name }`, or null to clear it (v0.6). ## Result The book options, as `book.options` and `book.setOptions` return them. - `splitActionForNum` (boolean, required): "Use Split Action Field for Number": a split's Number is its action, and the transaction's num is the T-Num. - `autoReadOnlyDays` (integer (int64), required): "Day Threshold for Read-Only Transactions (red line)": 0 when off. - `readOnlyThreshold` (Date or null): Today minus the threshold's days: transactions posted before it are read-only. Absent when the threshold is off. - `useTradingAccounts` (boolean, required): "Use Trading Accounts": every commit keeps the trading splits of multi-commodity transactions. - `defaultBudget` (Guid or null): "Default Budget": the GUID the option holds, or null when it is unset. A GUID naming no budget is returned as stored; `budget.list` gives the default in effect. - `companyName` (string, required): The Business tab's "Company Name"; `""` when unset (v0.6). - `companyAddress` (string, required): "Company Address": lines separated by newlines (v0.6). - `companyContactPerson` (string, required): "Company Contact Person" (v0.6). - `companyPhoneNumber` (string, required): "Company Phone Number" (v0.6). - `companyFaxNumber` (string, required): "Company Fax Number" (v0.6). - `companyEmailAddress` (string, required): "Company Email Address" (v0.6). - `companyWebsiteUrl` (string, required): "Company Website URL" (v0.6). - `companyId` (string, required): "Company ID", such as a tax ID (v0.6). - `taxNumber` (string, required): The Tax tab's "Tax Number" (v0.6). - `defaultInvoiceReport` (InvoiceReport or null): "Default Invoice Report": the report GnuCash's Print Invoice runs, as GnuCash parses the slot; null when unset or unreadable. The GUID is returned as stored and may name no report red-ale has (v0.6). ## Related - [book.options](method/book.options) - [invalid](error/invalid) - [conflict](error/conflict) --- *red-ale Manual, `method/book.setOptions`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # budget.copy Copy a budget as GnuCash's Copy Budget does (notes are not copied). Copies a budget as GnuCash's Copy Budget does: a new budget named `Copy of ` with the same description, recurrence, number of periods and every amount. Notes are not copied, nor are amounts hidden beyond the period count, and the copy goes last in book order. Rename it with [budget.update](method/budget.update). ## Examples *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Rent","type":"EXPENSE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"budget.create","params":{"name":"2024","numPeriods":3,"recurrence":{"mult":1,"periodType":"month","start":"2024-01-01"}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"budget.setAmounts","params":{"budget":"00ed0000000000000000000000000002","amounts":[{"account":"Rent","period":0,"amount":"750.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"budget.setNotes","params":{"budget":"00ed0000000000000000000000000002","notes":[{"account":"Rent","period":0,"note":"New lease"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"budget.copy","params":{"budget":"00ed0000000000000000000000000002"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": { "name": "Copy of 2024", "isDefault": false, "amounts": [ { "accountName": "Rent", "period": 0, "amount": { "num": "75000", "denom": "100" }, "…": "…" } ], "notes": [], "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Names one budget. - `budget` (Guid, required): The budget. ## Result A budget. - `guid` (Guid, required): Identity. - `name` (string, required): The name. - `description` (string, required): The description. - `numPeriods` (integer (uint32), required): The number of periods. - `recurrence` (Recurrence, required): The recurrence that gives the periods' dates, as stored. - `isDefault` (boolean, required): True for the default budget. - `periods` (array of PeriodInfo or null): Each period below `numPeriods`; absent in `budget.list`. - `amounts` (array of AmountInfo or null): Every set amount of an account in the tree below `numPeriods`, by account full name then period; absent in `budget.list`. - `notes` (array of NoteInfo or null): Every note likewise; absent in `budget.list`. - `hidden` (SlotCounts, required): Amounts and notes kept at or beyond `numPeriods`. - `orphaned` (SlotCounts, required): Amounts and notes kept for GUIDs that name no account. ## Related - [budget.update](method/budget.update) - [budget.delete](method/budget.delete) --- *red-ale Manual, `method/budget.copy`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # budget.create Create a budget; the first sets the Book feature for natural signs. Creates a budget: a name, a number of periods (1 to 60, default 12) and a recurrence that dates them (default every month from the first of this month). It has no amounts yet; fill them with [budget.setAmounts](method/budget.setAmounts). The first budget in a book sets the book feature `Use natural signs in budget amounts`, as GnuCash's New Budget does. In a book that has budgets but lacks the feature, which GnuCash older than 3.8 wrote, creating (and every other edit) is refused with `conflict` until [budget.scrubSigns](method/budget.scrubSigns) has run: red-ale never changes budgets when it opens a book. GnuCash's New Budget also fills the description with `Created: `; red-ale does not, send it yourself if you want it. ## Examples *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"budget.create","params":{"name":"2024","numPeriods":6,"recurrence":{"mult":1,"periodType":"month","start":"2024-01-01"}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "…", "name": "2024", "numPeriods": 6, "isDefault": true, "periods": [ { "index": 0, "startDate": "2024-01-01", "endDate": "2024-01-31" }, { "index": 1, "startDate": "2024-02-01", "endDate": "2024-02-29" }, "…" ], "amounts": [], "notes": [], "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"budget.create","params":{"numPeriods":61}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "error": { "code": 2001, "message": "a budget has 1 to 60 periods, not 61", "data": { "help": "error/invalid" } } } ``` **Effect:** `write`, on the Book. ## Params Params of `budget.create`; absent fields take GnuCash's defaults. - `name` (string or null): The name; `Unnamed Budget` when absent. - `description` (string or null): The description; empty when absent. - `numPeriods` (integer (uint32) or null): The number of periods, 1 to 60; 12 when absent. - `recurrence` (Recurrence or null): The periods' recurrence: never `once`, weekend adjustment `none`. Monthly from the first of the current month when absent. ## Result A budget. - `guid` (Guid, required): Identity. - `name` (string, required): The name. - `description` (string, required): The description. - `numPeriods` (integer (uint32), required): The number of periods. - `recurrence` (Recurrence, required): The recurrence that gives the periods' dates, as stored. - `isDefault` (boolean, required): True for the default budget. - `periods` (array of PeriodInfo or null): Each period below `numPeriods`; absent in `budget.list`. - `amounts` (array of AmountInfo or null): Every set amount of an account in the tree below `numPeriods`, by account full name then period; absent in `budget.list`. - `notes` (array of NoteInfo or null): Every note likewise; absent in `budget.list`. - `hidden` (SlotCounts, required): Amounts and notes kept at or beyond `numPeriods`. - `orphaned` (SlotCounts, required): Amounts and notes kept for GUIDs that name no account. ## Related - [budget.setAmounts](method/budget.setAmounts) - [budget.update](method/budget.update) - [budget.list](method/budget.list) - [budget.scrubSigns](method/budget.scrubSigns) --- *red-ale Manual, `method/budget.create`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # budget.delete Delete a budget; the last unsets the Book feature for natural signs. Deletes a budget with all its amounts and notes. Deleting the last budget unsets the book feature `Use natural signs in budget amounts`, as GnuCash does (`featureUnset` says so). The book option `Default Budget` is left alone even if it names the deleted budget; a stale one falls back to the first budget. ## Examples *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"budget.create","params":{"name":"2024"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"budget.delete","params":{"budget":"00ed0000000000000000000000000001"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "deleted": true, "featureUnset": true } } ``` **Effect:** `destructive`, on the Book. ## Params Names one budget. - `budget` (Guid, required): The budget. ## Result The result of `budget.delete`. - `deleted` (boolean, required): Always true. - `featureUnset` (boolean, required): The last budget went, so the feature `Use natural signs in budget amounts` was unset. ## Related - [budget.create](method/budget.create) - [budget.copy](method/budget.copy) --- *red-ale Manual, `method/budget.delete`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # budget.estimate Overwrite accounts' budget amounts with figures from past transactions, as GnuCash's Estimate dialog does. Fills the budget amounts of the accounts you name from what happened in the past, as GnuCash's Estimate dialog does. History periods follow the budget's own recurrence starting at `startDate`; the account's change over history period *n* becomes budget period *n*. With `useAverage` the change over all the history periods, divided by the number of periods, goes into every period. Each account's change includes its sub-accounts. Closing transactions are left out. It overwrites every period of every account you name, set amounts included, so it is destructive. Figures are rounded to `significantDigits` (default 1) significant digits, but never to the left of the decimal point: 812.50 at 2 digits is 813, and 5.6789 at 1 digit is 6. A period with no change is a set zero. ## Examples *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Rent","type":"EXPENSE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"budget.create","params":{"name":"2024","numPeriods":3,"recurrence":{"mult":1,"periodType":"month","start":"2024-01-01"}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"transaction.post","params":{"datePosted":"2024-01-05","description":"Rent","splits":[{"account":"Rent","value":"750.00"},{"account":"Checking","value":"-750.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"transaction.post","params":{"datePosted":"2024-02-05","description":"Rent","splits":[{"account":"Rent","value":"812.50"},{"account":"Checking","value":"-812.50"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":6,"method":"budget.estimate","params":{"budget":"00ed0000000000000000000000000003","accounts":["Rent"],"startDate":"2024-01-01","significantDigits":2}} ``` Response: ```json { "jsonrpc": "2.0", "id": 6, "result": { "amounts": [ { "accountName": "Rent", "period": 0, "amount": { "num": "750", "denom": "1" }, "…": "…" }, { "period": 1, "amount": { "num": "813", "denom": "1" }, "…": "…" }, { "period": 2, "amount": { "num": "0", "denom": "1" }, "…": "…" } ], "…": "…" } } ``` **Effect:** `destructive`, on the Book. ## Params Params of `budget.estimate`. - `budget` (Guid, required): The budget. - `accounts` (array of AccountRef, required): The accounts to estimate, at least one; each from its own subtree. - `startDate` (Date, required): The start of history period 0; history periods follow the budget's recurrence from here. - `significantDigits` (integer (uint8)): Significant digits to round to, 1 to 12. - `useAverage` (boolean): Store the average over every history period in every period. ## Result The result of `budget.estimate`. - `budget` (Guid, required): The budget. - `amounts` (array of AmountInfo, required): Every amount written. ## Related - [budget.setAmounts](method/budget.setAmounts) - [budget.get](method/budget.get) --- *red-ale Manual, `method/budget.estimate`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # budget.get One budget with its periods, amounts and notes. Returns one budget with its periods (each with its first and last day), every amount that is set and every note. Give `accounts` to see only those. A budget amount is either set (even to zero) or unset, which `budget.get` simply does not list: `0` and nothing are different, because the budget reports roll an unset parent up from its children but not a parent set to zero. Amounts are in natural signs: an expense budget is positive, an income budget negative. `hidden` counts amounts and notes beyond the budget's period count, which are kept; `orphaned` counts those of accounts no longer in the book. ## Examples *Example: with a copy of the `reports/budget` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"budget.get","params":{"budget":"f0000000000000000000000000000000","accounts":["Root:Expenses"]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "f0000000000000000000000000000000", "name": "test budget", "numPeriods": 6, "periods": [ { "index": 0, "startDate": "2024-03-01", "endDate": "2024-03-31" }, "…" ], "amounts": [ { "accountName": "Root:Expenses", "period": 1, "amount": { "num": "30", "denom": "1" }, "…": "…" }, { "period": 2, "amount": { "num": "20", "denom": "1" }, "…": "…" }, { "period": 3, "amount": { "num": "40", "denom": "1" }, "…": "…" } ], "notes": [ "…" ], "hidden": { "amounts": 0, "notes": 0 }, "orphaned": { "amounts": 0, "notes": 0 }, "…": "…" } } ``` **Effect:** `read`. ## Params Params of `budget.get`. - `budget` (Guid, required): The budget. - `accounts` (array of AccountRef or null): List amounts and notes of these accounts only. ## Result A budget. - `guid` (Guid, required): Identity. - `name` (string, required): The name. - `description` (string, required): The description. - `numPeriods` (integer (uint32), required): The number of periods. - `recurrence` (Recurrence, required): The recurrence that gives the periods' dates, as stored. - `isDefault` (boolean, required): True for the default budget. - `periods` (array of PeriodInfo or null): Each period below `numPeriods`; absent in `budget.list`. - `amounts` (array of AmountInfo or null): Every set amount of an account in the tree below `numPeriods`, by account full name then period; absent in `budget.list`. - `notes` (array of NoteInfo or null): Every note likewise; absent in `budget.list`. - `hidden` (SlotCounts, required): Amounts and notes kept at or beyond `numPeriods`. - `orphaned` (SlotCounts, required): Amounts and notes kept for GUIDs that name no account. ## Related - [budget.list](method/budget.list) - [budget.setAmounts](method/budget.setAmounts) --- *red-ale Manual, `method/budget.get`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # budget.list Every budget in book order, and which is the default. Lists the budgets in book order, without their periods, amounts and notes, with the default one (the budget the budget reports use unless told otherwise). `defaultFrom` says whether the book names it (`option`) or it is just the first (`first`). Set the default with `book.setOptions`. `needsSignScrub` is true when the book has budgets but not the natural-signs feature, so that edits are refused until [budget.scrubSigns](method/budget.scrubSigns) runs. Listing and reading work either way. ## Examples *Example: with a copy of the `reports/budget` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"budget.list","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "budgets": [ { "guid": "f0000000000000000000000000000000", "name": "test budget", "numPeriods": 6, "isDefault": true, "…": "…" } ], "default": "f0000000000000000000000000000000", "defaultFrom": "first", "naturalSigns": false, "needsSignScrub": true } } ``` **Effect:** `read`. ## Params Params for methods that take none. Type: NoParams. ## Result The result of `budget.list`. - `budgets` (array of BudgetInfo, required): Every budget, in book order, without periods, amounts and notes. - `default` (Guid or null): The default budget's GUID, or null when the book has none. - `defaultFrom` (DefaultFromWire or null): Where the default comes from, or null. - `naturalSigns` (boolean, required): Whether the book has the feature `Use natural signs in budget amounts`. - `needsSignScrub` (boolean, required): True when the book has budgets and lacks the feature: edits are refused until `budget.scrubSigns`. ## Related - [budget.get](method/budget.get) - [budget.scrubSigns](method/budget.scrubSigns) - [book.options](method/book.options) --- *red-ale Manual, `method/budget.list`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # budget.scrubSigns Run GnuCash's natural-signs scrub: guess each budget's old sign convention and flip amounts to match. Runs GnuCash's natural-signs scrub on a book whose budgets predate GnuCash 3.8, which stored amounts with the signs of the user's display preference. For each budget it guesses the old convention from the sums of its amounts and flips the amounts to natural signs, then sets the book feature `Use natural signs in budget amounts`. It rewrites amounts on a guess, so it is destructive: look at the budgets after, as GnuCash asks. GnuCash runs this every time a file opens; red-ale does not, and until you run it every budget edit is refused with `conflict` (reason `natural-signs`). `budget.list` tells you when it is needed. With no budgets it only unsets a feature left over. Each result says which `policy` was guessed (`incomeExpense`, `creditAccounts`, `none`) and how many amounts were flipped. ## Examples *Example: with a copy of the `reports/budget` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"budget.setAmounts","params":{"budget":"f0000000000000000000000000000000","amounts":[{"account":"Root:Expenses","period":0,"amount":"1"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": 2003, "message": "…", "data": { "reason": "natural-signs", "help": "error/conflict" } } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"budget.scrubSigns","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "featureSet": true, "featureUnset": false, "budgets": [ { "budget": "f0000000000000000000000000000000", "policy": "none", "flipped": 0 } ] } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"budget.list","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "naturalSigns": true, "needsSignScrub": false, "…": "…" } } ``` **Effect:** `destructive`, on the Book. ## Params Params for methods that take none. Type: NoParams. ## Result The result of `budget.scrubSigns`. - `featureSet` (boolean, required): The feature was set. - `featureUnset` (boolean, required): The feature was unset, as the book has no budgets. - `budgets` (array of BudgetScrubInfo, required): Each budget scrubbed, in book order. ## Related - [budget.list](method/budget.list) - [budget.create](method/budget.create) --- *red-ale Manual, `method/budget.scrubSigns`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # budget.setAmounts Set or unset many budget amounts, atomically. Sets or unsets many budget amounts at once, all or none. Each cell is an account and a period (counting from 0); an `amount` sets it, `null` unsets it, and `"0"` is a set zero, which is not the same as unset. Amounts are kept exactly as given (`"750.00"` is stored as 75000/100) in natural signs: expense budgets positive, income budgets negative. Refused with `invalid`: a period at or beyond the budget's count (GnuCash silently does nothing), the same cell twice in one call, the root account. Placeholder and hidden accounts may have amounts. ## Examples *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Rent","type":"EXPENSE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Salary","type":"INCOME","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"budget.create","params":{"name":"2024","numPeriods":6,"recurrence":{"mult":1,"periodType":"month","start":"2024-01-01"}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"budget.setAmounts","params":{"budget":"00ed0000000000000000000000000003","amounts":[{"account":"Rent","period":0,"amount":"750.00"},{"account":"Rent","period":1,"amount":"750.00"},{"account":"Salary","period":0,"amount":"-3000.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "budget": "00ed0000000000000000000000000003", "set": 3, "unset": 0 } } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"budget.setAmounts","params":{"budget":"00ed0000000000000000000000000003","amounts":[{"account":"Rent","period":9,"amount":"1"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "error": { "code": 2001, "message": "period 9 is past the budget's 6 periods (they count from 0)", "data": { "help": "error/invalid" } } } ``` **Effect:** `write`, on the Book. ## Params Params of `budget.setAmounts`. - `budget` (Guid, required): The budget. - `amounts` (array of AmountCell, required): The cells; each at most once. ## Result The result of `budget.setAmounts`. - `budget` (Guid, required): The budget. - `set` (integer (uint), required): Cells set. - `unset` (integer (uint), required): Set cells unset. ## Related - [budget.get](method/budget.get) - [budget.setNotes](method/budget.setNotes) - [budget.estimate](method/budget.estimate) --- *red-ale Manual, `method/budget.setAmounts`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # budget.setNotes Set or delete many budget notes, atomically. Sets or deletes many budget notes at once, all or none. A note belongs to an account and a period; an empty string or `null` deletes it. Notes have no length limit. The checks are those of [budget.setAmounts](method/budget.setAmounts). ## Examples *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Rent","type":"EXPENSE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"budget.create","params":{"name":"2024","numPeriods":6,"recurrence":{"mult":1,"periodType":"month","start":"2024-01-01"}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"budget.setNotes","params":{"budget":"00ed0000000000000000000000000002","notes":[{"account":"Rent","period":0,"note":"New lease"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "budget": "00ed0000000000000000000000000002", "set": 1, "deleted": 0 } } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"budget.setNotes","params":{"budget":"00ed0000000000000000000000000002","notes":[{"account":"Rent","period":0,"note":""}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "budget": "00ed0000000000000000000000000002", "set": 0, "deleted": 1 } } ``` **Effect:** `write`, on the Book. ## Params Params of `budget.setNotes`. - `budget` (Guid, required): The budget. - `notes` (array of NoteCell, required): The cells; each at most once. ## Result The result of `budget.setNotes`. - `budget` (Guid, required): The budget. - `set` (integer (uint), required): Notes set. - `deleted` (integer (uint), required): Notes deleted. ## Related - [budget.setAmounts](method/budget.setAmounts) - [budget.get](method/budget.get) --- *red-ale Manual, `method/budget.setNotes`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # budget.update Change a budget's name, description, number of periods or recurrence. Changes a budget's name, description, number of periods or recurrence. Lowering `numPeriods` hides amounts and notes beyond the new count but does not delete them: they stay in the book, `hidden` counts them, and raising the count shows them again, as in GnuCash, which has no way to drop them. Changing the recurrence moves no amount: amounts belong to a period number, so only the dates of the periods change. ## Examples *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Rent","type":"EXPENSE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"budget.create","params":{"name":"2024","numPeriods":6,"recurrence":{"mult":1,"periodType":"month","start":"2024-01-01"}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"budget.setAmounts","params":{"budget":"00ed0000000000000000000000000002","amounts":[{"account":"Rent","period":4,"amount":"750.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"budget.update","params":{"budget":"00ed0000000000000000000000000002","numPeriods":3}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "numPeriods": 3, "amounts": [], "hidden": { "amounts": 1, "notes": 0 }, "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `budget.update`; absent fields are left alone. - `budget` (Guid, required): The budget. - `name` (string or null): The new name. - `description` (string or null): The new description. - `numPeriods` (integer (uint32) or null): The new number of periods, 1 to 60. Lowering it hides amounts and notes beyond it but keeps them. - `recurrence` (Recurrence or null): The new recurrence: never `once`, weekend adjustment `none`. No amount moves. ## Result A budget. - `guid` (Guid, required): Identity. - `name` (string, required): The name. - `description` (string, required): The description. - `numPeriods` (integer (uint32), required): The number of periods. - `recurrence` (Recurrence, required): The recurrence that gives the periods' dates, as stored. - `isDefault` (boolean, required): True for the default budget. - `periods` (array of PeriodInfo or null): Each period below `numPeriods`; absent in `budget.list`. - `amounts` (array of AmountInfo or null): Every set amount of an account in the tree below `numPeriods`, by account full name then period; absent in `budget.list`. - `notes` (array of NoteInfo or null): Every note likewise; absent in `budget.list`. - `hidden` (SlotCounts, required): Amounts and notes kept at or beyond `numPeriods`. - `orphaned` (SlotCounts, required): Amounts and notes kept for GUIDs that name no account. ## Related - [budget.create](method/budget.create) - [budget.get](method/budget.get) --- *red-ale Manual, `method/budget.update`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # commodity.create Create a security, with the security editor's checks. Creates a security (a stock, fund or other non-currency commodity), with the security editor's checks. Give a `namespace` (an exchange such as `NASDAQ`), a `mnemonic` (the ticker) and a `fullname`; `fraction` is the smallest unit (default 10000), and `quoteFlag` and `quoteSource` set it up for online prices. Currencies cannot be created: the `CURRENCY` namespace is refused with `invalid`, and an existing name with `conflict`. Names with `::` are refused because they would make `NAMESPACE::MNEMONIC` ambiguous. ## Examples *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"commodity.create","params":{"namespace":"NASDAQ","mnemonic":"AAPL","fullname":"Apple Inc","fraction":10000}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "id": "NASDAQ::AAPL", "fullname": "Apple Inc", "fraction": 10000, "isCurrency": false, "builtIn": false, "displaySymbol": "AAPL", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"commodity.create","params":{"namespace":"CURRENCY","mnemonic":"ZZZ","fullname":"Nope"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "error": { "code": 2001, "message": "…", "data": { "help": "error/invalid" } } } ``` **Effect:** `write`, on the Book. ## Params Params of `commodity.create`. - `namespace` (string, required): Namespace (exchange or type), such as `NASDAQ`; not `CURRENCY` or `template`. - `mnemonic` (string, required): Mnemonic (ticker), unique within the namespace. - `fullname` (string, required): Full name; required. - `cusip` (string or null): Exchange code such as a CUSIP or ISIN. - `fraction` (integer (int64)): Smallest fraction, 1 to 1000000000; default 10000. - `quoteFlag` (boolean): Online quotes are wanted. - `quoteSource` (string or null): Quote source internal name, such as `yahoo_json`; unknown names are kept. - `quoteTz` (string or null): Quote time zone, such as `America/New_York`; absent means local time. - `userSymbol` (string or null): Display symbol. ## Result A commodity as GnuCash sees it once the book is loaded. - `id` (CommodityId, required): `NAMESPACE::MNEMONIC`. - `namespace` (string, required): Namespace. - `mnemonic` (string, required): Mnemonic (ticker or ISO code). - `fullname` (string or null): Full name. - `cusip` (string or null): Exchange code (CUSIP, ISIN; the ISO numeric code for a currency). - `fraction` (integer (int64), required): Smallest fraction (SCU). - `isCurrency` (boolean, required): In the `CURRENCY` namespace. - `builtIn` (boolean, required): One of GnuCash's built-in ISO 4217 currencies. - `defined` (boolean, required): Stored in the book file (a security, or a currency with quotes on or slots). - `quoteFlag` (boolean, required): Online quotes are wanted. For a currency an account uses this is on unless the user turned it off. - `quoteSource` (string or null): Quote source internal name; currencies report `currency`. - `quoteSourceType` (string or null): `single`, `multi`, `currency`, or `unknown` for a source GnuCash 5.17 does not know (kept as read). - `quoteTz` (string or null): Quote time zone; null means local time. - `userSymbol` (string or null): The user's display symbol. - `defaultSymbol` (string or null): A currency's built-in symbol. - `displaySymbol` (string, required): The symbol GnuCash shows amounts with: the user symbol, else the default symbol, else the mnemonic. - `usage` (UsageInfo, required): How much of the book refers to it. ## Related - [commodity.update](method/commodity.update) - [account.create](method/account.create) - [invalid](error/invalid) - [conflict](error/conflict) --- *red-ale Manual, `method/commodity.create`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # commodity.delete Delete a security that nothing uses; its prices go too only with deletePrices. Deletes a security that nothing uses. It is refused with `conflict` while an account, a transaction (as its currency) or a business object uses it, or while it has prices, unless `deletePrices` is true, which deletes those prices with it. GnuCash's dialog would leave the prices of a deleted currency dangling; red-ale will not. Currencies cannot be deleted. ## Examples *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"commodity.create","params":{"namespace":"NASDAQ","mnemonic":"AAPL","fullname":"Apple Inc"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"commodity.delete","params":{"commodity":"NASDAQ::AAPL"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "deletedPrices": [] } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"commodity.delete","params":{"commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "error": { "code": 2001, "message": "…", "data": { "help": "error/invalid" } } } ``` **Effect:** `destructive`, on the Book. ## Params Params of `commodity.delete`. - `commodity` (CommodityId, required): The security to delete. - `deletePrices` (boolean): Also delete its prices (either side). Without this, a commodity with prices is not deleted. ## Result What `commodity.delete` removed. - `deletedPrices` (array of Guid, required): The prices deleted with it. ## Related - [commodity.create](method/commodity.create) - [price.removeOld](method/price.removeOld) - [conflict](error/conflict) --- *red-ale Manual, `method/commodity.delete`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # commodity.get Describe one commodity, with how much of the book uses it. Describes one commodity by its `NAMESPACE::MNEMONIC` name (a bare `USD` names a currency): fullname, exchange code, fraction (its smallest unit, `100` for cents), quote settings, symbols and how much of the book uses it. The `displaySymbol` is what GnuCash prints amounts with: the user symbol, else the default symbol, else the mnemonic. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"commodity.get","params":{"commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "id": "CURRENCY::USD", "mnemonic": "USD", "fullname": "US Dollar", "cusip": "840", "fraction": 100, "isCurrency": true, "builtIn": true, "displaySymbol": "$", "…": "…" } } ``` **Effect:** `read`. ## Params Params naming one commodity. - `commodity` (CommodityId, required): The commodity, `NAMESPACE::MNEMONIC` (a bare code is a currency). ## Result A commodity as GnuCash sees it once the book is loaded. - `id` (CommodityId, required): `NAMESPACE::MNEMONIC`. - `namespace` (string, required): Namespace. - `mnemonic` (string, required): Mnemonic (ticker or ISO code). - `fullname` (string or null): Full name. - `cusip` (string or null): Exchange code (CUSIP, ISIN; the ISO numeric code for a currency). - `fraction` (integer (int64), required): Smallest fraction (SCU). - `isCurrency` (boolean, required): In the `CURRENCY` namespace. - `builtIn` (boolean, required): One of GnuCash's built-in ISO 4217 currencies. - `defined` (boolean, required): Stored in the book file (a security, or a currency with quotes on or slots). - `quoteFlag` (boolean, required): Online quotes are wanted. For a currency an account uses this is on unless the user turned it off. - `quoteSource` (string or null): Quote source internal name; currencies report `currency`. - `quoteSourceType` (string or null): `single`, `multi`, `currency`, or `unknown` for a source GnuCash 5.17 does not know (kept as read). - `quoteTz` (string or null): Quote time zone; null means local time. - `userSymbol` (string or null): The user's display symbol. - `defaultSymbol` (string or null): A currency's built-in symbol. - `displaySymbol` (string, required): The symbol GnuCash shows amounts with: the user symbol, else the default symbol, else the mnemonic. - `usage` (UsageInfo, required): How much of the book refers to it. ## Related - [commodity.list](method/commodity.list) - [commodity.update](method/commodity.update) --- *red-ale Manual, `method/commodity.get`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # commodity.list List commodities: the book's own and the built-in ISO 4217 currencies. Lists commodities, sorted by namespace and then mnemonic: the book's own and every built-in currency it does not define. `namespace` limits the list to one namespace; `usedOnly` keeps only those something in the book refers to (an account, a transaction currency, a price, a business object). Each entry says how much of the book uses it. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"commodity.list","params":{"usedOnly":true}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": [ { "id": "CURRENCY::GBP", "fullname": "Pound Sterling", "fraction": 100, "isCurrency": true, "usage": { "accounts": 2, "transactions": 13, "prices": 2, "business": 0 }, "…": "…" }, { "id": "CURRENCY::USD", "fullname": "US Dollar", "fraction": 100, "usage": { "accounts": 8, "transactions": 46, "prices": 2, "business": 0 }, "…": "…" } ] } ``` **Effect:** `read`. ## Params Params of `commodity.list`. - `namespace` (string or null): Only this namespace (`CURRENCY` for the currencies). - `usedOnly` (boolean): Only commodities something in the book uses. ## Result Type: array of CommodityInfo. ## Related - [commodity.get](method/commodity.get) - [commodity.namespaces](method/commodity.namespaces) --- *red-ale Manual, `method/commodity.list`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # commodity.namespaces List the commodity namespaces with how many commodities each holds. Lists the commodity namespaces with how many commodities each holds. `CURRENCY` holds the 227 built-in ISO 4217 currencies; other namespaces are exchanges or types you create securities in (`NASDAQ`, `FUND`). `CURRENCY` and `template` are reserved: no security can be created in them. Note that GnuCash's old name for the currency namespace, `ISO4217`, is accepted as `CURRENCY`. ## Examples *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"commodity.namespaces","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": [ { "name": "CURRENCY", "commodities": 227, "isCurrency": true, "reserved": true }, { "name": "template", "commodities": 1, "isCurrency": false, "reserved": true } ] } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"commodity.create","params":{"namespace":"NASDAQ","mnemonic":"AAPL","fullname":"Apple Inc"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"commodity.namespaces","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": [ { "name": "CURRENCY", "…": "…" }, { "name": "NASDAQ", "commodities": 1, "isCurrency": false, "reserved": false }, "…" ] } ``` **Effect:** `read`. ## Params Params for methods that take none. Type: NoParams. ## Result Type: array of NamespaceInfo. ## Related - [commodity.list](method/commodity.list) - [commodity.create](method/commodity.create) --- *red-ale Manual, `method/commodity.namespaces`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # commodity.update Edit a security (any field, including a rename) or a currency's quote flag, quote time zone and symbol. Edits a security (any field, including its namespace and mnemonic) or a currency's quote flag, quote time zone and symbol. Fields you leave out are kept; `null` clears `cusip`, `quoteSource`, `quoteTz` or `userSymbol`. A currency's other fields are fixed and a change is refused with `invalid`. Renaming a security changes every account, transaction and price that names it. Changing a commodity's `fraction` does not re-round amounts already stored. ## Examples *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"commodity.create","params":{"namespace":"NASDAQ","mnemonic":"AAPL","fullname":"Apple Inc"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"commodity.update","params":{"commodity":"NASDAQ::AAPL","fullname":"Apple Inc.","quoteFlag":true,"quoteSource":"yahoo_json"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "id": "NASDAQ::AAPL", "fullname": "Apple Inc.", "quoteFlag": true, "quoteSource": "yahoo_json", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"commodity.update","params":{"commodity":"EUR","fullname":"Euro, renamed"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "error": { "code": 2001, "message": "…", "data": { "help": "error/invalid" } } } ``` **Effect:** `write`, on the Book. ## Params Params of `commodity.update`. Absent fields are kept; `null` clears an optional one. - `commodity` (CommodityId, required): The commodity to edit. - `namespace` (string or null): New namespace (securities only); renames it everywhere in the book. - `mnemonic` (string or null): New mnemonic (securities only); renames it everywhere in the book. - `fullname` (string or null): New full name (securities only). - `cusip` (string or null): New exchange code (securities only); null or empty clears it. - `fraction` (integer (int64) or null): New smallest fraction (securities only). Stored amounts keep their denominators. - `quoteFlag` (boolean or null): Online quotes wanted. For a currency, a choice that differs from the automatic one is remembered. - `quoteSource` (string or null): New quote source (securities only); null clears it. - `quoteTz` (string or null): New quote time zone; null means local time. - `userSymbol` (string or null): New display symbol; null or empty removes it. ## Result A commodity as GnuCash sees it once the book is loaded. - `id` (CommodityId, required): `NAMESPACE::MNEMONIC`. - `namespace` (string, required): Namespace. - `mnemonic` (string, required): Mnemonic (ticker or ISO code). - `fullname` (string or null): Full name. - `cusip` (string or null): Exchange code (CUSIP, ISIN; the ISO numeric code for a currency). - `fraction` (integer (int64), required): Smallest fraction (SCU). - `isCurrency` (boolean, required): In the `CURRENCY` namespace. - `builtIn` (boolean, required): One of GnuCash's built-in ISO 4217 currencies. - `defined` (boolean, required): Stored in the book file (a security, or a currency with quotes on or slots). - `quoteFlag` (boolean, required): Online quotes are wanted. For a currency an account uses this is on unless the user turned it off. - `quoteSource` (string or null): Quote source internal name; currencies report `currency`. - `quoteSourceType` (string or null): `single`, `multi`, `currency`, or `unknown` for a source GnuCash 5.17 does not know (kept as read). - `quoteTz` (string or null): Quote time zone; null means local time. - `userSymbol` (string or null): The user's display symbol. - `defaultSymbol` (string or null): A currency's built-in symbol. - `displaySymbol` (string, required): The symbol GnuCash shows amounts with: the user symbol, else the default symbol, else the mnemonic. - `usage` (UsageInfo, required): How much of the book refers to it. ## Related - [commodity.get](method/commodity.get) - [commodity.create](method/commodity.create) --- *red-ale Manual, `method/commodity.update`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # config.get The whole Configuration, or one setting by path, with defaults filled in; secrets shown only as set or unset. Reads red-ale's Configuration: the settings GnuCash keeps outside the book (accounting period, document link folder, report options, import settings, quote services, limits). Give a dotted `path` for one setting (`quotes.network`); without it you get the whole Configuration, with defaults filled in and secrets shown only as set or unset. It works with no book open. An unknown path is `invalid-params`. ## Examples *Example: with no book.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"config.get","params":{"path":"quotes.network"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "path": "quotes.network", "value": false, "unknown": [], "problems": [], "configFile": null } } ``` **Effect:** `read`. ## Params Params of `config.get`. - `path` (string or null): A setting path, keys joined with `.` (`import.settings.matchThreshold`, `quotes.services.alphavantage`); absent for the whole Configuration. ## Result The result of `config.get`. - `path` (string or null): The path asked for; `null` for the whole Configuration. - `value` (any, required): The value, defaults filled in, each secret shown as `{"set": true|false}`. `null` for a map entry that does not exist. - `unknown` (array of string, required): Keys in the file, at or below the path, that declare no setting. They are kept and do nothing. - `problems` (array of ProblemInfo, required): Settings, at or below the path, whose values in the file do not match the schema. - `configFile` (string or null): The Configuration file; `null` for a process started with `--no-config`, whose Configuration is in memory. ## Related - [config.set](method/config.set) - [config.schema](method/config.schema) --- *red-ale Manual, `method/config.get`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # config.schema The Configuration's JSON Schema: every setting, its type, default and description. Returns the Configuration's JSON Schema: every setting with its type, default and description. Use it to find the path and the allowed values before calling [config.set](method/config.set). It works with no book open. ## Examples *Example: with no book.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"config.schema","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "title": "red-ale Configuration", "type": "object", "properties": { "accountingPeriod": { "type": "object", "…": "…" }, "…": "…" }, "…": "…" } } ``` **Effect:** `read`. ## Params Params for methods that take none. Type: NoParams. ## Result Type: any. ## Related - [config.get](method/config.get) - [config.set](method/config.set) --- *red-ale Manual, `method/config.schema`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # config.set Change one or more settings by path, validated against the schema, all or none; null restores a default. Changes one or more Configuration settings by path, all or none, validated against [config.schema](method/config.schema). Give `changes` as an object of path to value; a null value restores the default. It changes red-ale's Configuration only, never a book, and works with no book open. Settings that open the network or hold keys (`quotes.network` and the quote services' keys) cannot be changed through the MCP server, only through JSON-RPC or the CLI by a person, so an AI agent cannot switch the network on. ## Examples *Example: with no book.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"config.set","params":{"changes":{"quotes.network":true}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "values": { "quotes.network": true }, "clearedKeys": [], "configFile": null } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"config.set","params":{"changes":{"period.bogus":1}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "error": { "code": -32602, "message": "…", "data": { "problems": [ { "path": "period.bogus", "message": "…" } ], "help": "error/invalid-params" } } } ``` **Effect:** `write`, on the Configuration only. ## Params Params of `config.set`. - `changes` (object, required): Setting paths to their new values; `null` restores a setting's default. No path may lie inside another. ## Result The result of `config.set`. - `values` (object, required): Each path changed, with its value now, as `config.get` shows it. - `clearedKeys` (array of string, required): Keys cleared because their Quote service's URL moved to another host. - `configFile` (string or null): The Configuration file; `null` for a process started with `--no-config`, whose Configuration is in memory. ## Related - [config.get](method/config.get) - [config.schema](method/config.schema) - [invalid-params](error/invalid-params) --- *red-ale Manual, `method/config.set`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # counter.list Every counter: the last number issued, its format and the next ID it would give. Lists the book's counters, which number the business objects (customers, vendors, employees, invoices, bills, expense vouchers, jobs and orders): the last number issued, the format (null for the default `%.6li`) and the next ID each would give. GnuCash raises a counter each time it issues an ID. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"counter.list","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "counters": [ { "name": "gncCustomer", "last": 0, "format": null, "normalizedFormat": "%.6li", "next": "000001", "…": "…" }, "…" ] } } ``` **Effect:** `read`. ## Params Params for methods that take none. Type: NoParams. ## Result The result of `counter.list`. - `counters` (array of CounterInfo, required): The book options' eight counters in their order, then any others the book holds, by name. ## Related - [counter.set](method/counter.set) --- *red-ale Manual, `method/counter.list`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # counter.set Set a counter's last number issued or its format; a null or empty format means the default. Sets a counter's last number issued (`last`) or its format. A format is a C-style `printf` pattern for a `long`, such as `INV-%04li`; a null or empty format means the default. `formatValid` says whether the pattern is one GnuCash accepts, and `next` is the ID the counter will give next, so check it before relying on the format. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"counter.set","params":{"name":"gncInvoice","last":41}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "name": "gncInvoice", "last": 41, "format": null, "next": "000042", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"counter.set","params":{"name":"gncInvoice","format":"INV-%04li"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "name": "gncInvoice", "last": 41, "format": "INV-%04li", "formatValid": true, "next": "INV-0042", "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `counter.set`. - `name` (string, required): One of `gncCustomer`, `gncEmployee`, `gncInvoice`, `gncBill`, `gncExpVoucher`, `gncJob`, `gncOrder`, `gncVendor`. - `last` (integer (int64) or null): The last number issued, from 0 to 999999999; the next ID uses one more. - `format` (string or null): A printf format with one `%li`, `%lli` or `%I64i` conversion; null or empty removes it. ## Result A counter. - `name` (string, required): Its name in the book, such as `gncInvoice`. - `last` (integer (int64), required): The last number issued; 0 when none. - `format` (string or null): The format as stored, if any. - `formatValid` (boolean, required): GnuCash accepts the stored format; when false it numbers with the default. - `normalizedFormat` (string, required): The format GnuCash numbers with: the stored one normalised, else the default `%.6li`. - `next` (string, required): The ID the next object would get. Reading it does not take it. ## Related - [counter.list](method/counter.list) --- *red-ale Manual, `method/counter.set`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # currency.euroConvert Convert between the euro and a currency it replaced, at GnuCash's fixed rates. Converts between the euro and a currency it replaced, at the fixed rates fixed when the euro was introduced: to euros divides by the rate, from euros multiplies, rounding half away from zero to the currency's fraction. One side must be `EUR`. GnuCash returns 0 for a currency with no euro rate; red-ale refuses with `invalid`, so a zero is never taken for an answer. For other pairs use the price database ([price.nearest](method/price.nearest)). ## Examples *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"currency.euroConvert","params":{"amount":"100.00","from":"EUR","to":"DEM"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "amount": { "num": "19558", "denom": "100" }, "rate": { "num": "195583", "denom": "100000" } } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"currency.euroConvert","params":{"amount":"100.00","from":"USD","to":"GBP"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "error": { "code": 2001, "message": "…", "data": { "help": "error/invalid" } } } ``` **Effect:** `read`. ## Params Params of `currency.euroConvert`. - `amount` (Amount, required): The amount, in `from`. - `from` (CommodityId, required): The currency of the amount: `EUR` or a currency the euro replaced. - `to` (CommodityId, required): The currency wanted: `EUR` or a currency the euro replaced; one side must be `EUR`. ## Result The result of `currency.euroConvert`. - `amount` (Amount, required): The converted amount, rounded half away from zero to cents (to EUR) or to the currency's fraction. - `rate` (Amount, required): The fixed rate used: units of the legacy currency per euro. ## Related - [currency.list](method/currency.list) - [transaction.transfer](method/transaction.transfer) --- *red-ale Manual, `method/currency.euroConvert`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # currency.list List GnuCash 5.17's built-in ISO 4217 currencies. Lists GnuCash 5.17's 227 built-in ISO 4217 currencies in code order, with each one's code, name, ISO numeric code (`exchangeCode`), fraction, symbol and, for the euro and the currencies with a fixed rate to it, `euroRate`. Every book can use any of them without defining it first. [commodity.list](method/commodity.list) lists these and the book's own securities together. ## Examples *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"currency.list","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": [ { "id": "CURRENCY::ADF", "code": "ADF", "fullname": "Andorran Franc", "exchangeCode": "950", "fraction": 100, "symbol": "₣", "euroRate": null }, "…" ] } ``` **Effect:** `read`. ## Params Params for methods that take none. Type: NoParams. ## Result Type: array of CurrencyInfo. ## Related - [commodity.list](method/commodity.list) - [currency.euroConvert](method/currency.euroConvert) --- *red-ale Manual, `method/currency.list`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # customer.create Create a customer; its ID comes from the book's counter unless given. Creates a customer: someone you send invoices to. It needs a company `name` and a `currency`, the currency of all its documents; everything else (address, default billing term, tax table, discount, credit limit) is optional. Leave `id` out and the customer is numbered from the book's `gncCustomer` counter (`000001`, `000002`, …); see [counter.set](method/counter.set) to change the counter or its format. As in GnuCash, IDs are labels, not keys: nothing stops two customers having the same one, and the GUID is what identifies a customer. `terms` and `taxTable` take a GUID or the name of a visible billing term or tax table. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"customer.create","params":{"name":"Globex","currency":"EUR","terms":"Net30","discount":"10"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "…", "id": "000002", "name": "Globex", "currency": "CURRENCY::EUR", "terms": "3416d941790749378beeb338b8357a72", "discount": { "num": "10", "denom": "1" }, "active": true, "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `customer.create`. `name` and `currency` are required. - `name` (string or null): Company name. - `id` (string or null): Customer number. On create, absent or empty takes the next number from the book's `gncCustomer` counter. - `currency` (CommodityId or null): The currency of the customer's documents. - `addr` (AddressParams or null): Billing address. - `shipAddr` (AddressParams or null): Shipping address. - `notes` (string or null): Notes. - `terms` (BillTermRef or null): Default billing term for new invoices, by GUID or name; `null` for none. - `taxTable` (TaxTableRef or null): Tax table, by GUID or name; `null` for none. - `taxTableOverride` (boolean or null): New invoice lines use `taxTable` rather than the book's default. - `taxIncluded` (TaxIncludedWire or null): Whether prices include tax by default. - `discount` (Amount or null): Default discount percentage for new invoice lines, 0 to 100. - `credit` (Amount or null): Credit limit. - `active` (boolean or null): Active; `false` deactivates. ## Result A customer. - `guid` (Guid, required): A GUID: 32 hexadecimal digits. - `id` (string, required) - `name` (string, required) - `addr` (AddressInfo, required): An address. Empty strings are unset fields. - `shipAddr` (AddressInfo, required): An address. Empty strings are unset fields. - `notes` (string, required) - `currency` (CommodityId or null) - `terms` (Guid or null) - `taxTable` (Guid or null) - `taxTableOverride` (boolean, required) - `taxIncluded` (TaxIncludedWire, required): Whether prices include tax by default for the contact's documents. - `discount` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `credit` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `active` (boolean, required) ## Related - [customer.update](method/customer.update) - [customer.list](method/customer.list) - [billTerm.create](method/billTerm.create) - [taxTable.create](method/taxTable.create) - [job.create](method/job.create) --- *red-ale Manual, `method/customer.create`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # customer.get A customer. Returns one customer by GUID: its address, currency, default billing term and tax table, discount, credit limit and whether it is active. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"customer.get","params":{"customer":"5b22073fa4e34411b07c14a77147ce6b"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "5b22073fa4e34411b07c14a77147ce6b", "id": "000001", "name": "Acme & Sons ", "currency": "CURRENCY::EUR", "taxIncluded": "no", "credit": { "num": "100000", "denom": "100" }, "active": true, "…": "…" } } ``` **Effect:** `read`. ## Params Names one customer. - `customer` (Guid, required): The customer. ## Result A customer. - `guid` (Guid, required): A GUID: 32 hexadecimal digits. - `id` (string, required) - `name` (string, required) - `addr` (AddressInfo, required): An address. Empty strings are unset fields. - `shipAddr` (AddressInfo, required): An address. Empty strings are unset fields. - `notes` (string, required) - `currency` (CommodityId or null) - `terms` (Guid or null) - `taxTable` (Guid or null) - `taxTableOverride` (boolean, required) - `taxIncluded` (TaxIncludedWire, required): Whether prices include tax by default for the contact's documents. - `discount` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `credit` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `active` (boolean, required) ## Related - [customer.list](method/customer.list) - [customer.update](method/customer.update) --- *red-ale Manual, `method/customer.get`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # customer.list Customers, optionally filtered by name, ID or active state. Lists customers, in GUID order, optionally only the active ones or those whose name contains some text (any case) or whose ID matches exactly. Use it to find a customer's GUID from what you know of it. Deactivated customers are listed unless `activeOnly` is set. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"customer.list","params":{"name":"acme"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "customers": [ { "guid": "5b22073fa4e34411b07c14a77147ce6b", "name": "Acme & Sons ", "…": "…" } ] } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"customer.list","params":{"name":"globex"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "customers": [] } } ``` **Effect:** `read`. ## Params Filters for the contact lists. All given filters must match. - `activeOnly` (boolean): Only active contacts. - `name` (string or null): Case-insensitive part of the name. - `id` (string or null): The exact ID. IDs are not unique in GnuCash, so several may match. ## Result Customers. - `customers` (array of CustomerInfo, required): In GUID order. ## Related - [customer.get](method/customer.get) - [vendor.list](method/vendor.list) - [job.list](method/job.list) --- *red-ale Manual, `method/customer.list`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # customer.update Change a customer; `active: false` deactivates it. Changes the fields of a customer you name; fields you leave out stay as they are. `null` clears a field that can be empty (`terms`, `taxTable`), and `addr` and `shipAddr` merge field by field, so `{"addr": {"phone": "555-9999"}}` changes the phone number alone. There is no way to delete a customer, as there is none in GnuCash: its documents would be left without an owner. Set `active: false` instead. A deactivated customer is still in the book and keeps its documents. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"customer.update","params":{"customer":"5b22073fa4e34411b07c14a77147ce6b","active":false,"addr":{"phone":"555-9999"}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "5b22073fa4e34411b07c14a77147ce6b", "addr": { "name": "Acme Billing", "addr1": "1 Main St", "phone": "555-9999", "…": "…" }, "active": false, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"customer.list","params":{"activeOnly":true}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "customers": [] } } ``` **Effect:** `write`, on the Book. ## Params Params of `customer.update`: the fields to change. - `customer` (Guid, required): The customer. - `name` (string or null): Company name. - `id` (string or null): Customer number. On create, absent or empty takes the next number from the book's `gncCustomer` counter. - `currency` (CommodityId or null): The currency of the customer's documents. - `addr` (AddressParams or null): Billing address. - `shipAddr` (AddressParams or null): Shipping address. - `notes` (string or null): Notes. - `terms` (BillTermRef or null): Default billing term for new invoices, by GUID or name; `null` for none. - `taxTable` (TaxTableRef or null): Tax table, by GUID or name; `null` for none. - `taxTableOverride` (boolean or null): New invoice lines use `taxTable` rather than the book's default. - `taxIncluded` (TaxIncludedWire or null): Whether prices include tax by default. - `discount` (Amount or null): Default discount percentage for new invoice lines, 0 to 100. - `credit` (Amount or null): Credit limit. - `active` (boolean or null): Active; `false` deactivates. ## Result A customer. - `guid` (Guid, required): A GUID: 32 hexadecimal digits. - `id` (string, required) - `name` (string, required) - `addr` (AddressInfo, required): An address. Empty strings are unset fields. - `shipAddr` (AddressInfo, required): An address. Empty strings are unset fields. - `notes` (string, required) - `currency` (CommodityId or null) - `terms` (Guid or null) - `taxTable` (Guid or null) - `taxTableOverride` (boolean, required) - `taxIncluded` (TaxIncludedWire, required): Whether prices include tax by default for the contact's documents. - `discount` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `credit` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `active` (boolean, required) ## Related - [customer.create](method/customer.create) - [customer.get](method/customer.get) --- *red-ale Manual, `method/customer.update`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # docLink.documents Invoices, bills and vouchers with a document link, with the URI each one opens. Lists the business documents (invoices, bills and expense vouchers) that have a document link, with the URI each one opens. It is the counterpart of [docLink.transactions](method/docLink.transactions) for the business side. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"docLink.documents","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "pathHead": null, "links": [] } } ``` **Effect:** `read`. ## Params Params for methods that take none. Type: NoParams. ## Result The links of one kind, with the path head they were resolved against. - `pathHead` (string or null): The configured path head, if any. - `links` (array of DocumentLink, required): The links. ## Related - [docLink.transactions](method/docLink.transactions) - [docLink.pathHead](method/docLink.pathHead) --- *red-ale Manual, `method/docLink.documents`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # docLink.pathHead The configured folder relative document links start from. Reads the folder that relative document links start from, as a `file://` URI, or null when none is set. A document link on a transaction or business document that is a relative path is opened from this folder. It is kept in red-ale's Configuration, not in the book, so the call works with no book open. ## Examples *Example: with no book.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"docLink.pathHead","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "pathHead": null, "configFile": null } } ``` **Effect:** `read`. ## Params Params for methods that take none. Type: NoParams. ## Result The path head setting. - `pathHead` (string or null): The path head, a `file://` URI ending in `/`, if configured. - `configFile` (string or null): The configuration file, if the setting is kept in one; otherwise it lasts as long as the server. ## Related - [docLink.setPathHead](method/docLink.setPathHead) - [docLink.transactions](method/docLink.transactions) --- *red-ale Manual, `method/docLink.pathHead`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # docLink.setPathHead Set or remove the folder relative document links start from, in red-ale's configuration. Sets the folder relative document links start from, or removes it with null. Give a directory path or `file://` URI; the stored form is a `file://` URI ending in `/`. It changes red-ale's Configuration only, never the book. ## Examples *Example: with no book.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"docLink.setPathHead","params":{"pathHead":"/home/me/receipts"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "pathHead": "file:///home/me/receipts/", "configFile": null } } ``` **Effect:** `write`, on the Configuration only. ## Params Params of `docLink.setPathHead`. - `pathHead` (string or null): An absolute path or a `file://` URI; a trailing `/` is added. Absent or `null` removes the setting. ## Result The path head setting. - `pathHead` (string or null): The path head, a `file://` URI ending in `/`, if configured. - `configFile` (string or null): The configuration file, if the setting is kept in one; otherwise it lasts as long as the server. ## Related - [docLink.pathHead](method/docLink.pathHead) - [docLink.transactions](method/docLink.transactions) --- *red-ale Manual, `method/docLink.setPathHead`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # docLink.transactions Transactions with a document link, with the URI each one opens. Lists the transactions that have a document link, each with the link as stored, whether it is relative and the full `uri` it opens (the link resolved against the path head). Set a link with the `docLink` param of [transaction.post](method/transaction.post) or [transaction.update](method/transaction.update); an empty string removes it. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"docLink.setPathHead","params":{"pathHead":"/home/me/receipts"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"transaction.update","params":{"guid":"c0000000000000000000000000000005","docLink":"may/fuel.pdf"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"docLink.transactions","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "pathHead": "file:///home/me/receipts/", "links": [ { "transaction": "c0000000000000000000000000000005", "docLink": "may/fuel.pdf", "relative": true, "uri": "file:///home/me/receipts/may/fuel.pdf", "…": "…" } ] } } ``` **Effect:** `read`. ## Params Params for methods that take none. Type: NoParams. ## Result The links of one kind, with the path head they were resolved against. - `pathHead` (string or null): The configured path head, if any. - `links` (array of TransactionLink, required): The links. ## Related - [docLink.documents](method/docLink.documents) - [docLink.pathHead](method/docLink.pathHead) - [transaction.update](method/transaction.update) --- *red-ale Manual, `method/docLink.transactions`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # employee.create Create an employee; its ID comes from the book's counter unless given. Creates an employee: the owner of expense vouchers. It needs a `name` and a `currency`. GnuCash keeps an employee's name as the name of its address, so `name` overrides `addr.name`. `rate` is the hourly rate and `workday` the hours per day; `creditCardAccount`, if given, must be a `CREDIT` account, which card-paid voucher lines are charged to when the voucher is posted. GnuCash's engine accepts any account here and only its dialog offers credit cards; red-ale refuses the rest. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"employee.create","params":{"name":"John Roe","currency":"EUR","rate":"30.00"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "…", "name": "John Roe", "rate": { "num": "3000", "denom": "100" }, "creditCardAccount": null, "active": true, "…": "…" } } ``` A card account that is not a credit card is refused: *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"employee.create","params":{"name":"John Roe","currency":"EUR","creditCardAccount":"1d8f8d4a358c4a169b3421d953b40369"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": 2001, "message": "the credit card account must be of type CREDIT, not PAYABLE", "data": { "help": "error/invalid" } } } ``` **Effect:** `write`, on the Book. ## Params Params of `employee.create`. `name` and `currency` are required. - `name` (string or null): The employee's name, which GnuCash keeps as the address name; it overrides `addr.name`. - `id` (string or null): Employee number. On create, absent or empty takes the next number from the book's `gncEmployee` counter. - `username` (string or null): User name. - `currency` (CommodityId or null): The currency of the employee's expense vouchers. - `addr` (AddressParams or null): Payment address. - `language` (string or null): Language. - `acl` (string or null): Access control list (stored only). - `workday` (Amount or null): Working hours per day. - `rate` (Amount or null): Hourly rate. - `creditCardAccount` (AccountRef or null): The company credit card account (type CREDIT) card-paid expenses are charged to; `null` for none. - `active` (boolean or null): Active; `false` deactivates. ## Result An employee. - `guid` (Guid, required): A GUID: 32 hexadecimal digits. - `id` (string, required) - `name` (string, required): The address name. - `username` (string, required) - `addr` (AddressInfo, required): An address. Empty strings are unset fields. - `language` (string, required) - `acl` (string, required) - `workday` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `rate` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `currency` (CommodityId or null) - `creditCardAccount` (Guid or null) - `active` (boolean, required) ## Related - [employee.update](method/employee.update) - [invoice.create](method/invoice.create) --- *red-ale Manual, `method/employee.create`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # employee.get An employee. Returns one employee by GUID. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"employee.get","params":{"employee":"7f0d801fdccd48198abec7b197e55581"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "7f0d801fdccd48198abec7b197e55581", "name": "Jane Doe", "username": "jdoe", "rate": { "num": "4250", "denom": "100" }, "…": "…" } } ``` **Effect:** `read`. ## Params Names one employee. - `employee` (Guid, required): The employee. ## Result An employee. - `guid` (Guid, required): A GUID: 32 hexadecimal digits. - `id` (string, required) - `name` (string, required): The address name. - `username` (string, required) - `addr` (AddressInfo, required): An address. Empty strings are unset fields. - `language` (string, required) - `acl` (string, required) - `workday` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `rate` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `currency` (CommodityId or null) - `creditCardAccount` (Guid or null) - `active` (boolean, required) ## Related - [employee.list](method/employee.list) - [employee.update](method/employee.update) --- *red-ale Manual, `method/employee.get`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # employee.list Employees, optionally filtered by name, ID or active state. Lists employees, in GUID order, optionally only the active ones, those whose name contains some text (any case) or those with an exact ID. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"employee.list","params":{"activeOnly":true}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "employees": [ { "guid": "7f0d801fdccd48198abec7b197e55581", "name": "Jane Doe", "…": "…" } ] } } ``` **Effect:** `read`. ## Params Filters for the contact lists. All given filters must match. - `activeOnly` (boolean): Only active contacts. - `name` (string or null): Case-insensitive part of the name. - `id` (string or null): The exact ID. IDs are not unique in GnuCash, so several may match. ## Result Employees. - `employees` (array of EmployeeInfo, required): In GUID order. ## Related - [employee.get](method/employee.get) - [customer.list](method/customer.list) --- *red-ale Manual, `method/employee.list`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # employee.update Change an employee; `active: false` deactivates it. Changes the fields of an employee you name; fields you leave out stay as they are, and `null` clears `creditCardAccount`. Employees cannot be deleted; set `active: false`. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"employee.update","params":{"employee":"7f0d801fdccd48198abec7b197e55581","rate":"45.00"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "7f0d801fdccd48198abec7b197e55581", "rate": { "num": "4500", "denom": "100" }, "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `employee.update`: the fields to change. - `employee` (Guid, required): The employee. - `name` (string or null): The employee's name, which GnuCash keeps as the address name; it overrides `addr.name`. - `id` (string or null): Employee number. On create, absent or empty takes the next number from the book's `gncEmployee` counter. - `username` (string or null): User name. - `currency` (CommodityId or null): The currency of the employee's expense vouchers. - `addr` (AddressParams or null): Payment address. - `language` (string or null): Language. - `acl` (string or null): Access control list (stored only). - `workday` (Amount or null): Working hours per day. - `rate` (Amount or null): Hourly rate. - `creditCardAccount` (AccountRef or null): The company credit card account (type CREDIT) card-paid expenses are charged to; `null` for none. - `active` (boolean or null): Active; `false` deactivates. ## Result An employee. - `guid` (Guid, required): A GUID: 32 hexadecimal digits. - `id` (string, required) - `name` (string, required): The address name. - `username` (string, required) - `addr` (AddressInfo, required): An address. Empty strings are unset fields. - `language` (string, required) - `acl` (string, required) - `workday` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `rate` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `currency` (CommodityId or null) - `creditCardAccount` (Guid or null) - `active` (boolean, required) ## Related - [employee.create](method/employee.create) - [employee.get](method/employee.get) --- *red-ale Manual, `method/employee.update`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # export.accounts Write a new book file holding the open book's account tree and commodities, and no transactions. Never overwrites a file. Writes a new book file with the open book's account tree and commodities and no transactions: a chart of accounts to start another book from. It never overwrites a file: a path that exists is refused with `file-exists`. `.gnucash` is added when missing. The open book is not changed. ## Examples *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"export.accounts","params":{"path":"chart"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "path": "…", "accounts": 2, "commodities": 2 } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"export.accounts","params":{"path":"chart"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "error": { "code": 1007, "message": "…", "data": { "path": "…", "help": "error/file-exists" } } } ``` **Effect:** `read`. ## Params Params of `export.accounts`. - `path` (string, required): The new book file: a path or `xml://` URI that does not exist. `.gnucash` is added when missing. ## Result The result of `export.accounts`. - `path` (string, required): The file written, uncompressed. - `accounts` (integer (uint), required): Account elements written, the root account's included. - `commodities` (integer (uint), required): Commodity elements written. ## Related - [export.csvTree](method/export.csvTree) - [book.create](method/book.create) --- *red-ale Manual, `method/export.accounts`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # export.csvTransactions Transactions of some accounts and dates as CSV text, in GnuCash's simple or complex layout. Writes no file. Returns the transactions of some accounts, between two dates, as CSV text in GnuCash's Export Transactions to CSV layout. It writes no file. `layout: complex` (the default) writes one line per split with the transaction's ID; `simple` writes one line per transaction, for its split in the exported account. A transaction is written once, under the first account in `accounts` it has a split in, so the order of `accounts` matters. Dates and numbers follow the Locale (the `locale` setting, or `locale` for this call), so the default `C` locale gives `06/03/24` and `$3.50`. In the simple layout the header says `Account Name` but the column holds the full name, as in GnuCash. ## Examples *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Food","type":"EXPENSE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"transaction.post","params":{"datePosted":"2024-06-03","description":"Coffee","splits":[{"account":"Food","value":"3.50"},{"account":"Checking","value":"-3.50"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"export.csvTransactions","params":{"accounts":["Checking"],"layout":"simple"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "csv": "Date,Account Name,Number,Description,Full Category Path,Reconcile,Amount With Sym,Amount Num.,Value With Sym,Value Num.,Rate/Price\r\n06/03/24,Checking,,Coffee,Food,n,-$3.50,-3.50,-$3.50,-3.50,1.00\r\n", "transactions": 1, "lines": 1 } } ``` Request: ```json {"jsonrpc":"2.0","id":5,"method":"export.csvTransactions","params":{"accounts":["Checking"],"from":"2024-07-01"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 5, "result": { "transactions": 0, "lines": 0, "…": "…" } } ``` **Effect:** `read`. ## Params Params of `export.csvTransactions`. - `accounts` (array of AccountRef, required): The accounts, at least one, in the order to process them; a transaction goes under the first one it has a split in. Sub-accounts are not included unless listed. - `from` (Date or null): Posted on or after local 00:00:00 of this date; by default the earliest. - `to` (Date or null): Posted on or before local 23:59:59 of this date; by default the latest. - `layout` (LayoutParam): `simple` or `complex` (the default). - `separator` (string): The field separator: any non-empty string. - `quotes` (boolean): Quote every field. - `locale` (string or null): The Locale to format numbers and dates in: a supported POSIX locale name (`fr_FR`, `C`) or `environment`; by default the Configuration's `locale` setting. ## Result The result of `export.csvTransactions`. - `csv` (string, required): The CSV text: UTF-8, every line ending in CRLF, the header first. - `transactions` (integer (uint), required): Transactions written. - `lines` (integer (uint), required): Lines written, the header not counted. ## Related - [export.csvTree](method/export.csvTree) - [import.preview](method/import.preview) - [transaction.list](method/transaction.list) --- *red-ale Manual, `method/export.csvTransactions`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # export.csvTree The account tree as CSV text, as GnuCash's CSV export writes it. Writes no file. Returns the account tree as CSV text, in the layout of GnuCash's Export Account Tree to CSV, which GnuCash's and red-ale's [account import](method/import.preview) read back. It writes no file: the text is in `csv`, with `rows` for the number of accounts. Fields are quoted only when they hold the separator, a quote or a line break, unless `quotes` is set. Siblings come in book order but are sorted by name bytewise, where GnuCash sorts by locale. ## Examples *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"export.csvTree","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "csv": "Type,Full Account Name,Account Name,Account Code,Description,Account Color,Notes,Symbol,Namespace,Hidden,Tax Info,Placeholder\r\nBANK,Checking,Checking,,,,,USD,CURRENCY,F,F,F\r\n", "rows": 1 } } ``` **Effect:** `read`. ## Params Params of `export.csvTree`. - `separator` (string): The field separator: any non-empty string. - `quotes` (boolean): Quote every field. Without it, a field is quoted only when it holds the separator, a quote or a line break. ## Result The result of `export.csvTree`. - `csv` (string, required): The CSV text: UTF-8, every line ending in CRLF, the header first. - `rows` (integer (uint), required): Account lines, the header not counted. ## Related - [export.csvTransactions](method/export.csvTransactions) - [export.accounts](method/export.accounts) - [import.preview](method/import.preview) --- *red-ale Manual, `method/export.csvTree`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # help.get One Page of the Manual, by Page ID or method name, as Markdown or text, with its Examples for one door. Returns one Page of the Manual by Page ID (`error/unbalanced`) or by method name (`transaction.post`), as Markdown or plain text (`format`), with its Examples written for one door (`door`: `jsonrpc`, `cli` or `mcp`). The same Pages are available as MCP resources and through `red-ale help`. An unknown Page is `not-found`. ## Examples *Example: with no book.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"help.get","params":{"id":"error/unbalanced"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "id": "error/unbalanced", "kind": "error", "title": "unbalanced", "format": "markdown", "door": "jsonrpc", "content": "…", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"help.get","params":{"id":"transaction.post","door":"cli","format":"text"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "id": "method/transaction.post", "kind": "method", "format": "text", "door": "cli", "…": "…" } } ``` **Effect:** `read`. ## Params Params of `help.get`. - `id` (string, required): The Page ID (`method/transaction.post`), or a method's, error code's or report template's name (`transaction.post`, `unbalanced`, `Balance Sheet`). - `format` (PageFormat): `markdown` (the default) or `text`. - `door` (PageDoor): Which door the Examples are shown for: `jsonrpc` (the default), `cli` or `mcp`. ## Result Result of `help.get`. - `id` (string, required): The Page ID. - `kind` (PageKind, required): What the Page is about. - `title` (string, required): The title. - `summary` (string, required): One line on what it covers. - `related` (array of string, required): The Page IDs of related Pages. - `from` (string or null): The section of GnuCash's documentation the Page adapts, if any. - `format` (PageFormat, required): The format of `content`. - `door` (PageDoor, required): The door `content` shows Examples for. - `content` (string, required): The Page, ending with its licence notice. ## Related - [help.topics](method/help.topics) - [help.search](method/help.search) --- *red-ale Manual, `method/help.get`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # help.search Pages of the Manual ranked for a question in your own words, best first, each with a snippet. Ranks the Manual's Pages for a question in your own words, best first, each with a snippet. Search is offline and deterministic, and knows GnuCash's words: "quantity" finds *amount*, "bill" finds *document*, a menu path such as "Stock Split" finds the Page for that menu item. Give `kind` to search one kind of Page and `limit` to cap the hits. ## Examples A method's own Page ranks first for the words of its name, ahead of an error that shares them: *Example: with no book.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"help.search","params":{"query":"open a book","limit":2}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "hits": [ { "id": "method/book.open", "kind": "method", "title": "book.open", "summary": "…", "snippet": "…" }, { "id": "error/book-already-open", "kind": "error", "title": "book-already-open", "summary": "…", "snippet": "…" } ] } } ``` *Example: with no book.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"help.search","params":{"query":"transaction does not balance","kind":"error","limit":2}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "hits": [ { "id": "error/unbalanced", "kind": "error", "title": "unbalanced", "summary": "…", "snippet": "…" }, "…" ] } } ``` **Effect:** `read`. ## Params Params of `help.search`. - `query` (string, required): What to look for, in any words: a question, a GnuCash menu item ("Stock Split…"), a method name. - `kind` (PageKind or null): Only Pages of this kind. - `limit` (integer (uint32) or null): The most Pages to return, 1 to 100; 10 by default. ## Result Result of `help.search`. - `hits` (array of HelpHit, required): The Pages found, best first; ties in Page ID order. ## Related - [help.topics](method/help.topics) - [help.get](method/help.get) --- *red-ale Manual, `method/help.search`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # help.topics Every Page of red-ale's Manual, or those of one kind: Page ID, kind, title and summary. Lists the Pages of red-ale's Manual: Page ID, kind (`method`, `error`, `report`, `concept`, `guide`, `gnucash`, …), title and summary. Give `kind` to list one kind. Start here to see what the Manual covers, then read a Page with [help.get](method/help.get). It works with no book open. ## Examples *Example: with no book.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"help.topics","params":{"kind":"error"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "topics": [ { "id": "error/arithmetic", "kind": "error", "title": "arithmetic", "summary": "…" }, "…" ] } } ``` **Effect:** `read`. ## Params Params of `help.topics`. - `kind` (PageKind or null): Only Pages of this kind; every Page by default. ## Result Result of `help.topics`. - `topics` (array of HelpTopic, required): The Pages, by Page ID. ## Related - [help.get](method/help.get) - [help.search](method/help.search) --- *red-ale Manual, `method/help.topics`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # import.apply Apply a held Import proposal with the caller's changes, as one Mutation. Applies a held Import proposal as one change, with the changes you make to it, or does nothing. It is destructive: it adds transactions, accounts, prices, documents or customers to the book. `changes` alter a record by its `index`: a new `action` (`add`, `clear`, `update`, `skip`; `clear` and `update` need a `match`, the split GUID of one of the transaction's `matches`), and for an `add` the `account` that balances it and its `amount` when that account is in another commodity. The account you choose is learned into the import map, so the next file is proposed with it. Records you do not name keep the proposal's choice. Errors in the proposal stop the apply unless you pass `skipErrors`, which leaves those rows out. The result lists what was added, cleared, updated and skipped, the accounts and commodities created, every `Imbalance-` split made, and what was learned. A proposal stays held after a failed apply, so you can fix it and try again. If the book has changed since the preview, the proposal is refused with `conflict`: preview again. ## Examples A proposal that is not held, because it was applied, discarded, pushed out or made before the book was opened, is refused: *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"import.apply","params":{"proposal":"imp-999999"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": 2000, "message": "…", "data": { "kind": "importProposal", "id": "imp-999999", "help": "error/not-found" } } } ``` A bank statement previewed and applied, giving Food as the account that balances Coffee. Proposal IDs count up from `imp-1` in each server. Lunch, given no account, is balanced against `Imbalance-USD`: *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Food","type":"EXPENSE","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"import.preview","params":{"format":"csvTransactions","files":[{"name":"bank.csv","text":"Date,Description,Amount\n2024-06-03,Coffee,-3.50\n2024-06-04,Lunch,-12.00\n"}],"layout":{"format":"csv","separators":",","skipStartLines":1,"dateFormat":"y-m-d","currencyFormat":"period","encoding":"utf-8","baseAccount":"Checking","columns":["Date","Description","Amount"]}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "id": "imp-1", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"import.apply","params":{"proposal":"imp-1","changes":[{"index":0,"account":"Food"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "result": { "added": [ { "index": 0, "transaction": "…" }, { "index": 1, "transaction": "…" } ], "skipped": [], "imbalanceSplits": [ { "index": 1, "account": "…", "value": { "num": "1200", "denom": "100" }, "…": "…" } ], "learned": "…", "warnings": "…", "…": "…" } } ``` **Effect:** `destructive`, on the Book. ## Params The params of `import.apply`. - `proposal` (string, required): The proposal's ID. - `changes` (array of ChangeParam): The caller's changes, by index. - `skipErrors` (boolean): Apply although the proposal lists errors, leaving those rows out (GnuCash's "Skip errors"). - `appendText` (boolean or null): For *update*: append the imported description and notes instead of replacing them. Default: the import account's `import-append-text` slot, as GnuCash's checkbox defaults. ## Result The result of `import.apply`. - `added` (array of IndexedTransaction, required): Transactions added. - `cleared` (array of IndexedTransaction, required): Existing transactions cleared. - `updated` (array of IndexedTransaction, required): Existing transactions updated and cleared. - `skipped` (array of integer (uint), required): Indexes skipped: transactions, or a CSV account or price import's rows. - `accounts` (AccountsChanged, required): Accounts created and changed. - `commodities` (array of string, required): Commodities created, as `NAMESPACE::MNEMONIC` (QIF securities); none for CSV. - `prices` (PricesChanged, required): Prices recorded. - `imbalanceSplits` (array of ImbalanceSplitWire, required): Every `Imbalance-` split made. - `learned` (LearnedWire, required): Import map entries written. - `warnings` (array of WarningWire, required): Every Imbalance split again, every transaction applied read-only by date, and the matcher's own warnings. - `documents` (RecordsChanged or null): `csvDocuments`: the documents created, updated (entries appended) and posted. - `owners` (RecordsChanged or null): `csvOwners`: the customers or vendors created and updated. ## Related - [import.preview](method/import.preview) - [import.discard](method/import.discard) - [importMap.list](method/importMap.list) --- *red-ale Manual, `method/import.apply`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # import.discard Drop a held Import proposal. Drops a held Import proposal without applying it. Proposals are also dropped when applied, when 16 newer ones push them out and when the book closes, so discarding is only for tidiness. It changes nothing in the book. ## Examples *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"import.discard","params":{"proposal":"imp-999999"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": 2000, "message": "…", "data": { "kind": "importProposal", "id": "imp-999999", "help": "error/not-found" } } } ``` A held proposal is dropped, and is then gone: *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"import.preview","params":{"format":"csvPrices","files":[{"text":"2024-06-28,1.0850\n"}],"layout":{"format":"csv","separators":",","skipStartLines":0,"dateFormat":"y-m-d","currencyFormat":"period","encoding":"utf-8","columns":["Date","Amount"],"fromCommodity":"CURRENCY::EUR","toCurrency":"USD"}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "id": "imp-1", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"import.discard","params":{"proposal":"imp-1"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "discarded": true } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"import.apply","params":{"proposal":"imp-1"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "error": { "code": 2000, "message": "…", "data": { "kind": "importProposal", "id": "imp-1", "help": "error/not-found" } } } ``` **Effect:** `read`. ## Params The params of `import.discard`. - `proposal` (string, required): The proposal's ID. ## Result The result of `import.discard`. - `discarded` (boolean, required): Always true. ## Related - [import.preview](method/import.preview) - [import.apply](method/import.apply) --- *red-ale Manual, `method/import.discard`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # import.preview Read a file and propose what importing it would do: the Import proposal, held by ID. Changes nothing. Reads a file and says what importing it would do, without changing the book. The answer, the Import proposal, is held under an `id` until you [apply](method/import.apply) or [discard](method/import.discard) it. Nothing reaches the book without a preview first, whatever the format. `format` is one of `csvTransactions` (GnuCash's Import Transactions from CSV), `qif` (Import QIF), `csvAccounts`, `csvPrices`, `csvDocuments` (Import Bills & Invoices) and `csvOwners` (Import Customers & Vendors). The file's content goes in `files` as `text`, or as `base64` with an `encoding`; there is no path to read. Only QIF takes several files. The other params depend on the format: for CSV transactions and prices, a `layout`, by name or written out whole, which says the separator, the date and number formats and what each column is. Only CSV transactions go through GnuCash's duplicate matcher (`action` is `add`, `clear`, `update` or `skip` for each transaction, with `matches` to choose from). A transaction that does not balance is not refused, as in GnuCash: applying it adds an `Imbalance-` split, and the proposal flags it with `imbalance` beforehand. Rows that cannot be imported are listed in `errors` with GnuCash's own messages and are left out. Proposal IDs (`imp-1`, …) count up from 1 in each server and are never reused while it runs, so a proposal made before the book was opened, or pushed out by 16 newer ones, is gone. Applying a proposal made at an older revision of the book is refused. ## Examples A bank's statement in a CSV file, as a layout with a base account describes it. The transfer account is unknown, so each transaction would be balanced against `Imbalance-USD`; give the account at `import.apply`. *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Checking","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"import.preview","params":{"format":"csvTransactions","files":[{"name":"bank.csv","text":"Date,Description,Amount\n2024-06-03,Coffee,-3.50\n2024-06-04,Lunch,-12.00\n"}],"layout":{"format":"csv","separators":",","skipStartLines":1,"dateFormat":"y-m-d","currencyFormat":"period","encoding":"utf-8","baseAccount":"Checking","columns":["Date","Description","Amount"]}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "id": "…", "format": "csvTransactions", "summary": { "add": 2, "imbalanced": 2, "errors": 0, "…": "…" }, "newAccounts": [ { "name": "Imbalance-USD", "type": "BANK", "commodity": "CURRENCY::USD" } ], "transactions": [ { "index": 0, "description": "Coffee", "datePosted": "2024-06-03", "action": "add", "splits": [ { "accountName": "Checking", "value": { "num": "-350", "denom": "100" }, "…": "…" } ], "imbalance": { "value": { "num": "350", "denom": "100" }, "…": "…" }, "…": "…" }, { "index": 1, "description": "Lunch", "…": "…" } ], "…": "…" } } ``` The base account can also be given beside the layout, which overrides the layout's own or gives one to a layout that has none, as choosing the account in GnuCash's assistant does. A saved layout can then serve several accounts: *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Savings","type":"BANK","commodity":"USD"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"import.preview","params":{"format":"csvTransactions","files":[{"text":"2024-06-03,Interest,1.25\n"}],"layout":{"format":"csv","separators":",","dateFormat":"y-m-d","currencyFormat":"period","encoding":"utf-8","columns":["Date","Description","Amount"]},"baseAccount":"Savings"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "transactions": [ { "index": 0, "description": "Interest", "splits": [ { "accountName": "Savings", "value": { "num": "125", "denom": "100" }, "…": "…" } ], "…": "…" } ], "…": "…" } } ``` In a book that has imported before, the Bayesian matcher proposes the account the same words and weekday went to last time (`from: "bayes"`), so `import.apply` needs no account for them: *Example: with a copy of the `synthetic/import-map` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"import.preview","params":{"format":"csvTransactions","files":[{"text":"2024-06-03,Corner Grocer,-23.40\n2024-06-28,Salary ACME,2000.00\n"}],"layout":{"columns":["Date","Description","Amount"],"dateFormat":"y-m-d"},"baseAccount":"Assets:Checking"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "transactions": [ { "description": "Corner Grocer", "action": "add", "other": { "accountName": "Expenses:Groceries", "from": "bayes", "…": "…" }, "…": "…" }, { "description": "Salary ACME", "other": { "accountName": "Income:Salary", "from": "bayes", "…": "…" }, "…": "…" } ], "…": "…" } } ``` Prices from a file with a date and a rate on each line: *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"import.preview","params":{"format":"csvPrices","files":[{"text":"2024-06-28,1.0850\n"}],"layout":{"format":"csv","separators":",","skipStartLines":0,"dateFormat":"y-m-d","currencyFormat":"period","encoding":"utf-8","columns":["Date","Amount"],"fromCommodity":"CURRENCY::EUR","toCurrency":"USD"}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "id": "…", "format": "csvPrices", "summary": { "add": 1, "errors": 0, "…": "…" }, "prices": [ { "index": 0, "commodity": "CURRENCY::EUR", "currency": "CURRENCY::USD", "date": "2024-06-28", "amount": { "num": "10850", "denom": "10000" }, "action": "add", "existing": null, "…": "…" } ], "…": "…" } } ``` Accounts, in the layout GnuCash's account export writes: *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"import.preview","params":{"format":"csvAccounts","files":[{"text":"Type,Full Account Name,Account Name,Account Code,Description,Account Color,Notes,Symbol,Namespace,Hidden,Tax Info,Placeholder\nBANK,Savings,Savings,,,,,USD,CURRENCY,F,F,F\n"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "id": "…", "format": "csvAccounts", "newAccounts": [ { "name": "Savings", "type": "BANK", "commodity": "CURRENCY::USD" } ], "accounts": [ { "index": 0, "fullName": "Savings", "action": "add", "…": "…" } ], "…": "…" } } ``` **Effect:** `read`. ## Params The params of `import.preview`: the common ones and each format's own, chosen by `format`. Type: PreviewParam. ## Result The Import proposal. - `id` (string, required): The proposal's ID, for `import.apply` and `import.discard`. - `format` (string, required): The format, as given. - `bookRevision` (integer (uint64), required): The Book revision it was made at: the number of Mutations the session had applied. - `thresholdDate` (Date or null): The auto read-only threshold date at the time of the preview, or null with no threshold. - `summary` (Summary, required): Counts. - `ignoredLines` (array of IgnoredLineWire, required): Lines the reader skipped. - `errors` (array of RowErrorWire, required): Rows that can't be imported, with GnuCash's message. None of their records appear below. - `warnings` (array of WarningWire, required): Things the caller should know about the whole import; each transaction's own are in its `warnings`. - `newAccounts` (array of NewAccountWire, required): Accounts the import will create, by full name, parents first. - `newCommodities` (array of NewCommodityWire, required): Commodities the import will create (QIF securities); none for CSV. - `transactions` (array of ImportedTransactionWire, required): One per transaction the file holds, in the order the importer builds them. - `csv` (CsvWire or null): CSV's own state: each account name the file uses and where it resolved. - `documents` (array of DocumentWire or null): `csvDocuments`: the documents, by index. - `owners` (array of OwnerWire or null): `csvOwners`: the customers or vendors, by index. - `qif` (QifWire or null): QIF's own state: the date formats to choose between, the account, category and payee maps, and the securities. - `accounts` (array of AccountRecordWire or null): `csvAccounts`: one per account row, in file order. - `prices` (array of PriceRecordWire or null): `csvPrices`: one per price line, in file order. ## Related - [import.apply](method/import.apply) - [import.discard](method/import.discard) - [importMap.list](method/importMap.list) --- *red-ale Manual, `method/import.preview`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # importMap.delete Delete Import map or online entries, one by one, by kind, or every invalid one. Deletes import map entries: named ones (`entries`, each an account, a `kind` and a `key`), every entry of a kind on an account (leave out the `key`), or every invalid one (`invalid: true`), as GnuCash's import map editor does. Give either `entries` or `invalid`, not both. A `bayes` token is kept once per target account; `target` picks one, otherwise the token goes for all of them. It is destructive: the matcher forgets what it learned. ## Examples Removing the invalid entries, then one learned description, which is then gone: *Example: with a copy of the `synthetic/import-map` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"importMap.delete","params":{"invalid":true}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "deleted": [ { "account": { "guid": "…", "fullName": "Assets:Checking" }, "kind": "bayes", "key": "Coffee", "target": null, "count": 1, "valid": false } ] } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"importMap.delete","params":{"entries":[{"account":"Assets:Checking","kind":"desc","key":"Corner Grocer"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "deleted": [ { "kind": "desc", "key": "Corner Grocer", "…": "…" } ] } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"importMap.delete","params":{"entries":[{"account":"Assets:Checking","kind":"desc","key":"Corner Grocer"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "error": { "code": 2000, "message": "…", "data": { "help": "error/not-found", "…": "…" } } } ``` **Effect:** `destructive`, on the Book. ## Params Params of `importMap.delete`: `entries` or `invalid`, not both. - `entries` (array of EntryParam or null): The entries to delete. - `invalid` (boolean): Instead of `entries`: every invalid entry in the book, as the editor's "Delete invalid mappings". ## Result The entries deleted. - `deleted` (array of ImportMapEntry, required): Each as it was listed. ## Related - [importMap.list](method/importMap.list) --- *red-ale Manual, `method/importMap.delete`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # importMap.list List Import map entries (Bayesian, desc, memo, csv-account-map) and online entries. Lists what the importers have learned: the entries in the book that propose a transfer account for an imported transaction. They are the `bayes` tokens GnuCash's Bayesian matcher trains, the plain `desc` and `memo` maps, the `csvAccountMap` of account names in CSV files, and the online IDs of bank connections (`onlineId`, `hbci`, `ofxIncomeAccount`). Each says which account holds it, its key, the account it points to and whether it is still valid. An entry is invalid when the account it points to no longer exists; `invalidOnly` lists what [importMap.delete](method/importMap.delete) with `invalid` would remove. A book that has never imported has none. ## Examples A book whose checking account has learned from a few imports. GnuCash's Bayesian matcher keeps one entry per token and account (the words of a description, and the day of the week), the plain maps one per description or memo, and the CSV map one per account name in a file. The `Coffee` token points to an account deleted since, so it is invalid: *Example: with a copy of the `synthetic/import-map` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"importMap.list","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "entries": [ { "account": { "guid": "…", "fullName": "Assets:Checking" }, "kind": "bayes", "key": "ACME", "target": { "guid": "…", "fullName": "Income:Salary" }, "count": 1, "valid": true }, { "kind": "bayes", "key": "Coffee", "target": null, "valid": false, "…": "…" }, { "kind": "bayes", "key": "Corner", "target": { "guid": "…", "fullName": "Expenses:Groceries" }, "…": "…" }, { "kind": "bayes", "key": "Friday", "…": "…" }, { "kind": "bayes", "key": "Grocer", "…": "…" }, { "kind": "bayes", "key": "Monday", "…": "…" }, { "kind": "bayes", "key": "Salary", "…": "…" }, { "kind": "desc", "key": "Corner Grocer", "target": { "guid": "…", "fullName": "Expenses:Groceries" }, "…": "…" }, { "kind": "memo", "key": "March rent", "target": { "guid": "…", "fullName": "Expenses:Rent" }, "…": "…" }, { "kind": "csvAccountMap", "key": "CHK-001", "target": { "guid": "…", "fullName": "Assets:Checking" }, "…": "…" } ] } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"importMap.list","params":{"invalidOnly":true}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "entries": [ { "account": { "guid": "…", "fullName": "Assets:Checking" }, "kind": "bayes", "key": "Coffee", "target": null, "count": 1, "valid": false } ] } } ``` A book that has never imported has none: *Example: with a copy of the `synthetic/rich` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"importMap.list","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "entries": [] } } ``` **Effect:** `read`. ## Params Params of `importMap.list`. - `account` (AccountRef or null): Only the entries this account holds (for `csvAccountMap`, the target, which holds it). - `kind` (KindWire or null): Only this kind. - `invalidOnly` (boolean): Only the entries the editor's "Delete invalid mappings" would remove. ## Result The entries. - `entries` (array of ImportMapEntry, required): By holding account's full name, then kind, then key, bytewise. ## Related - [importMap.delete](method/importMap.delete) - [import.apply](method/import.apply) --- *red-ale Manual, `method/importMap.list`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # invoice.addEntry Add a line to an unposted document (and optionally to an order). Adds a line to an unposted document, and optionally to an open order too (customer invoices only). A line has a description, a quantity, a price and an income account (invoices) or expense account (bills and vouchers). Anything you leave out is filled in as GnuCash's entry register would: the price from the job's rate, the discount from the customer, the tax table from the customer, vendor or the book's default, tax included from the owner. So a line on a customer's invoice can come back with a discount and a tax table you never asked for. Fields that GnuCash's register has no column for on a kind of document are refused: discounts on bills, `billable` and `billTo` on invoices, tax settings on vouchers. So are accounts the register does not offer: A/R, A/P, bank, cash, equity and placeholder accounts, an expense account on an invoice or an income account on a bill. On a credit note, `quantity` is the quantity as printed, and is stored negated. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"invoice.addEntry","params":{"invoice":"71803cac5d8e4dceabfd0d56ec5e7521","description":"Design","quantity":"4","account":"Income"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "…", "description": "Design", "quantity": { "num": "4", "denom": "1" }, "invoicePrice": { "num": "9000", "denom": "100" }, "discount": { "num": "5", "denom": "1" }, "discountType": "percent", "invoiceTaxTable": "489200ce534b46379dd206e300012248", "…": "…" } } ``` Posted documents are closed to new lines: *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"invoice.addEntry","params":{"invoice":"aa210b7131de44c48b8513cd27c00e95","description":"Late extra","quantity":"1","price":"10","account":"Income"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": 2003, "message": "…", "data": { "help": "error/conflict" } } } ``` **Effect:** `write`, on the Book. ## Params Params of `invoice.addEntry`. - `invoice` (Guid, required): The unposted document. - `order` (Guid or null): Also put the line on this open order. Customer invoices only: order lines use the invoice side, as GnuCash's order ledger does. - `date` (Date or null): The line's date; stored as noon local time, as GnuCash's register does. Defaults to today. - `description` (string or null): Description. - `action` (string or null): Action: a free unit label such as "Hours". - `notes` (string or null): Notes. - `quantity` (Amount or null): Quantity, as printed on the document; stored negated on a credit note. - `account` (AccountRef or null): The income account (invoices) or expense account (bills, vouchers); `null` for none. - `price` (Amount or null): Unit price. A new line on a job's document defaults to the job's rate. - `discount` (Amount or null): Invoices only: the discount, a percentage or an amount. Defaults to the customer's discount. - `discountType` (AmountTypeWire or null): Invoices only: whether the discount is a percentage or an amount. - `discountHow` (DiscountHowWire or null): Invoices only: when the discount applies relative to tax. - `taxable` (boolean or null): Invoices and bills: the line is taxed. Defaults to true when a tax table applies. - `taxIncluded` (boolean or null): Invoices and bills: the price includes tax. Defaults from the customer's or vendor's setting. - `taxTable` (TaxTableRef or null): Invoices and bills: the tax table, by GUID or name; `null` for none. Defaults to the owner's table when it overrides, else the book's default. - `billable` (boolean or null): Bills and vouchers: the cost is to be invoiced on to `billTo`. - `billTo` (Guid or null): Bills and vouchers: the customer or job to invoice the cost to; `null` for none. - `payment` (PaymentWire or null): Vouchers only: cash (the employee paid) or card (the company card paid). ## Result A line. Both sides are shown; the one its document uses is `invoice*` for customer invoices and `bill*` for bills and vouchers. - `guid` (Guid, required): A GUID: 32 hexadecimal digits. - `date` (Timestamp, required): An instant, RFC 3339; written in UTC with a Z suffix. - `dateEntered` (Timestamp, required): An instant, RFC 3339; written in UTC with a Z suffix. - `description` (string, required) - `action` (string, required) - `notes` (string, required) - `quantity` (Amount, required): As stored: negated on a credit note. - `documentQuantity` (Amount, required): As printed on the document. - `invoice` (Guid or null): The customer invoice it is on. - `bill` (Guid or null): The bill or voucher it is on. - `order` (Guid or null): The order it is on. - `invoiceAccount` (Guid or null) - `invoicePrice` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `discount` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `discountType` (AmountTypeWire, required): Percentage or fixed amount. - `discountHow` (DiscountHowWire, required): When a discount applies relative to tax. - `invoiceTaxable` (boolean, required) - `invoiceTaxIncluded` (boolean, required) - `invoiceTaxTable` (Guid or null) - `billAccount` (Guid or null) - `billPrice` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `billTaxable` (boolean, required) - `billTaxIncluded` (boolean, required) - `billTaxTable` (Guid or null) - `billable` (boolean, required) - `billTo` (OwnerInfo or null) - `payment` (PaymentWire, required): How an employee paid an expense. ## Related - [invoice.updateEntry](method/invoice.updateEntry) - [invoice.removeEntry](method/invoice.removeEntry) - [invoice.totals](method/invoice.totals) - [order.addEntry](method/order.addEntry) --- *red-ale Manual, `method/invoice.addEntry`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # invoice.create Create an invoice, bill or expense voucher; the owner decides which. Creates an unposted document: an invoice, a bill or an expense voucher, with no lines yet. The `owner` decides which: a customer gives an invoice, a vendor a bill, an employee an expense voucher, and a job gives the kind of its owner. Add lines with [invoice.addEntry](method/invoice.addEntry), then post it with [invoice.post](method/invoice.post). The document takes its owner's currency and billing term (give `terms: null` for none), and its number from the counter of its kind (`gncInvoice`, `gncBill` or `gncExpVoucher`) unless you give `id`. A number taken is never given back, even if the document is later deleted. `creditNote: true` makes a credit note, which cannot be changed afterwards; it also sets the book feature `Credit Notes`, which older GnuCash versions do not know, so they will refuse the book. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"invoice.create","params":{"owner":"5b22073fa4e34411b07c14a77147ce6b","billingId":"PO-5"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "…", "id": "000003", "type": "invoice", "posted": false, "terms": "3416d941790749378beeb338b8357a72", "billingId": "PO-5", "entryCount": 0, "entries": [], "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"invoice.create","params":{"owner":"9697710198334d558a9bfde219bb1e41"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "guid": "…", "id": "000002", "type": "bill", "posted": false, "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `invoice.create`. `owner` is required. - `owner` (Guid or null): A customer (invoice), vendor (bill), employee (expense voucher) or job (its owner's type). On update it can change only to an owner of the same type; the currency follows the owner. - `id` (string or null): Document number. On create, absent or empty takes the next number from the counter of the type (`gncInvoice`, `gncBill` or `gncExpVoucher`). - `dateOpened` (Date or null): Date opened; stored as noon local time. Defaults to today. - `terms` (BillTermRef or null): Billing term, by GUID or name; `null` for none. On create, absent takes the owner's term. - `billingId` (string or null): The customer's reference (purchase order number) or the vendor's invoice number. - `notes` (string or null): Notes. - `docLink` (string or null): A document link: a URL, a `file://` URI, or a path relative to the path head. Empty removes it. Posted documents accept it too. - `billTo` (Guid or null): Bills and vouchers: the customer or job the costs are for; `null` for none. - `chargeAmount` (Amount or null): Vouchers: an extra amount to charge to the employee's credit card when posted. - `active` (boolean or null): Active; `false` deactivates. - `creditNote` (boolean or null): A credit note (default false). Fixed once the document exists: an update may only repeat it. ## Result A document with its lines, in GnuCash's order (date, date entered, description, action, GUID). - `guid` (Guid, required): A GUID: 32 hexadecimal digits. - `id` (string, required) - `type` (DocumentKindWire or null): From the owner (through a job to its owner) and the credit-note flag. - `owner` (OwnerInfo, required): An owner: a customer, vendor, employee or job. - `currency` (CommodityId or null) - `dateOpened` (Timestamp, required): An instant, RFC 3339; written in UTC with a Z suffix. - `posted` (boolean, required) - `datePosted` (Timestamp or null) - `terms` (Guid or null) - `billingId` (string, required) - `notes` (string, required) - `docLink` (string or null): The document link (`assoc_uri` slot), as stored. - `active` (boolean, required) - `billTo` (OwnerInfo or null) - `chargeAmount` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `postedAccount` (Guid or null) - `postedTransaction` (Guid or null) - `postedLot` (Guid or null) - `entryCount` (integer (uint), required) - `entries` (array of EntryInfo, required): Its lines. ## Related - [invoice.addEntry](method/invoice.addEntry) - [invoice.post](method/invoice.post) - [customer.create](method/customer.create) - [vendor.create](method/vendor.create) - [employee.create](method/employee.create) --- *red-ale Manual, `method/invoice.create`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # invoice.delete Delete an unposted document and its lines. Deletes an unposted document and its lines. Lines that are also on an order stay on the order. A posted document is refused with `conflict`: [invoice.unpost](method/invoice.unpost) it first, which deletes its transaction. GnuCash's own screens can only discard a document that has just been created; red-ale lets you delete any unposted one, so a draft can be undone. Its number is not given back to the counter. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"invoice.delete","params":{"invoice":"aa210b7131de44c48b8513cd27c00e95"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": 2003, "message": "document 000001 is posted; unpost it first", "data": { "help": "error/conflict" } } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"invoice.delete","params":{"invoice":"71803cac5d8e4dceabfd0d56ec5e7521"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": {} } ``` **Effect:** `destructive`, on the Book. ## Params Names one document. - `invoice` (Guid, required): The document. ## Result A result with nothing to report. Type: Done. ## Related - [invoice.unpost](method/invoice.unpost) - [invoice.removeEntry](method/invoice.removeEntry) --- *red-ale Manual, `method/invoice.delete`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # invoice.due Posted, unpaid documents falling due within some days: GnuCash's bills-due and invoices-due reminders. Lists the posted documents that are still open and fall due within `daysInAdvance` days (default 7) of `now`: GnuCash's reminders of invoices due (`kind: invoices`, customer documents) and bills due (`kind: bills`, vendor and employee documents). Overdue documents are included. Sorted by due date; `amount` is the open balance, signed as on the A/R or A/P account. GnuCash shows these at book open, from its preferences; red-ale has no screen, so the preferences are the params. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"invoice.due","params":{"kind":"invoices","daysInAdvance":60,"now":"2024-04-01T00:00:00Z"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": [ { "invoice": "aa210b7131de44c48b8513cd27c00e95", "id": "000001", "company": "Acme & Sons ", "dueDate": "2024-04-03", "amount": { "num": "87300", "denom": "100" }, "…": "…" } ] } ``` **Effect:** `read`. ## Params Params of `invoice.due`. - `kind` (DueKind, required): Which documents. - `daysInAdvance` (integer (int64)): How many days ahead to look (GnuCash's `days-in-advance` preference, default 7). Negative counts as 0. - `now` (Timestamp or null): The moment to look from. Default: now. ## Result Type: array of DueDocument. ## Related - [invoice.dueDate](method/invoice.dueDate) - [invoice.list](method/invoice.list) --- *red-ale Manual, `method/invoice.due`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # invoice.dueDate When a document posted on a date falls due under its (or a given) billing term. Computes when a document posted on `postDate` falls due under a billing term: the document's own (give `invoice`) or one you name by GUID or name (`term`). A `days` term adds its days; a `proximo` term falls due on its day of the next month (clamped to the month's end), or of the month after when the posting day is past its cutoff. With no term, the due date is the posting date. [invoice.post](method/invoice.post) uses the same rule when you give no `dueDate`. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"invoice.dueDate","params":{"invoice":"aa210b7131de44c48b8513cd27c00e95","postDate":"2024-03-28"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "dueDate": "2024-04-27", "due": "2024-04-27T10:59:00Z" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"invoice.dueDate","params":{"term":"Prox15","postDate":"2024-03-28"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "dueDate": "2024-05-15", "due": "2024-05-15T10:59:00Z" } } ``` **Effect:** `read`. ## Params Params of `invoice.dueDate`. - `invoice` (Guid or null): A document whose billing term to use. Give this or `term`. - `term` (BillTermRef or null): A billing term to use, by GUID or by name. Give this or `invoice`. - `postDate` (Date, required): The posting date. ## Result Result of `invoice.dueDate`. - `dueDate` (Date, required): The due date. - `due` (Timestamp, required): The instant GnuCash stores: the day-neutral time of the due date. ## Related - [billTerm.create](method/billTerm.create) - [invoice.post](method/invoice.post) - [invoice.due](method/invoice.due) --- *red-ale Manual, `method/invoice.dueDate`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # invoice.duplicate Copy a document and its lines into a new unposted document with a new number and date, as GnuCash's Duplicate does. Copies a document, posted or not, and all its lines into a new unposted document, as GnuCash's Duplicate does. The copy is active, takes the next number from its kind's counter (or `id`), and has `date` (default today) as its opened date and the date of every line. Not copied: the posting itself, and each line's payment method, which goes back to `cash`, so a duplicated expense voucher loses its card lines. GnuCash does the same. To duplicate several documents with one date, call it once for each. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"invoice.duplicate","params":{"invoice":"aa210b7131de44c48b8513cd27c00e95","date":"2024-05-01"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "…", "id": "000003", "posted": false, "billingId": "CUST-REF-9", "entryCount": 2, "entries": [ "…" ], "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `invoice.duplicate`. - `invoice` (Guid, required): The document to copy, posted or not. - `date` (Date or null): The date of the copy and of each of its lines, stored at its day-neutral time. Defaults to today. - `id` (string or null): The copy's number. Absent or empty takes the next number from the counter of its kind. ## Result A document with its lines, in GnuCash's order (date, date entered, description, action, GUID). - `guid` (Guid, required): A GUID: 32 hexadecimal digits. - `id` (string, required) - `type` (DocumentKindWire or null): From the owner (through a job to its owner) and the credit-note flag. - `owner` (OwnerInfo, required): An owner: a customer, vendor, employee or job. - `currency` (CommodityId or null) - `dateOpened` (Timestamp, required): An instant, RFC 3339; written in UTC with a Z suffix. - `posted` (boolean, required) - `datePosted` (Timestamp or null) - `terms` (Guid or null) - `billingId` (string, required) - `notes` (string, required) - `docLink` (string or null): The document link (`assoc_uri` slot), as stored. - `active` (boolean, required) - `billTo` (OwnerInfo or null) - `chargeAmount` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `postedAccount` (Guid or null) - `postedTransaction` (Guid or null) - `postedLot` (Guid or null) - `entryCount` (integer (uint), required) - `entries` (array of EntryInfo, required): Its lines. ## Related - [invoice.create](method/invoice.create) - [invoice.get](method/invoice.get) --- *red-ale Manual, `method/invoice.duplicate`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # invoice.get A document with its lines. Returns one document with its lines, in GnuCash's order (by date, then date entered, description, action and GUID). A line has both an invoice side and a bill side, as in GnuCash; the side that applies depends on the document's kind. Amounts are exact; the totals are in [invoice.totals](method/invoice.totals). ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"invoice.get","params":{"invoice":"aa210b7131de44c48b8513cd27c00e95"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "aa210b7131de44c48b8513cd27c00e95", "id": "000001", "type": "invoice", "posted": true, "billingId": "CUST-REF-9", "entryCount": 2, "entries": [ { "description": "Consulting", "quantity": { "num": "10", "denom": "1" }, "invoicePrice": { "num": "12050", "denom": "100" }, "…": "…" }, "…" ], "…": "…" } } ``` **Effect:** `read`. ## Params Names one document. - `invoice` (Guid, required): The document. ## Result A document with its lines, in GnuCash's order (date, date entered, description, action, GUID). - `guid` (Guid, required): A GUID: 32 hexadecimal digits. - `id` (string, required) - `type` (DocumentKindWire or null): From the owner (through a job to its owner) and the credit-note flag. - `owner` (OwnerInfo, required): An owner: a customer, vendor, employee or job. - `currency` (CommodityId or null) - `dateOpened` (Timestamp, required): An instant, RFC 3339; written in UTC with a Z suffix. - `posted` (boolean, required) - `datePosted` (Timestamp or null) - `terms` (Guid or null) - `billingId` (string, required) - `notes` (string, required) - `docLink` (string or null): The document link (`assoc_uri` slot), as stored. - `active` (boolean, required) - `billTo` (OwnerInfo or null) - `chargeAmount` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `postedAccount` (Guid or null) - `postedTransaction` (Guid or null) - `postedLot` (Guid or null) - `entryCount` (integer (uint), required) - `entries` (array of EntryInfo, required): Its lines. ## Related - [invoice.list](method/invoice.list) - [invoice.totals](method/invoice.totals) --- *red-ale Manual, `method/invoice.get`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # invoice.list Invoices, bills and vouchers, optionally filtered. Lists documents of every kind, without their lines, in GUID order. Filter by `type` (`invoice`, `bill`, `expenseVoucher`, `creditNote`), by owner (a customer's list includes its jobs' documents), by posted or unposted, by active, or by exact number. Numbers are only unique within a counter, so `id` may match an invoice and a bill. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"invoice.list","params":{"type":"expenseVoucher"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "invoices": [ { "id": "000001", "type": "expenseVoucher", "posted": true, "entryCount": 1, "…": "…" } ] } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"invoice.list","params":{"posted":false}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "invoices": [ { "guid": "71803cac5d8e4dceabfd0d56ec5e7521", "id": "000002", "posted": false, "…": "…" } ] } } ``` **Effect:** `read`. ## Params Filters for `invoice.list`. All given filters must match. - `type` (DocumentKindWire or null): Only this type. - `owner` (Guid or null): Only this owner's documents; a customer or vendor also matches its jobs' documents. - `posted` (boolean or null): Only posted (`true`) or unposted (`false`) documents. - `activeOnly` (boolean): Only active documents. - `id` (string or null): The exact document number. ## Result Documents. - `invoices` (array of InvoiceInfo, required): In GUID order. ## Related - [invoice.get](method/invoice.get) - [invoice.due](method/invoice.due) --- *red-ale Manual, `method/invoice.list`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # invoice.pay Record a payment of one posted document. Records a payment of one posted document: a transaction between the A/R or A/P account and `transferAccount`, applied to that document only. `amount` is positive when a customer pays or when you pay a vendor or employee; a negative amount is a refund. A payment of less than the balance leaves the rest open; one of more leaves a pre-payment. To pay several documents at once, or an owner's oldest first, use [payment.process](method/payment.process). ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"invoice.pay","params":{"invoice":"95e2e7416db94eb3a7de7433f3e7875f","transferAccount":"Assets:Bank","amount":"20.00","date":"2024-03-25","memo":"Part payment"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "transaction": "…", "paymentLot": null } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"invoice.pay","params":{"invoice":"71803cac5d8e4dceabfd0d56ec5e7521","transferAccount":"Assets:Bank","amount":"1.00","date":"2024-03-25"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "error": { "code": 2001, "message": "document 000002 is not posted", "data": { "help": "error/invalid" } } } ``` **Effect:** `write`, on the Book. ## Params Params of `invoice.pay`. - `invoice` (Guid, required): The posted document. - `transferAccount` (AccountRef, required): Where the money goes or comes from. - `amount` (Amount, required): The payment, signed as in `payment.process`. - `exchangeRate` (Amount or null): Units of the transfer account's commodity per unit of the A/R or A/P account's commodity, when they differ. - `date` (Date, required): The payment date. - `memo` (string or null): Memo of both splits. - `num` (string or null): Transaction number. ## Result Result of a payment. - `transaction` (Guid or null): The payment transaction (none when the amount is zero). - `paymentLot` (Guid or null): The lot holding what was not applied: a pre-payment. ## Related - [payment.process](method/payment.process) - [payment.openItems](method/payment.openItems) --- *red-ale Manual, `method/invoice.pay`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # invoice.post Post a document to an A/R or A/P account: its transaction, lot, frozen tax tables and terms. Posts an unposted document to an A/Receivable account (invoices) or A/Payable account (bills, vouchers) in the document's currency: it makes the transaction, puts the balance in a new lot, and freezes copies of the document's billing term and the tax tables of its lines. The transaction is read-only until the document is unposted. By default the lines are accumulated into one split per income or expense account (`accumulateSplits`), as GnuCash's default preference is. `dueDate` defaults to the billing term's. Lines or tax accounts in another commodity need a `prices` entry each. Everything is checked first, and a document with no lines, a line without an account or a wrong posting account is refused with `invalid` and nothing changed; GnuCash can stop halfway. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"invoice.post","params":{"invoice":"71803cac5d8e4dceabfd0d56ec5e7521","account":"Assets:Receivable","postDate":"2024-03-10","dueDate":"2024-04-10"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "transaction": "…", "lot": "…", "due": "2024-04-10T10:59:00Z" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"invoice.post","params":{"invoice":"71803cac5d8e4dceabfd0d56ec5e7521","account":"Assets:Receivable","postDate":"2024-03-10"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "error": { "code": 2003, "message": "document 000002 is already posted", "data": { "help": "error/conflict" } } } ``` **Effect:** `write`, on the Book. ## Params Params of `invoice.post`. - `invoice` (Guid, required): The document. - `account` (AccountRef, required): The A/Receivable (customer documents) or A/Payable (bills, vouchers) account, in the document currency. - `postDate` (Date, required): The posting date. - `dueDate` (Date or null): The due date. Default: from the document's billing term, else the posting date. - `memo` (string or null): Memo for the A/R or A/P split and accumulated splits. - `accumulateSplits` (boolean or null): One split per account rather than per entry (GnuCash's default: true). - `autoPay` (boolean): Then apply the owner's open pre-payments and opposite documents (GnuCash's default: false). - `prices` (array of PriceParam): Prices for entries posting to accounts in another commodity. ## Result Result of `invoice.post`. - `transaction` (Guid, required): The posted transaction. - `lot` (Guid, required): The document's lot. - `due` (Timestamp, required): The due instant stored on the transaction. ## Related - [invoice.totals](method/invoice.totals) - [invoice.unpost](method/invoice.unpost) - [invoice.pay](method/invoice.pay) - [payment.process](method/payment.process) --- *red-ale Manual, `method/invoice.post`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # invoice.removeEntry Delete a line from its documents and order. Deletes a line from the documents and the order it is on, and destroys it. The document must be unposted and the order open. The tax tables and billing term the line used lose a reference. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"invoice.removeEntry","params":{"entry":"5eff8018de334b2084ef00f90330cd57"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": {} } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"invoice.get","params":{"invoice":"71803cac5d8e4dceabfd0d56ec5e7521"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "entryCount": 0, "entries": [], "…": "…" } } ``` **Effect:** `destructive`, on the Book. ## Params Names one line. - `entry` (Guid, required): The line. ## Result A result with nothing to report. Type: Done. ## Related - [invoice.addEntry](method/invoice.addEntry) - [invoice.delete](method/invoice.delete) --- *red-ale Manual, `method/invoice.removeEntry`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # invoice.totals A document's subtotal, tax and total, per tax account and per entry, as GnuCash computes them. Gives a document's subtotal, tax and total, the tax per tax account and each line's value, discount and tax, worked out as GnuCash does: exactly, with each line's value rounded to the currency's smallest unit, but each account's tax summed unrounded over the lines and rounded once. So the tax total can differ by a cent from the sum of the lines' taxes. Figures are signed as printed on the document. It works on posted and unposted documents alike, and a posted document's total is what [invoice.post](method/invoice.post) put in the A/R or A/P split. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"invoice.totals","params":{"invoice":"aa210b7131de44c48b8513cd27c00e95"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "subtotal": { "num": "125000", "denom": "100" }, "tax": { "num": "12300", "denom": "100" }, "total": { "num": "137300", "denom": "100" }, "taxes": [ { "accountName": "Liabilities:Tax", "amount": { "num": "12050", "denom": "100" }, "…": "…" }, { "accountName": "Liabilities:Levy", "amount": { "num": "250", "denom": "100" }, "…": "…" } ], "entries": [ "…" ] } } ``` **Effect:** `read`. ## Params Params naming one document. - `invoice` (Guid, required): The invoice, bill or expense voucher. ## Result Result of `invoice.totals`. Amounts are signed as printed on the document: positive for invoices and bills, and for credit notes too. - `subtotal` (Amount, required): Σ of the entries' rounded values. - `tax` (Amount, required): Σ of `taxes`. - `total` (Amount, required): Subtotal plus tax: what the document is for. - `taxes` (array of AccountAmount, required): Tax per tax account: each account's unrounded taxes summed over the entries, then rounded once. - `entries` (array of EntryTotals, required): Each entry, in document order. ## Related - [invoice.get](method/invoice.get) - [invoice.post](method/invoice.post) --- *red-ale Manual, `method/invoice.totals`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # invoice.unpost Unpost a document: delete its posted transaction and lot links; payments stay as pre-payments. Unposts a document: deletes its transaction and the lot links to other documents, so it can be edited, and puts it back as unposted. Payments made against it are not deleted: they stay in its lot as pre-payments of the owner, ready to be applied again. A lot left empty is deleted. The document keeps its frozen billing term; with `resetTaxTables` its lines go back to the tax tables the frozen copies came from. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"invoice.unpost","params":{"invoice":"aa210b7131de44c48b8513cd27c00e95"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": {} } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"invoice.get","params":{"invoice":"aa210b7131de44c48b8513cd27c00e95"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "posted": false, "datePosted": null, "postedTransaction": null, "postedLot": null, "…": "…" } } ``` **Effect:** `destructive`, on the Book. ## Params Params of `invoice.unpost`. - `invoice` (Guid, required): The posted document. - `resetTaxTables` (boolean): Point the entries back at the tax tables their frozen copies came from (GnuCash's dialog default: false). ## Result A result with nothing to report. Type: Done. ## Related - [invoice.post](method/invoice.post) - [invoice.delete](method/invoice.delete) --- *red-ale Manual, `method/invoice.unpost`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # invoice.update Change an unposted document, or (de)activate any document. Changes an unposted document: its owner, number, dates, billing term, notes, document link and the like. A new owner must give the same kind of document (another customer, or one of a customer's jobs, for an invoice), and the currency follows the owner. Whether it is a credit note cannot change. A posted document can only be activated or deactivated, or have its document link changed; any other change is refused with `conflict`. Unpost it first with [invoice.unpost](method/invoice.unpost). ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"invoice.update","params":{"invoice":"71803cac5d8e4dceabfd0d56ec5e7521","notes":"Phase 1"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "71803cac5d8e4dceabfd0d56ec5e7521", "notes": "Phase 1", "posted": false, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"invoice.update","params":{"invoice":"aa210b7131de44c48b8513cd27c00e95","notes":"Phase 1"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "error": { "code": 2003, "message": "document 000001 is posted; only its active flag can change", "data": { "help": "error/conflict" } } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"invoice.update","params":{"invoice":"aa210b7131de44c48b8513cd27c00e95","active":false}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "guid": "aa210b7131de44c48b8513cd27c00e95", "active": false, "posted": true, "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `invoice.update`: the fields to change. Posted documents accept only `active`. - `invoice` (Guid, required): The document. - `owner` (Guid or null): A customer (invoice), vendor (bill), employee (expense voucher) or job (its owner's type). On update it can change only to an owner of the same type; the currency follows the owner. - `id` (string or null): Document number. On create, absent or empty takes the next number from the counter of the type (`gncInvoice`, `gncBill` or `gncExpVoucher`). - `dateOpened` (Date or null): Date opened; stored as noon local time. Defaults to today. - `terms` (BillTermRef or null): Billing term, by GUID or name; `null` for none. On create, absent takes the owner's term. - `billingId` (string or null): The customer's reference (purchase order number) or the vendor's invoice number. - `notes` (string or null): Notes. - `docLink` (string or null): A document link: a URL, a `file://` URI, or a path relative to the path head. Empty removes it. Posted documents accept it too. - `billTo` (Guid or null): Bills and vouchers: the customer or job the costs are for; `null` for none. - `chargeAmount` (Amount or null): Vouchers: an extra amount to charge to the employee's credit card when posted. - `active` (boolean or null): Active; `false` deactivates. - `creditNote` (boolean or null): A credit note (default false). Fixed once the document exists: an update may only repeat it. ## Result A document with its lines, in GnuCash's order (date, date entered, description, action, GUID). - `guid` (Guid, required): A GUID: 32 hexadecimal digits. - `id` (string, required) - `type` (DocumentKindWire or null): From the owner (through a job to its owner) and the credit-note flag. - `owner` (OwnerInfo, required): An owner: a customer, vendor, employee or job. - `currency` (CommodityId or null) - `dateOpened` (Timestamp, required): An instant, RFC 3339; written in UTC with a Z suffix. - `posted` (boolean, required) - `datePosted` (Timestamp or null) - `terms` (Guid or null) - `billingId` (string, required) - `notes` (string, required) - `docLink` (string or null): The document link (`assoc_uri` slot), as stored. - `active` (boolean, required) - `billTo` (OwnerInfo or null) - `chargeAmount` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `postedAccount` (Guid or null) - `postedTransaction` (Guid or null) - `postedLot` (Guid or null) - `entryCount` (integer (uint), required) - `entries` (array of EntryInfo, required): Its lines. ## Related - [invoice.create](method/invoice.create) - [invoice.unpost](method/invoice.unpost) --- *red-ale Manual, `method/invoice.update`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # invoice.updateEntry Change a line of an unposted document or open order. Changes a line of an unposted document or an open order; fields you leave out stay as they are. A line stays on the documents and the order it was added to; this cannot move it. A line of a posted document or a closed order is refused with `conflict`. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"invoice.updateEntry","params":{"entry":"5eff8018de334b2084ef00f90330cd57","price":"12.50","quantity":"2"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "5eff8018de334b2084ef00f90330cd57", "quantity": { "num": "2", "denom": "1" }, "invoicePrice": { "num": "1250", "denom": "100" }, "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `invoice.updateEntry` and `order.updateEntry`: the fields to change. - `entry` (Guid, required): The line. - `date` (Date or null): The line's date; stored as noon local time, as GnuCash's register does. Defaults to today. - `description` (string or null): Description. - `action` (string or null): Action: a free unit label such as "Hours". - `notes` (string or null): Notes. - `quantity` (Amount or null): Quantity, as printed on the document; stored negated on a credit note. - `account` (AccountRef or null): The income account (invoices) or expense account (bills, vouchers); `null` for none. - `price` (Amount or null): Unit price. A new line on a job's document defaults to the job's rate. - `discount` (Amount or null): Invoices only: the discount, a percentage or an amount. Defaults to the customer's discount. - `discountType` (AmountTypeWire or null): Invoices only: whether the discount is a percentage or an amount. - `discountHow` (DiscountHowWire or null): Invoices only: when the discount applies relative to tax. - `taxable` (boolean or null): Invoices and bills: the line is taxed. Defaults to true when a tax table applies. - `taxIncluded` (boolean or null): Invoices and bills: the price includes tax. Defaults from the customer's or vendor's setting. - `taxTable` (TaxTableRef or null): Invoices and bills: the tax table, by GUID or name; `null` for none. Defaults to the owner's table when it overrides, else the book's default. - `billable` (boolean or null): Bills and vouchers: the cost is to be invoiced on to `billTo`. - `billTo` (Guid or null): Bills and vouchers: the customer or job to invoice the cost to; `null` for none. - `payment` (PaymentWire or null): Vouchers only: cash (the employee paid) or card (the company card paid). ## Result A line. Both sides are shown; the one its document uses is `invoice*` for customer invoices and `bill*` for bills and vouchers. - `guid` (Guid, required): A GUID: 32 hexadecimal digits. - `date` (Timestamp, required): An instant, RFC 3339; written in UTC with a Z suffix. - `dateEntered` (Timestamp, required): An instant, RFC 3339; written in UTC with a Z suffix. - `description` (string, required) - `action` (string, required) - `notes` (string, required) - `quantity` (Amount, required): As stored: negated on a credit note. - `documentQuantity` (Amount, required): As printed on the document. - `invoice` (Guid or null): The customer invoice it is on. - `bill` (Guid or null): The bill or voucher it is on. - `order` (Guid or null): The order it is on. - `invoiceAccount` (Guid or null) - `invoicePrice` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `discount` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `discountType` (AmountTypeWire, required): Percentage or fixed amount. - `discountHow` (DiscountHowWire, required): When a discount applies relative to tax. - `invoiceTaxable` (boolean, required) - `invoiceTaxIncluded` (boolean, required) - `invoiceTaxTable` (Guid or null) - `billAccount` (Guid or null) - `billPrice` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `billTaxable` (boolean, required) - `billTaxIncluded` (boolean, required) - `billTaxTable` (Guid or null) - `billable` (boolean, required) - `billTo` (OwnerInfo or null) - `payment` (PaymentWire, required): How an employee paid an expense. ## Related - [invoice.addEntry](method/invoice.addEntry) - [invoice.removeEntry](method/invoice.removeEntry) --- *red-ale Manual, `method/invoice.updateEntry`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # job.create Create a job for a customer or vendor; its ID comes from the book's counter unless given. Creates a job: a project of a customer or a vendor that its invoices or bills can be filed under. It needs a `name` and an `owner`, the GUID of a customer or vendor. A job has no currency of its own; it uses its owner's. `rate` is the default price of new lines on the job's documents (GnuCash keeps it in the job's `job-rate` slot); zero removes it. Leave `id` out and the job is numbered from the `gncJob` counter. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"job.create","params":{"name":"Audit","owner":"5b22073fa4e34411b07c14a77147ce6b","rate":"120"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "…", "name": "Audit", "owner": { "kind": "customer", "guid": "5b22073fa4e34411b07c14a77147ce6b" }, "rate": { "num": "120", "denom": "1" }, "active": true, "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `job.create`. `name` and `owner` are required. - `name` (string or null): Job name. - `id` (string or null): Job number. On create, absent or empty takes the next number from the book's `gncJob` counter. - `owner` (Guid or null): The customer or vendor the job is for. It cannot change once the job has documents. - `reference` (string or null): Reference (GnuCash's job description). - `rate` (Amount or null): Rate: the default price of new lines on the job's documents. Zero removes it. - `active` (boolean or null): Active; `false` deactivates. ## Result A job. - `guid` (Guid, required): A GUID: 32 hexadecimal digits. - `id` (string, required) - `name` (string, required) - `owner` (OwnerInfo, required): An owner: a customer, vendor, employee or job. - `reference` (string, required) - `rate` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `active` (boolean, required) ## Related - [job.update](method/job.update) - [job.list](method/job.list) - [customer.create](method/customer.create) - [invoice.create](method/invoice.create) --- *red-ale Manual, `method/job.create`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # job.get A job. Returns one job by GUID, with its owner as a `kind` (`customer` or `vendor`) and GUID. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"job.get","params":{"job":"3048f991c36143769571bcc833015d53"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "3048f991c36143769571bcc833015d53", "id": "JOB-1", "name": "Website rebuild", "owner": { "kind": "customer", "guid": "5b22073fa4e34411b07c14a77147ce6b" }, "reference": "PO-77", "…": "…" } } ``` **Effect:** `read`. ## Params Names one job. - `job` (Guid, required): The job. ## Result A job. - `guid` (Guid, required): A GUID: 32 hexadecimal digits. - `id` (string, required) - `name` (string, required) - `owner` (OwnerInfo, required): An owner: a customer, vendor, employee or job. - `reference` (string, required) - `rate` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `active` (boolean, required) ## Related - [job.list](method/job.list) - [job.update](method/job.update) --- *red-ale Manual, `method/job.get`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # job.list Jobs, optionally filtered by owner, name, ID or active state. Lists jobs, optionally only those of one customer or vendor (`owner`), the active ones, those whose name contains some text or one ID. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"job.list","params":{"owner":"5b22073fa4e34411b07c14a77147ce6b"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "jobs": [ { "guid": "3048f991c36143769571bcc833015d53", "name": "Website rebuild", "…": "…" } ] } } ``` **Effect:** `read`. ## Params Filters for `job.list`. All given filters must match. - `owner` (Guid or null): Only this customer's or vendor's jobs. - `activeOnly` (boolean): Only active jobs. - `name` (string or null): Case-insensitive part of the name. - `id` (string or null): The exact ID. ## Result Jobs. - `jobs` (array of JobInfo, required): In GUID order. ## Related - [job.get](method/job.get) - [customer.list](method/customer.list) --- *red-ale Manual, `method/job.list`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # job.update Change a job; `active: false` deactivates it. Changes a job's name, ID, reference, rate or active state. Fields you leave out stay as they are. Once a job has invoices, bills or orders its `owner` cannot change, and the call is refused with `conflict`. GnuCash allows it, and silently moves the job's documents, posted ones included, to the new owner. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"job.update","params":{"job":"3048f991c36143769571bcc833015d53","owner":"9697710198334d558a9bfde219bb1e41"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": 2003, "message": "the job has invoices, bills or orders, so its owner cannot change", "data": { "help": "error/conflict" } } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"job.update","params":{"job":"3048f991c36143769571bcc833015d53","active":false}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "guid": "3048f991c36143769571bcc833015d53", "active": false, "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `job.update`: the fields to change. - `job` (Guid, required): The job. - `name` (string or null): Job name. - `id` (string or null): Job number. On create, absent or empty takes the next number from the book's `gncJob` counter. - `owner` (Guid or null): The customer or vendor the job is for. It cannot change once the job has documents. - `reference` (string or null): Reference (GnuCash's job description). - `rate` (Amount or null): Rate: the default price of new lines on the job's documents. Zero removes it. - `active` (boolean or null): Active; `false` deactivates. ## Result A job. - `guid` (Guid, required): A GUID: 32 hexadecimal digits. - `id` (string, required) - `name` (string, required) - `owner` (OwnerInfo, required): An owner: a customer, vendor, employee or job. - `reference` (string, required) - `rate` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `active` (boolean, required) ## Related - [job.create](method/job.create) - [job.get](method/job.get) --- *red-ale Manual, `method/job.update`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # lot.assignSplit Put a split in a lot, cutting it if it would overfill the lot; without a lot, FIFO chooses. Puts a split in a lot. Given `lot`, the split joins it, and is cut in two if it would overfill the lot; the cut-off rest stays in no lot (`rest`). Without `lot`, GnuCash's FIFO policy chooses the earliest open lot the split reduces, or opens a new one (`newLots`). A split joins only a lot of its own account, and a closed lot refuses with `conflict`. ## Examples *Example: with a copy of the `reports/investment-lots` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"lot.assignSplit","params":{"split":"d0000000000000000000000000000001"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "pieces": [ { "split": "d0000000000000000000000000000001", "lot": "…" } ], "rest": null, "newLots": [ "…" ] } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"lot.assignSplit","params":{"split":"d0000000000000000000000000000007"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "pieces": [ { "split": "d0000000000000000000000000000007", "lot": "…" } ], "rest": null, "newLots": [] } } ``` **Effect:** `write`, on the Book. ## Params Params of `lot.assignSplit`. - `split` (Guid, required): The split. - `lot` (Guid or null): The lot; without it, FIFO chooses and opens lots as needed. ## Result The result of `lot.assignSplit`. - `pieces` (array of Piece, required): Each piece and its lot. - `rest` (Guid or null): When the split was cut to close the chosen lot: the new split holding the rest, in no lot. - `newLots` (array of Guid, required): Lots FIFO opened. ## Related - [lot.removeSplit](method/lot.removeSplit) - [lot.freeSplits](method/lot.freeSplits) - [lot.scrubAccount](method/lot.scrubAccount) --- *red-ale Manual, `method/lot.assignSplit`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # lot.computeGains Recompute a lot's capital gains, recording them in gains transactions. Recomputes a lot's capital gains: for each selling split, the gain is its value less the basis of the shares it sells, and it is recorded in a two-split gains transaction, `Realized Gain/Loss`, in the lot and in the gains account (or `gainsAccount`). A gain of zero records nothing, and a gains transaction that is already right is not rewritten. Unlike [lot.scrub](method/lot.scrub) it does not move splits between lots. ## Examples *Example: with a copy of the `reports/lots-baseline` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"lot.computeGains","params":{"lot":"10000000000000000000000000000000"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "lotsCreated": [], "transactionsCreated": [], "transactionsChanged": [], "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `lot.computeGains`. - `lot` (Guid, required): The lot. - `gainsAccount` (AccountRef or null): The account new gains transactions credit, used when its commodity is the transaction currency; by default the lot account's gains account (`Orphaned Gains-` unless one is set). ## Result What a scrub or gains computation changed. - `lotsCreated` (array of Guid, required): Lots made. - `lotsDeleted` (array of Guid, required): Lots deleted. - `transactionsCreated` (array of Guid, required): Transactions made: gains transactions. - `transactionsChanged` (array of Guid, required): Transactions changed: cut or merged splits, updated gains. - `transactionsDeleted` (array of Guid, required): Transactions deleted: gains transactions of merged splits. - `accountsCreated` (array of Guid, required): Accounts made: `Orphaned Gains-`. ## Related - [lot.scrub](method/lot.scrub) - [lot.get](method/lot.get) --- *red-ale Manual, `method/lot.computeGains`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # lot.create Make an empty lot in an account, titled `Lot ` unless a title is given. Makes an empty lot in an account. Its title is `Lot ` from the account's counter unless you give `title`, and you can give `notes`. Put splits in it with [lot.assignSplit](method/lot.assignSplit). You rarely need this: assigning a split without naming a lot opens one for you. ## Examples *Example: with a copy of the `reports/investment-lots` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"lot.create","params":{"account":"Root:Assets:Broker:AAPL"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "…", "title": "Lot 0", "closed": false, "balance": { "num": "0", "denom": "1" }, "splitCount": 0, "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `lot.create`. - `account` (AccountRef, required): The account to hold the lot. - `title` (string or null): Title; by default `Lot `. - `notes` (string or null): Notes. ## Result A lot, as the lot viewer lists it. - `guid` (Guid, required): The lot. - `account` (Guid, required): Its account. - `title` (string or null): Title. - `notes` (string or null): Notes. - `invoice` (Guid or null): The invoice the lot belongs to (the viewer's type `I`). - `closed` (boolean, required): The lot has splits and its balance is zero. - `openDate` (Date or null): Posted date of its earliest split. - `closeDate` (Date or null): Posted date of its latest split, when closed. - `balance` (Amount, required): Sum of its splits' amounts, restated after stock splits. - `gainsCurrency` (CommodityId or null): Currency of its realised gains. - `realizedGains` (Amount, required): Realised gains: the values of its gains splits in that currency. - `splitCount` (integer (uint), required): How many splits it holds. ## Related - [lot.update](method/lot.update) - [lot.assignSplit](method/lot.assignSplit) - [lot.delete](method/lot.delete) --- *red-ale Manual, `method/lot.create`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # lot.delete Delete a lot; its splits stay but leave the lot. A lot with splits needs releaseSplits. Deletes a lot; its splits stay in the account but leave the lot. A lot that still holds splits is refused with `conflict` unless you pass `releaseSplits: true`, which makes the release explicit (GnuCash's viewer deletes without asking). A lot that belongs to a business document cannot be deleted. ## Examples *Example: with a copy of the `reports/lots-baseline` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"lot.delete","params":{"lot":"10000000000000000000000000000000"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": 2003, "message": "…", "data": { "help": "error/conflict" } } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"lot.delete","params":{"lot":"10000000000000000000000000000000","releaseSplits":true}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "releasedSplits": [ "d0000000000000000000000000000000" ] } } ``` **Effect:** `destructive`, on the Book. ## Params Params of `lot.delete`. - `lot` (Guid, required): The lot. - `releaseSplits` (boolean): Take the lot's splits out of it first; without this, a lot with splits is refused. ## Result The result of `lot.delete`. - `releasedSplits` (array of Guid, required): Splits taken out of the lot. ## Related - [lot.removeSplit](method/lot.removeSplit) - [conflict](error/conflict) --- *red-ale Manual, `method/lot.delete`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # lot.freeSplits List an account's splits that are in no lot, with the gain each would realise against a lot. Lists the splits of an account that are in no lot, as the lot viewer's free splits. With `lot`, each also shows the gain it would realise against that lot. Use it to see what [lot.assignSplit](method/lot.assignSplit) or [lot.scrubAccount](method/lot.scrubAccount) still has to place. ## Examples *Example: with a copy of the `reports/investment-lots` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"lot.freeSplits","params":{"account":"Root:Assets:Broker:AAPL"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": [ { "split": "d0000000000000000000000000000001", "description": "Buy AAPL lot 1", "amount": { "num": "100", "denom": "1" }, "…": "…" }, { "split": "d0000000000000000000000000000004", "description": "Buy AAPL lot 2", "…": "…" }, { "split": "d0000000000000000000000000000007", "description": "Sell AAPL", "amount": { "num": "-60", "denom": "1" }, "…": "…" } ] } ``` **Effect:** `read`. ## Params Params of `lot.freeSplits`. - `account` (AccountRef, required): The account. - `lot` (Guid or null): A lot of the account to compute each split's gain against. ## Result Type: array of LotSplitInfo. ## Related - [lot.assignSplit](method/lot.assignSplit) - [lot.scrubAccount](method/lot.scrubAccount) --- *red-ale Manual, `method/lot.freeSplits`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # lot.get Describe one lot with its splits. Describes one lot with its splits. Each split shows its amount, its adjusted amount (the amount restated in the units after any later stock split), its value, the capital gain it realised and its `kind`: `normal`, `gains` or `stockSplit`. Reading never writes: gains that are out of date are reported as recorded, where GnuCash's viewer recomputes them. Use [lot.computeGains](method/lot.computeGains) to bring them up to date. ## Examples *Example: with a copy of the `reports/lots-baseline` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"lot.get","params":{"lot":"10000000000000000000000000000000"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "10000000000000000000000000000000", "closed": false, "balance": { "num": "100", "denom": "1" }, "splits": [ { "split": "d0000000000000000000000000000000", "description": "Buy AAPL lot baseline", "amount": { "num": "100", "denom": "1" }, "value": { "num": "500000", "denom": "100" }, "kind": "normal", "…": "…" } ], "…": "…" } } ``` **Effect:** `read`. ## Params Params naming a lot. - `lot` (Guid, required): The lot. ## Result The result of `lot.get`. - `guid` (Guid, required): The lot. - `account` (Guid, required): Its account. - `title` (string or null): Title. - `notes` (string or null): Notes. - `invoice` (Guid or null): The invoice the lot belongs to (the viewer's type `I`). - `closed` (boolean, required): The lot has splits and its balance is zero. - `openDate` (Date or null): Posted date of its earliest split. - `closeDate` (Date or null): Posted date of its latest split, when closed. - `balance` (Amount, required): Sum of its splits' amounts, restated after stock splits. - `gainsCurrency` (CommodityId or null): Currency of its realised gains. - `realizedGains` (Amount, required): Realised gains: the values of its gains splits in that currency. - `splitCount` (integer (uint), required): How many splits it holds. - `splits` (array of LotSplitInfo, required): Its splits, earliest first. ## Related - [lot.list](method/lot.list) - [lot.update](method/lot.update) --- *red-ale Manual, `method/lot.get`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # lot.list List an account's lots as the lot viewer shows them, optionally only open or closed ones. Lists an account's lots as GnuCash's lot viewer shows them: opened earliest first, empty lots last. A lot groups the splits of one account that buy and later sell the same holding; it is `closed` when it has splits and their amounts sum to zero. `state` is `all` (the default), `open` or `closed`. Each lot shows its balance, its realized gains and how many splits it holds. A lot's `title` is null until it is set; lots made by red-ale are titled `Lot `. ## Examples *Example: with a copy of the `reports/lots-baseline` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"lot.list","params":{"account":"Root:Assets:Broker:AAPL"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": [ { "guid": "10000000000000000000000000000000", "title": null, "closed": false, "openDate": "2020-01-01", "balance": { "num": "100", "denom": "1" }, "splitCount": 1, "…": "…" } ] } ``` **Effect:** `read`. ## Params Params of `lot.list`. - `account` (AccountRef, required): The account. - `state` (LotState): `all` (default), `open` or `closed`. ## Result Type: array of LotInfo. ## Related - [lot.get](method/lot.get) - [lot.create](method/lot.create) - [lot.scrubAccount](method/lot.scrubAccount) --- *red-ale Manual, `method/lot.list`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # lot.removeSplit Take a split out of its lot; a lot left empty is deleted. Takes a split out of its lot. A lot left empty is deleted (`lotDeleted: true`); GnuCash drops it from the account in the same way. The split itself and its transaction are untouched. ## Examples *Example: with a copy of the `reports/lots-baseline` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"lot.removeSplit","params":{"split":"d0000000000000000000000000000000"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "lotDeleted": true } } ``` **Effect:** `write`, on the Book. ## Params Params of `lot.removeSplit`. - `split` (Guid, required): The split. ## Result The result of `lot.removeSplit`. - `lotDeleted` (boolean, required): The lot was left empty and deleted. ## Related - [lot.assignSplit](method/lot.assignSplit) - [lot.delete](method/lot.delete) --- *red-ale Manual, `method/lot.removeSplit`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # lot.scrub Repair one lot: merge cut pieces, refill it and recompute its capital gains. Repairs one lot, as GnuCash's lot scrub does: merges split pieces that were cut from one split, refills an overfull lot, and recomputes its capital gains, recording them in gains transactions in the gains account (an income account named `Orphaned Gains-` unless the account names another). The result lists what was created, changed and deleted. It changes nothing in a lot that is already right. ## Examples *Example: with a copy of the `reports/lots-baseline` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"lot.scrub","params":{"lot":"10000000000000000000000000000000"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "lotsCreated": [], "lotsDeleted": [], "transactionsCreated": [], "transactionsChanged": [], "transactionsDeleted": [], "accountsCreated": [] } } ``` **Effect:** `write`, on the Book. ## Params Params naming a lot. - `lot` (Guid, required): The lot. ## Result What a scrub or gains computation changed. - `lotsCreated` (array of Guid, required): Lots made. - `lotsDeleted` (array of Guid, required): Lots deleted. - `transactionsCreated` (array of Guid, required): Transactions made: gains transactions. - `transactionsChanged` (array of Guid, required): Transactions changed: cut or merged splits, updated gains. - `transactionsDeleted` (array of Guid, required): Transactions deleted: gains transactions of merged splits. - `accountsCreated` (array of Guid, required): Accounts made: `Orphaned Gains-`. ## Related - [lot.scrubAccount](method/lot.scrubAccount) - [lot.computeGains](method/lot.computeGains) --- *red-ale Manual, `method/lot.scrub`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # lot.scrubAccount Assign an account's splits to lots by FIFO and repair every lot, optionally for its sub-accounts too. Assigns an account's splits to lots by FIFO and repairs every lot, as GnuCash's Scrub Account does for lots; with `subaccounts: true` it does the whole subtree. Only accounts with trades are scrubbed (stock and mutual fund accounts, and any account with a split in another commodity than its own). Use it once on an account that has never had lots; run again, it changes nothing. ## Examples *Example: with a copy of the `reports/investment-lots` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"lot.scrubAccount","params":{"account":"Root:Assets:Broker:AAPL"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "lotsCreated": [ "…", "…" ], "lotsDeleted": [], "transactionsChanged": [ "…", "…", "…" ], "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"lot.list","params":{"account":"Root:Assets:Broker:AAPL"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": [ { "title": "Lot 0", "balance": { "num": "40", "denom": "1" }, "splitCount": 2, "…": "…" }, { "title": "Lot 1", "balance": { "num": "50", "denom": "1" }, "splitCount": 1, "…": "…" } ] } ``` **Effect:** `write`, on the Book. ## Params Params of `lot.scrubAccount`. - `account` (AccountRef, required): The account. - `subaccounts` (boolean): Scrub every sub-account first, as GnuCash's tree scrub does. ## Result What a scrub or gains computation changed. - `lotsCreated` (array of Guid, required): Lots made. - `lotsDeleted` (array of Guid, required): Lots deleted. - `transactionsCreated` (array of Guid, required): Transactions made: gains transactions. - `transactionsChanged` (array of Guid, required): Transactions changed: cut or merged splits, updated gains. - `transactionsDeleted` (array of Guid, required): Transactions deleted: gains transactions of merged splits. - `accountsCreated` (array of Guid, required): Accounts made: `Orphaned Gains-`. ## Related - [lot.scrub](method/lot.scrub) - [lot.assignSplit](method/lot.assignSplit) - [scrub.checkAndRepair](method/scrub.checkAndRepair) --- *red-ale Manual, `method/lot.scrubAccount`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # lot.update Set a lot's title or notes; an empty string removes one. Sets a lot's `title` or `notes`; a field you leave out is kept and an empty string removes it. GnuCash's lot viewer writes empty strings whenever you move the selection; this writes only what you give. ## Examples *Example: with a copy of the `reports/lots-baseline` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"lot.update","params":{"lot":"10000000000000000000000000000000","title":"Core holding","notes":"bought at open"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "10000000000000000000000000000000", "title": "Core holding", "notes": "bought at open", "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `lot.update`. - `lot` (Guid, required): The lot. - `title` (string or null): New title; an empty string removes it. - `notes` (string or null): New notes; an empty string removes them. ## Result A lot, as the lot viewer lists it. - `guid` (Guid, required): The lot. - `account` (Guid, required): Its account. - `title` (string or null): Title. - `notes` (string or null): Notes. - `invoice` (Guid or null): The invoice the lot belongs to (the viewer's type `I`). - `closed` (boolean, required): The lot has splits and its balance is zero. - `openDate` (Date or null): Posted date of its earliest split. - `closeDate` (Date or null): Posted date of its latest split, when closed. - `balance` (Amount, required): Sum of its splits' amounts, restated after stock splits. - `gainsCurrency` (CommodityId or null): Currency of its realised gains. - `realizedGains` (Amount, required): Realised gains: the values of its gains splits in that currency. - `splitCount` (integer (uint), required): How many splits it holds. ## Related - [lot.get](method/lot.get) --- *red-ale Manual, `method/lot.update`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # order.addEntry Add a line to an open order. Adds a line to an open order. The line uses the invoice side and gets only the engine's defaults, not the owner's discount or tax table. To put a line on an order and a customer invoice at once, use [invoice.addEntry](method/invoice.addEntry) with `order`. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"order.create","params":{"owner":"5b22073fa4e34411b07c14a77147ce6b"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"order.addEntry","params":{"order":"00ed0000000000000000000000000001","description":"Widgets","quantity":"10","price":"2.50","account":"Income"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "guid": "…", "description": "Widgets", "quantity": { "num": "10", "denom": "1" }, "invoicePrice": { "num": "250", "denom": "100" }, "invoice": null, "order": "00ed0000000000000000000000000001", "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `order.addEntry`. - `order` (Guid, required): The open order. - `date` (Date or null): The line's date; stored as noon local time, as GnuCash's register does. Defaults to today. - `description` (string or null): Description. - `action` (string or null): Action: a free unit label such as "Hours". - `notes` (string or null): Notes. - `quantity` (Amount or null): Quantity, as printed on the document; stored negated on a credit note. - `account` (AccountRef or null): The income account (invoices) or expense account (bills, vouchers); `null` for none. - `price` (Amount or null): Unit price. A new line on a job's document defaults to the job's rate. - `discount` (Amount or null): Invoices only: the discount, a percentage or an amount. Defaults to the customer's discount. - `discountType` (AmountTypeWire or null): Invoices only: whether the discount is a percentage or an amount. - `discountHow` (DiscountHowWire or null): Invoices only: when the discount applies relative to tax. - `taxable` (boolean or null): Invoices and bills: the line is taxed. Defaults to true when a tax table applies. - `taxIncluded` (boolean or null): Invoices and bills: the price includes tax. Defaults from the customer's or vendor's setting. - `taxTable` (TaxTableRef or null): Invoices and bills: the tax table, by GUID or name; `null` for none. Defaults to the owner's table when it overrides, else the book's default. - `billable` (boolean or null): Bills and vouchers: the cost is to be invoiced on to `billTo`. - `billTo` (Guid or null): Bills and vouchers: the customer or job to invoice the cost to; `null` for none. - `payment` (PaymentWire or null): Vouchers only: cash (the employee paid) or card (the company card paid). ## Result A line. Both sides are shown; the one its document uses is `invoice*` for customer invoices and `bill*` for bills and vouchers. - `guid` (Guid, required): A GUID: 32 hexadecimal digits. - `date` (Timestamp, required): An instant, RFC 3339; written in UTC with a Z suffix. - `dateEntered` (Timestamp, required): An instant, RFC 3339; written in UTC with a Z suffix. - `description` (string, required) - `action` (string, required) - `notes` (string, required) - `quantity` (Amount, required): As stored: negated on a credit note. - `documentQuantity` (Amount, required): As printed on the document. - `invoice` (Guid or null): The customer invoice it is on. - `bill` (Guid or null): The bill or voucher it is on. - `order` (Guid or null): The order it is on. - `invoiceAccount` (Guid or null) - `invoicePrice` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `discount` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `discountType` (AmountTypeWire, required): Percentage or fixed amount. - `discountHow` (DiscountHowWire, required): When a discount applies relative to tax. - `invoiceTaxable` (boolean, required) - `invoiceTaxIncluded` (boolean, required) - `invoiceTaxTable` (Guid or null) - `billAccount` (Guid or null) - `billPrice` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `billTaxable` (boolean, required) - `billTaxIncluded` (boolean, required) - `billTaxTable` (Guid or null) - `billable` (boolean, required) - `billTo` (OwnerInfo or null) - `payment` (PaymentWire, required): How an employee paid an expense. ## Related - [order.updateEntry](method/order.updateEntry) - [order.removeEntry](method/order.removeEntry) - [invoice.addEntry](method/invoice.addEntry) --- *red-ale Manual, `method/order.addEntry`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # order.close Close an order that has lines. Closes an order that has at least one line. A closed order is frozen: no line can be added, changed or removed, and it cannot be closed again. This is the only way to set its closing date, which defaults to now. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"order.create","params":{"owner":"5b22073fa4e34411b07c14a77147ce6b"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"order.addEntry","params":{"order":"00ed0000000000000000000000000001","description":"Widgets","quantity":"10","price":"2.50","account":"Income"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"order.close","params":{"order":"00ed0000000000000000000000000001","date":"2024-07-02T09:00:00Z"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "closed": true, "dateClosed": "2024-07-02T09:00:00Z", "entryCount": 1, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"order.addEntry","params":{"order":"00ed0000000000000000000000000001","description":"More"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "error": { "code": 2003, "message": "order 000001 is closed", "data": { "help": "error/conflict" } } } ``` **Effect:** `write`, on the Book. ## Params Params of `order.close`. - `order` (Guid, required): The open order. - `date` (Timestamp or null): When it closed; defaults to now, as GnuCash's order dialog does. ## Result An order with its lines, in GnuCash's order. - `guid` (Guid, required): A GUID: 32 hexadecimal digits. - `id` (string, required) - `owner` (OwnerInfo, required): An owner: a customer, vendor, employee or job. - `dateOpened` (Timestamp, required): An instant, RFC 3339; written in UTC with a Z suffix. - `closed` (boolean, required) - `dateClosed` (Timestamp or null) - `notes` (string, required) - `reference` (string, required) - `active` (boolean, required) - `entryCount` (integer (uint), required) - `entries` (array of EntryInfo, required): Its lines. ## Related - [order.create](method/order.create) - [order.addEntry](method/order.addEntry) --- *red-ale Manual, `method/order.close`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # order.create Create an order for a customer, vendor or job. Creates an open order for a customer, vendor or job: a list of lines promised to or by someone, which invoice lines can join. It takes the next number from the `gncOrder` counter unless you give `id`. An order has no totals and no posting. Order lines use the invoice side whoever owns the order, because GnuCash's order screen is a customer-document screen. Only a customer invoice's line can join an order. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"order.create","params":{"owner":"5b22073fa4e34411b07c14a77147ce6b","reference":"PO-9"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "…", "id": "000001", "owner": { "kind": "customer", "guid": "5b22073fa4e34411b07c14a77147ce6b" }, "closed": false, "reference": "PO-9", "entryCount": 0, "entries": [], "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `order.create`. `owner` is required. - `owner` (Guid or null): A customer, vendor or job. It can change only while the order has no lines. - `id` (string or null): Order number. On create, absent or empty takes the next number from the book's `gncOrder` counter. - `dateOpened` (Date or null): Date opened; stored as noon local time. Defaults to today. - `notes` (string or null): Notes. - `reference` (string or null): Reference. - `active` (boolean or null): Active; `false` deactivates. ## Result An order with its lines, in GnuCash's order. - `guid` (Guid, required): A GUID: 32 hexadecimal digits. - `id` (string, required) - `owner` (OwnerInfo, required): An owner: a customer, vendor, employee or job. - `dateOpened` (Timestamp, required): An instant, RFC 3339; written in UTC with a Z suffix. - `closed` (boolean, required) - `dateClosed` (Timestamp or null) - `notes` (string, required) - `reference` (string, required) - `active` (boolean, required) - `entryCount` (integer (uint), required) - `entries` (array of EntryInfo, required): Its lines. ## Related - [order.addEntry](method/order.addEntry) - [order.close](method/order.close) - [customer.create](method/customer.create) --- *red-ale Manual, `method/order.create`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # order.get An order with its lines. Returns one order with its lines. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"order.create","params":{"owner":"5b22073fa4e34411b07c14a77147ce6b"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"order.get","params":{"order":"00ed0000000000000000000000000001"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "id": "000001", "closed": false, "dateClosed": null, "entryCount": 0, "entries": [], "…": "…" } } ``` **Effect:** `read`. ## Params Names one order. - `order` (Guid, required): The order. ## Result An order with its lines, in GnuCash's order. - `guid` (Guid, required): A GUID: 32 hexadecimal digits. - `id` (string, required) - `owner` (OwnerInfo, required): An owner: a customer, vendor, employee or job. - `dateOpened` (Timestamp, required): An instant, RFC 3339; written in UTC with a Z suffix. - `closed` (boolean, required) - `dateClosed` (Timestamp or null) - `notes` (string, required) - `reference` (string, required) - `active` (boolean, required) - `entryCount` (integer (uint), required) - `entries` (array of EntryInfo, required): Its lines. ## Related - [order.list](method/order.list) - [order.update](method/order.update) --- *red-ale Manual, `method/order.get`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # order.list Orders, optionally filtered. Lists orders, in GUID order and without their lines, optionally those of one owner (a customer's list includes its jobs' orders), only the open or only the closed, or only the active. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"order.list","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "orders": [] } } ``` **Effect:** `read`. ## Params Filters for `order.list`. - `owner` (Guid or null): Only this owner's orders; a customer or vendor also matches its jobs' orders. - `closed` (boolean or null): Only open (`false`) or closed (`true`) orders. - `activeOnly` (boolean): Only active orders. ## Result Orders. - `orders` (array of OrderInfo, required): In GUID order. ## Related - [order.get](method/order.get) - [order.close](method/order.close) --- *red-ale Manual, `method/order.list`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # order.removeEntry Delete a line (same as invoice.removeEntry). Deletes a line of an open order. It is the same method as [invoice.removeEntry](method/invoice.removeEntry); it is refused once the order is closed. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"order.create","params":{"owner":"5b22073fa4e34411b07c14a77147ce6b"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"order.addEntry","params":{"order":"00ed0000000000000000000000000001","description":"Widgets","quantity":"10","price":"2.50","account":"Income"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"order.removeEntry","params":{"entry":"00ed0000000000000000000000000002"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": {} } ``` **Effect:** `destructive`, on the Book. ## Params Names one line. - `entry` (Guid, required): The line. ## Result A result with nothing to report. Type: Done. ## Related - [order.addEntry](method/order.addEntry) - [invoice.removeEntry](method/invoice.removeEntry) --- *red-ale Manual, `method/order.removeEntry`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # order.update Change an order. Changes an order's number, dates, notes, reference or active state. The owner can change only while the order has no lines. To change its lines use [order.updateEntry](method/order.updateEntry). ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"order.create","params":{"owner":"5b22073fa4e34411b07c14a77147ce6b"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"order.update","params":{"order":"00ed0000000000000000000000000001","notes":"Rush"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "notes": "Rush", "closed": false, "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `order.update`: the fields to change. - `order` (Guid, required): The order. - `owner` (Guid or null): A customer, vendor or job. It can change only while the order has no lines. - `id` (string or null): Order number. On create, absent or empty takes the next number from the book's `gncOrder` counter. - `dateOpened` (Date or null): Date opened; stored as noon local time. Defaults to today. - `notes` (string or null): Notes. - `reference` (string or null): Reference. - `active` (boolean or null): Active; `false` deactivates. ## Result An order with its lines, in GnuCash's order. - `guid` (Guid, required): A GUID: 32 hexadecimal digits. - `id` (string, required) - `owner` (OwnerInfo, required): An owner: a customer, vendor, employee or job. - `dateOpened` (Timestamp, required): An instant, RFC 3339; written in UTC with a Z suffix. - `closed` (boolean, required) - `dateClosed` (Timestamp or null) - `notes` (string, required) - `reference` (string, required) - `active` (boolean, required) - `entryCount` (integer (uint), required) - `entries` (array of EntryInfo, required): Its lines. ## Related - [order.create](method/order.create) - [order.close](method/order.close) --- *red-ale Manual, `method/order.update`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # order.updateEntry Change a line of an open order (same as invoice.updateEntry). Changes a line of an open order. It is the same method as [invoice.updateEntry](method/invoice.updateEntry); it is refused once the order is closed. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"order.create","params":{"owner":"5b22073fa4e34411b07c14a77147ce6b"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"order.addEntry","params":{"order":"00ed0000000000000000000000000001","description":"Widgets","quantity":"10","price":"2.50","account":"Income"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"order.updateEntry","params":{"entry":"00ed0000000000000000000000000002","quantity":"12"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "quantity": { "num": "12", "denom": "1" }, "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `invoice.updateEntry` and `order.updateEntry`: the fields to change. - `entry` (Guid, required): The line. - `date` (Date or null): The line's date; stored as noon local time, as GnuCash's register does. Defaults to today. - `description` (string or null): Description. - `action` (string or null): Action: a free unit label such as "Hours". - `notes` (string or null): Notes. - `quantity` (Amount or null): Quantity, as printed on the document; stored negated on a credit note. - `account` (AccountRef or null): The income account (invoices) or expense account (bills, vouchers); `null` for none. - `price` (Amount or null): Unit price. A new line on a job's document defaults to the job's rate. - `discount` (Amount or null): Invoices only: the discount, a percentage or an amount. Defaults to the customer's discount. - `discountType` (AmountTypeWire or null): Invoices only: whether the discount is a percentage or an amount. - `discountHow` (DiscountHowWire or null): Invoices only: when the discount applies relative to tax. - `taxable` (boolean or null): Invoices and bills: the line is taxed. Defaults to true when a tax table applies. - `taxIncluded` (boolean or null): Invoices and bills: the price includes tax. Defaults from the customer's or vendor's setting. - `taxTable` (TaxTableRef or null): Invoices and bills: the tax table, by GUID or name; `null` for none. Defaults to the owner's table when it overrides, else the book's default. - `billable` (boolean or null): Bills and vouchers: the cost is to be invoiced on to `billTo`. - `billTo` (Guid or null): Bills and vouchers: the customer or job to invoice the cost to; `null` for none. - `payment` (PaymentWire or null): Vouchers only: cash (the employee paid) or card (the company card paid). ## Result A line. Both sides are shown; the one its document uses is `invoice*` for customer invoices and `bill*` for bills and vouchers. - `guid` (Guid, required): A GUID: 32 hexadecimal digits. - `date` (Timestamp, required): An instant, RFC 3339; written in UTC with a Z suffix. - `dateEntered` (Timestamp, required): An instant, RFC 3339; written in UTC with a Z suffix. - `description` (string, required) - `action` (string, required) - `notes` (string, required) - `quantity` (Amount, required): As stored: negated on a credit note. - `documentQuantity` (Amount, required): As printed on the document. - `invoice` (Guid or null): The customer invoice it is on. - `bill` (Guid or null): The bill or voucher it is on. - `order` (Guid or null): The order it is on. - `invoiceAccount` (Guid or null) - `invoicePrice` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `discount` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `discountType` (AmountTypeWire, required): Percentage or fixed amount. - `discountHow` (DiscountHowWire, required): When a discount applies relative to tax. - `invoiceTaxable` (boolean, required) - `invoiceTaxIncluded` (boolean, required) - `invoiceTaxTable` (Guid or null) - `billAccount` (Guid or null) - `billPrice` (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number. - `billTaxable` (boolean, required) - `billTaxIncluded` (boolean, required) - `billTaxTable` (Guid or null) - `billable` (boolean, required) - `billTo` (OwnerInfo or null) - `payment` (PaymentWire, required): How an employee paid an expense. ## Related - [order.addEntry](method/order.addEntry) - [invoice.updateEntry](method/invoice.updateEntry) --- *red-ale Manual, `method/order.updateEntry`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # payment.fromTransaction Turn an existing transaction into a payment and apply it, or re-match an existing payment; its other splits are deleted. Turns a transaction you entered by hand (a deposit that was really a customer's cheque) into a payment, as GnuCash's Assign as Payment does, or changes the matching of an existing payment. It is destructive: every split of the transaction except its transfer split, the one in a bank, cash, asset, liability or equity account, is deleted and rebuilt as the A/R or A/P split of a payment in a new lot, then applied as in [payment.process](method/payment.process). Without `applyTo` it applies to the documents the transaction already pays. A posted document's own transaction cannot be made a payment: unpost the document instead. A void or read-only transaction is refused too. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"transaction.post","params":{"datePosted":"2024-03-20","description":"Acme cheque","splits":[{"account":"Assets:Bank","value":"500.00"},{"account":"Assets:Receivable","value":"-500.00"}]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"payment.fromTransaction","params":{"transaction":"00ed0000000000000000000000000003","owner":{"type":"customer","id":"5b22073fa4e34411b07c14a77147ce6b"},"applyTo":["aa210b7131de44c48b8513cd27c00e95"]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "transaction": "00ed0000000000000000000000000003", "paymentLot": null } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"payment.openItems","params":{"owner":{"type":"customer","id":"5b22073fa4e34411b07c14a77147ce6b"},"account":"Assets:Receivable"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "items": [ { "invoice": "aa210b7131de44c48b8513cd27c00e95", "balance": { "num": "37300", "denom": "100" }, "…": "…" } ] } } ``` *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"payment.fromTransaction","params":{"transaction":"0ffd3608651e4faa8e39816c17e6a3b1"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": 2001, "message": "a posted document's transaction cannot become a payment; unpost the document", "data": { "help": "error/invalid" } } } ``` **Effect:** `destructive`, on the Book. ## Params Params of `payment.fromTransaction`. Absent params take the payment dialog's defaults. - `transaction` (Guid, required): The transaction. - `owner` (OwnerParam or null): Who pays or is paid. Default: the owner of the document or pre-payment its A/R or A/P split is in. - `account` (AccountRef or null): The A/Receivable or A/Payable account. Default: that of the transaction's A/R or A/P splits. - `transferSplit` (Guid or null): The split to keep as the payment's transfer split. Default: the only split in a bank, cash, asset, liability or equity account. - `amount` (Amount or null): The payment, signed as in `payment.process`. Default: the transfer split's amount; needed when the transfer and A/R or A/P commodities differ. - `exchangeRate` (Amount or null): Units of the transfer account's commodity per unit of the A/R or A/P account's commodity, when they differ. - `date` (Date or null): The payment date. Default: the transaction's posted date. - `memo` (string or null): Memo of the A/R or A/P split. Default: the transaction's description. - `num` (string or null): Transaction number. Default: the transaction's. - `applyTo` (array of Guid or null): Documents (invoice GUIDs) and pre-payment lots to apply it to. Default: the documents and pre-payments the transaction is already applied to that would stay open without it. - `autoPay` (boolean): With nothing to apply to: apply to all the owner's open documents and pre-payments. ## Result Result of a payment. - `transaction` (Guid or null): The payment transaction (none when the amount is zero). - `paymentLot` (Guid or null): The lot holding what was not applied: a pre-payment. ## Related - [payment.process](method/payment.process) - [payment.openItems](method/payment.openItems) - [transaction.post](method/transaction.post) --- *red-ale Manual, `method/payment.fromTransaction`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # payment.openItems An owner's open documents and pre-payments in an A/R or A/P account, in the order GnuCash's payment dialog applies them. Lists what an owner has open in an A/R or A/P account: posted documents with a balance and pre-payments, in the order GnuCash's payment dialog applies them (by due date). Pass the GUIDs it gives, in this order, as `applyTo` of [payment.process](method/payment.process) to pay as the dialog would. `balance` is signed as on the account: a customer's unpaid invoice is positive and a pre-payment is negative; for a vendor it is the other way round. `invoice` and `id` are null for a pre-payment, whose `type` is `Pre-Payment`. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"payment.openItems","params":{"owner":{"type":"customer","id":"5b22073fa4e34411b07c14a77147ce6b"},"account":"Assets:Receivable"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "items": [ { "lot": "83f95c95c93e444f8941d784bff4de2c", "invoice": "aa210b7131de44c48b8513cd27c00e95", "id": "000001", "type": "Invoice", "balance": { "num": "87300", "denom": "100" }, "…": "…" } ] } } ``` **Effect:** `read`. ## Params Params of `payment.openItems`. - `owner` (OwnerParam, required): A customer, vendor or employee. - `account` (AccountRef, required): The A/Receivable or A/Payable account. ## Result Result of `payment.openItems`. - `items` (array of OpenItem, required): In the order GnuCash's payment dialog hands chosen items to the engine. ## Related - [payment.process](method/payment.process) - [invoice.pay](method/invoice.pay) --- *red-ale Manual, `method/payment.openItems`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # payment.process Record an owner's payment and apply it to chosen documents, or to the oldest open ones. Records a payment by a customer, or to a vendor or employee, and applies it to the documents you choose (`applyTo`, in that order), or with `autoPay` to all the owner's open documents, oldest first. `amount` is in the A/R or A/P account's commodity and positive when a customer pays or you pay a vendor or employee; negative is a refund. What is left over becomes a pre-payment, a lot with no document, and is returned as `paymentLot`; it is applied later by a new payment of amount 0 naming it in `applyTo`. With neither `applyTo` nor `autoPay` the whole payment is a pre-payment. An amount of 0 records no transaction and only links the lots named. To pay in a commodity other than the account's, give `exchangeRate`. ## Examples *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"payment.process","params":{"owner":{"type":"customer","id":"5b22073fa4e34411b07c14a77147ce6b"},"account":"Assets:Receivable","transferAccount":"Assets:Bank","amount":"300.00","date":"2024-03-25","applyTo":["aa210b7131de44c48b8513cd27c00e95"]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "transaction": "…", "paymentLot": null } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"payment.openItems","params":{"owner":{"type":"customer","id":"5b22073fa4e34411b07c14a77147ce6b"},"account":"Assets:Receivable"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "items": [ { "invoice": "aa210b7131de44c48b8513cd27c00e95", "balance": { "num": "57300", "denom": "100" }, "…": "…" } ] } } ``` Paying a vendor without saying what for leaves a pre-payment: *Example: with a copy of the `synthetic/business-editable` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"payment.process","params":{"owner":{"type":"vendor","id":"9697710198334d558a9bfde219bb1e41"},"account":"Liabilities:Payable","transferAccount":"Assets:Bank","amount":"10.00","date":"2024-03-25"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "transaction": "…", "paymentLot": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `payment.process`. - `owner` (OwnerParam, required): Who pays or is paid. - `account` (AccountRef, required): The A/Receivable or A/Payable account the documents are posted to. - `transferAccount` (AccountRef or null): Where the money goes (customer payments) or comes from (vendor and employee payments). Needed unless the amount is zero. - `amount` (Amount, required): The payment, in the A/R or A/P account's commodity: positive when a customer pays or when a vendor or employee is paid; negative for a refund. Zero links the chosen documents with each other only. - `exchangeRate` (Amount or null): Units of the transfer account's commodity per unit of the A/R or A/P account's commodity, when they differ. - `date` (Date, required): The payment date. - `memo` (string or null): Memo of both splits. - `num` (string or null): Transaction number (a check number). - `applyTo` (array of Guid): Documents (invoice GUIDs) and pre-payment lots (lot GUIDs) to apply the payment to, in order. - `autoPay` (boolean): With no `applyTo`: apply to all the owner's open documents and pre-payments (GnuCash's preference, default false). ## Result Result of a payment. - `transaction` (Guid or null): The payment transaction (none when the amount is zero). - `paymentLot` (Guid or null): The lot holding what was not applied: a pre-payment. ## Related - [invoice.pay](method/invoice.pay) - [payment.openItems](method/payment.openItems) - [payment.fromTransaction](method/payment.fromTransaction) --- *red-ale Manual, `method/payment.process`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # period.dates The first and last days of the accounting period containing today or a given date. Gives the first and last day of the accounting period containing a date, by default today (the local date of the session's clock, or of the server's with no book open). `start`, `end` and `fiscalYearEnd` override the configured bounds for this call only. `startTime` and `endTime` are the instants GnuCash uses: local 00:00:00 of the first day and 23:59:59 of the last. Use it to work out the dates to pass to a report or to [transaction.list](method/transaction.list). A fiscal year starts the day after the fiscal year end of the previous year, so with a year ending 31 March, 15 July 2024 falls in 2024-04-01 to 2025-03-31. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`, at 2024-07-15T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"period.dates","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "today": "2024-07-15", "start": "2024-01-01", "end": "2024-12-31", "startTime": "2024-01-01T00:00:00Z", "endTime": "2024-12-31T23:59:59Z" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"period.dates","params":{"start":"fiscal-year","end":"fiscal-year","fiscalYearEnd":"03-31"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "start": "2024-04-01", "end": "2025-03-31", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"period.dates","params":{"date":"2024-02-15","start":"previous-quarter","end":"previous-quarter"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "start": "2023-10-01", "end": "2023-12-31", "…": "…" } } ``` It needs no book; today is then the server's: *Example: with no book, at 2024-11-20T09:30:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"period.dates","params":{"start":"quarter","end":"quarter"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "today": "2024-11-20", "start": "2024-10-01", "end": "2024-12-31", "startTime": "2024-10-01T00:00:00Z", "endTime": "2024-12-31T23:59:59Z" } } ``` **Effect:** `read`. ## Params Params of `period.dates`. The optional fields override the configured setting for this call only. - `date` (Date or null): The day the period must contain; by default today in the local time zone. - `start` (string or null): Start, instead of the configured one. - `end` (string or null): End, instead of the configured one. - `fiscalYearEnd` (string or null): Fiscal year end, `MM-DD`, instead of the configured one. ## Result The result of `period.dates`. - `today` (Date, required): The day used as today. - `start` (Date, required): First day of the period (GnuCash starts it at 00:00:00 local time). - `end` (Date, required): Last day of the period (GnuCash ends it at 23:59:59 local time). - `startTime` (Timestamp, required): The period's first instant: local 00:00:00 on `start`. - `endTime` (Timestamp, required): The period's last instant: local 23:59:59 on `end`. ## Related - [period.get](method/period.get) - [period.set](method/period.set) --- *red-ale Manual, `method/period.dates`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # period.get The configured accounting period and fiscal year end. Reads the accounting period: the start and end bounds that reports and account totals use by default (GnuCash's Accounting Period preferences), and the fiscal year end. A bound is a relative choice (`today`, `month`, `previous-month`, `quarter`, `previous-quarter`, `year`, `previous-year`, `fiscal-year`, `previous-fiscal-year`) or a `YYYY-MM-DD` date. The default is `year` for both. GnuCash keeps these as user preferences, not in the book; red-ale keeps them in its Configuration, so the call works with no book open. ## Examples *Example: with no book.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"period.get","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "start": "year", "end": "year", "fiscalYearEnd": null, "fiscalYearEndSource": null, "choices": [ "today", "month", "previous-month", "quarter", "previous-quarter", "year", "previous-year", "fiscal-year", "previous-fiscal-year" ], "…": "…" } } ``` **Effect:** `read`. ## Params Params for methods that take none. Type: NoParams. ## Result The accounting period setting. - `start` (string, required): Start: a relative choice (`today`, `month`, `previous-month`, `quarter`, `previous-quarter`, `year`, `previous-year`, `fiscal-year`, `previous-fiscal-year`) or a `YYYY-MM-DD` date. - `end` (string, required): End, in the same form; a relative choice means the period's last day. - `fiscalYearEnd` (string or null): The fiscal year end in use (`MM-DD`), if any. - `fiscalYearEndSource` (string or null): Where it comes from: `config`, or `book` (the open book's `fy_end` slot). - `configFile` (string or null): The configuration file, if the setting is kept in one; otherwise it lasts as long as the server. - `choices` (array of string, required): Every relative choice, in GnuCash's order. ## Related - [period.set](method/period.set) - [period.dates](method/period.dates) --- *red-ale Manual, `method/period.get`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # period.set Set the accounting period or the fiscal year end in red-ale's configuration. Sets the accounting period's start and end bounds or the fiscal year end (`MM-DD`) in red-ale's Configuration, and returns the result as [period.get](method/period.get) does. It changes no book and works with no book open. Use `clearFiscalYearEnd: true` to remove the fiscal year end. A fiscal choice (`fiscal-year`, `previous-fiscal-year`) is refused with `invalid` unless a fiscal year end is known, from the Configuration or from the open book's own slot; GnuCash would silently return the epoch. ## Examples *Example: with no book.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"period.set","params":{"start":"fiscal-year"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": 2001, "message": "…", "data": { "help": "error/invalid" } } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"period.set","params":{"start":"fiscal-year","end":"fiscal-year","fiscalYearEnd":"03-31"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "start": "fiscal-year", "end": "fiscal-year", "fiscalYearEnd": "03-31", "fiscalYearEndSource": "config", "…": "…" } } ``` **Effect:** `write`, on the Configuration only. ## Params Params of `period.set`. Absent fields keep their setting. - `start` (string or null): Start: a relative choice or a `YYYY-MM-DD` date. - `end` (string or null): End: a relative choice or a `YYYY-MM-DD` date. - `fiscalYearEnd` (string or null): Fiscal year end, `MM-DD`, for the fiscal-year choices. - `clearFiscalYearEnd` (boolean): Remove the configured fiscal year end (the open book's `fy_end` slot, if any, then applies). ## Result The accounting period setting. - `start` (string, required): Start: a relative choice (`today`, `month`, `previous-month`, `quarter`, `previous-quarter`, `year`, `previous-year`, `fiscal-year`, `previous-fiscal-year`) or a `YYYY-MM-DD` date. - `end` (string, required): End, in the same form; a relative choice means the period's last day. - `fiscalYearEnd` (string or null): The fiscal year end in use (`MM-DD`), if any. - `fiscalYearEndSource` (string or null): Where it comes from: `config`, or `book` (the open book's `fy_end` slot). - `configFile` (string or null): The configuration file, if the setting is kept in one; otherwise it lasts as long as the server. - `choices` (array of string, required): Every relative choice, in GnuCash's order. ## Related - [period.get](method/period.get) - [period.dates](method/period.dates) - [invalid](error/invalid) --- *red-ale Manual, `method/period.set`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # price.add Add a price; a same-day price of the pair is replaced or wins by source precedence, as GnuCash does. Adds a price: `value` units of `currency` per unit of `commodity` on a `date` (or at an exact `time`), kept exactly as given, so `"1.0850"` is stored as 10850/10000. The `source` defaults to `user:price-editor`, the price editor's, and must be one of GnuCash's eleven source strings (`Finance::Quote`, `user:price`, `user:xfer-dialog`, …) so that GnuCash reads it back the same. A same-day price of the pair (in either direction) is handled as GnuCash does. One with a better-ranked source blocks the new one: `outcome` is `rejected` and `existing` names it. Otherwise it is replaced (`outcome` `replaced`, with the old GUID in `replaced`). Adding the same price twice therefore replaces the first, as in GnuCash, which removes the old price before it looks for an identical one. `outcome` is `duplicate` only when another identical price of that day is still there, which only a book GnuCash wrote can hold. ## Examples *Example: with a new, empty book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"price.add","params":{"commodity":"EUR","currency":"USD","value":"1.0850","date":"2024-06-28"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "outcome": "added", "price": { "commodity": "CURRENCY::EUR", "currency": "CURRENCY::USD", "date": "2024-06-28", "source": "user:price-editor", "value": { "num": "10850", "denom": "10000" }, "…": "…" }, "replaced": null, "existing": null } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"price.add","params":{"commodity":"EUR","currency":"USD","value":"1.0900","date":"2024-06-28","source":"Finance::Quote"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "outcome": "rejected", "price": null, "replaced": null, "existing": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"price.add","params":{"commodity":"EUR","currency":"USD","value":"1.0850","date":"2024-06-28"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "result": { "outcome": "replaced", "price": { "date": "2024-06-28", "value": { "num": "10850", "denom": "10000" }, "…": "…" }, "replaced": "…", "existing": null } } ``` **Effect:** `write`, on the Book. ## Params Params of `price.add`. - `commodity` (CommodityId, required): The commodity priced. - `currency` (CommodityId, required): The currency (or commodity) the value is in. - `value` (Amount, required): Units of `currency` per unit of `commodity`; stored exactly as given. - `date` (Date or null): The day it applies, stored at its day-neutral time as the price editor does. Give this or `time`. - `time` (Timestamp or null): The exact time it applies. Give this or `date`. - `source` (string or null): One of GnuCash's price sources; default `user:price-editor`. - `type` (string or null): Its type, such as `last`, `bid`, `ask`, `nav` or `unknown`. ## Result What `price.add` did. - `outcome` (string, required): `added`, `replaced` (added, removing a same-day price), `rejected` (a same-day price with a better source is kept) or `duplicate` (another identical same-day price is still there once `replaced` is removed; nothing added). - `price` (PriceInfo or null): The price added. - `replaced` (Guid or null): The same-day price removed. - `existing` (Guid or null): The price that made this one rejected or a duplicate. ## Related - [price.list](method/price.list) - [price.update](method/price.update) - [price.latest](method/price.latest) --- *red-ale Manual, `method/price.add`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # price.delete Delete a price. Deletes one price and returns it. To thin out many old prices at once, use [price.removeOld](method/price.removeOld) instead. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"price.delete","params":{"price":"e0000000000000000000000000000000"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "e0000000000000000000000000000000", "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"price.list","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": [ { "guid": "e0000000000000000000000000000001", "…": "…" } ] } ``` **Effect:** `destructive`, on the Book. ## Params Params naming one price. - `price` (Guid, required): The price's GUID. ## Result A price. - `guid` (Guid, required): Identity. - `commodity` (CommodityId, required): The commodity priced. - `currency` (CommodityId, required): The currency (or commodity) the value is in. - `time` (Timestamp, required): When the price applies. - `date` (Date or null): The local day of `time`, which the same-day rules use. - `source` (string or null): Where it came from, such as `user:price-editor` or `Finance::Quote`; kept as read even when GnuCash does not know it. - `type` (string or null): Its type, such as `last`, `bid`, `ask`, `nav`, `transaction` or `unknown`. - `value` (Amount, required): Units of `currency` per unit of `commodity`, exactly as stored. ## Related - [price.removeOld](method/price.removeOld) - [price.list](method/price.list) --- *red-ale Manual, `method/price.delete`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # price.fetchQuotes Start a Quote fetch of online prices; returns its ID at once. Starts fetching online prices for commodities that have a quote source, and returns a fetch ID at once; poll [price.fetchStatus](method/price.fetchStatus) for the outcome. With no `commodities` it fetches every commodity GnuCash would (its quote flag on and a supported source); `namespace` limits it to a namespace. The network is off by default: until the Configuration setting `quotes.network` is true the call fails with [network-disabled](error/network-disabled) and sends nothing. A person turns it on with [config.set](method/config.set); over MCP the setting cannot be changed. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"price.fetchQuotes","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": 5000, "message": "…", "data": { "help": "error/network-disabled" } } } ``` **Effect:** `write`, on the Book. ## Params Params of `price.fetchQuotes`. - `commodities` (array of CommodityId or null): Fetch these, whatever their quote flag; each needs a quote source (a currency has `currency`). Default: every commodity with quotes on and a quote source. - `namespace` (string or null): Only commodities in namespaces matching this pattern, case-insensitive and unanchored, as `gnucash-cli --namespace`. Not with `commodities`. ## Result What `price.fetchQuotes` started. - `fetch` (string, required): The Quote fetch's ID, for `price.fetchStatus`. - `commodities` (array of CommodityId, required): The commodities it covers, in the order fetched. ## Related - [price.fetchStatus](method/price.fetchStatus) - [config.set](method/config.set) - [network-disabled](error/network-disabled) --- *red-ale Manual, `method/price.fetchQuotes`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # price.fetchStatus A Quote fetch's state and, per commodity, the price stored or why there is none. Reports a quote fetch: whether it is running or finished and, for each commodity, the price stored or why none was. `fetch` is the ID [price.fetchQuotes](method/price.fetchQuotes) returned; leave it out for the latest fetch. With no fetch started it fails with `not-found`. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"price.fetchStatus","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": 2000, "message": "…", "data": { "kind": "quoteFetch", "id": "latest", "help": "error/not-found" } } } ``` **Effect:** `read`. ## Params Params of `price.fetchStatus`. - `fetch` (string or null): The Quote fetch; default the latest. ## Result A Quote fetch. - `fetch` (string, required): Its ID. - `state` (FetchState, required): `running` or `finished`. - `started` (Timestamp, required): When it started. - `finished` (Timestamp or null): When its prices were stored; null while running. - `commodities` (array of CommodityFetch, required): One entry per commodity, in the order fetched. - `stored` (integer (uint) or null): Commodities whose price went through `price.add`'s rules, once finished. - `failed` (integer (uint) or null): Commodities with no price, once finished. ## Related - [price.fetchQuotes](method/price.fetchQuotes) --- *red-ale Manual, `method/price.fetchStatus`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # price.get Describe one price. Describes one price by GUID: the commodity, the currency, the time and local date, the source, the type and the value. GUIDs come from [price.list](method/price.list) and [price.add](method/price.add). ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"price.get","params":{"price":"e0000000000000000000000000000001"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "guid": "e0000000000000000000000000000001", "commodity": "CURRENCY::GBP", "currency": "CURRENCY::USD", "date": "2000-02-15", "source": "user:xfer-dialog", "type": "test", "value": { "num": "3", "denom": "2" }, "…": "…" } } ``` **Effect:** `read`. ## Params Params naming one price. - `price` (Guid, required): The price's GUID. ## Result A price. - `guid` (Guid, required): Identity. - `commodity` (CommodityId, required): The commodity priced. - `currency` (CommodityId, required): The currency (or commodity) the value is in. - `time` (Timestamp, required): When the price applies. - `date` (Date or null): The local day of `time`, which the same-day rules use. - `source` (string or null): Where it came from, such as `user:price-editor` or `Finance::Quote`; kept as read even when GnuCash does not know it. - `type` (string or null): Its type, such as `last`, `bid`, `ask`, `nav`, `transaction` or `unknown`. - `value` (Amount, required): Units of `currency` per unit of `commodity`, exactly as stored. ## Related - [price.list](method/price.list) - [price.update](method/price.update) --- *red-ale Manual, `method/price.get`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # price.latest The latest price of a commodity in a currency, either direction. Gives the newest price of a commodity in a currency, looking in both directions. The result has the stored `price`, `reversed` (true when the price is stored the other way round) and `rate`, the value in the direction you asked for: the exact inverse when reversed. The result is null when there is no price. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"price.latest","params":{"commodity":"USD","currency":"GBP"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "price": { "guid": "e0000000000000000000000000000001", "…": "…" }, "reversed": true, "rate": { "num": "2", "denom": "3" } } } ``` **Effect:** `read`. ## Params Params of `price.latest`. - `commodity` (CommodityId, required): The commodity priced. - `currency` (CommodityId, required): The currency wanted. ## Result Type: FoundPrice or null. ## Related - [price.nearest](method/price.nearest) - [price.list](method/price.list) --- *red-ale Manual, `method/price.latest`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # price.list List prices, by commodity, currency and date range, in GnuCash's order. Lists prices in the order GnuCash writes them: by commodity, then currency, newest first. Give `commodity` to list one commodity's prices, `currency` as well to narrow it to a pair, `bothDirections` to include the pair's prices the other way round, and `from` and `to` (inclusive local days) to limit the dates. The result is a plain array. A book may hold several prices of a pair on one day (loading a file applies no same-day rule). ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"price.list","params":{"commodity":"GBP","currency":"USD","bothDirections":true}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": [ { "guid": "e0000000000000000000000000000001", "commodity": "CURRENCY::GBP", "currency": "CURRENCY::USD", "value": { "num": "3", "denom": "2" }, "…": "…" }, { "guid": "e0000000000000000000000000000000", "commodity": "CURRENCY::USD", "currency": "CURRENCY::GBP", "value": { "num": "5", "denom": "7" }, "…": "…" } ] } ``` **Effect:** `read`. ## Params Params of `price.list`. - `commodity` (CommodityId or null): Only prices of this commodity. - `currency` (CommodityId or null): Only prices in this currency (needs `commodity`). - `bothDirections` (boolean): Also prices of `currency` in `commodity` (needs both). - `from` (Date or null): Only prices from local 00:00:00 on this day. - `to` (Date or null): Only prices up to local 23:59:59 on this day. ## Result Type: array of PriceInfo. ## Related - [price.get](method/price.get) - [price.latest](method/price.latest) - [price.nearest](method/price.nearest) --- *red-ale Manual, `method/price.list`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # price.nearest The price of a commodity in a currency nearest to a time, before it, or on its day. Gives the price of a commodity in a currency nearest to a `date` or `time`, in both directions. `mode` is `nearest` (the default: the closer of the newest price at or before and the oldest after, a tie going to the older), `before` (the newest at or before) or `sameDay`. GnuCash has no "nearest after", and neither does red-ale. Conversions at a past date, such as a foreign-currency transfer, use this. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"price.nearest","params":{"commodity":"GBP","currency":"USD","date":"2000-01-20"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "price": { "guid": "e0000000000000000000000000000000", "date": "2000-01-15", "…": "…" }, "reversed": true, "rate": { "num": "7", "denom": "5" } } } ``` **Effect:** `read`. ## Params Params of `price.nearest`. - `commodity` (CommodityId, required): The commodity priced. - `currency` (CommodityId, required): The currency wanted. - `date` (Date or null): A day, meaning its neutral time (10:59 UTC from UTC−10 to UTC+13). Give this or `time`. - `time` (Timestamp or null): An exact time. Give this or `date`. - `mode` (NearestMode): `nearest` (default), `before` or `sameDay`. ## Result Type: FoundPrice or null. ## Related - [price.latest](method/price.latest) - [price.list](method/price.list) --- *red-ale Manual, `method/price.nearest`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # price.removeOld Remove old prices, keeping the last of each week, month, quarter or fiscal year. GnuCash's Edit > Prices > Remove Old Prices: removes prices of the named `commodities` (in every currency) from before `before`, keeping the last price of each week, month, quarter or fiscal year (`keep`: `none`, `lastOfWeek` (the default), `lastOfMonth`, `lastOfQuarter`, `lastOfPeriod` or `scaled`). Only prices from the chosen `sources` are candidates: `fetched` (the default; `Finance::Quote`), `user` (only `user:price`) and `app` (every other source, the price editor's and the transfer dialog's included). Pitfall: GnuCash compares periods by number only, so January 2022 is "the same month" as January 2023; red-ale reproduces that, so thinning prices over several years can remove more than you expect. Use `lastOfPeriod` for a fiscal-year comparison without it. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"price.removeOld","params":{"commodities":["GBP"],"before":"2001-01-01","sources":["app"],"keep":"none"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "removed": [ "e0000000000000000000000000000001" ] } } ``` **Effect:** `destructive`, on the Book. ## Params Params of `price.removeOld`. - `commodities` (array of CommodityId, required): The commodities whose prices (in any currency) are considered; at least one. - `before` (Date, required): Only prices before this day's neutral time are considered. - `sources` (array of RemoveSource): Which sources may be removed; default `["fetched"]`. - `keep` (KeepOption): What to keep; default `lastOfWeek`. - `fiscalYearEnd` (Date or null): The last day of a fiscal year, for quarters and periods; default 31 December of the current year. ## Result What `price.removeOld` removed. - `removed` (array of Guid, required): The prices removed. ## Related - [price.delete](method/price.delete) - [period.get](method/period.get) --- *red-ale Manual, `method/price.removeOld`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # price.update Edit a price's value, time, source, type, commodity or currency, as the price editor does. Edits a price as the price editor does: its value, time, source, type, commodity or currency. Changing the commodity, currency or time re-adds the price, so the same-day rules apply against the others. Where GnuCash would then drop the edited price itself (a better-ranked same-day price exists, or an identical one), red-ale refuses with `conflict` and changes nothing. `type: null` clears the type. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"price.update","params":{"price":"e0000000000000000000000000000001","value":"1.55","type":"last"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "price": { "guid": "e0000000000000000000000000000001", "type": "last", "value": { "num": "155", "denom": "100" }, "…": "…" }, "replaced": null } } ``` **Effect:** `write`, on the Book. ## Params Params of `price.update`. Absent fields are kept. - `price` (Guid, required): The price to edit. - `commodity` (CommodityId or null): New commodity. - `currency` (CommodityId or null): New currency. - `date` (Date or null): New day (its neutral time). - `time` (Timestamp or null): New exact time. - `source` (string or null): New source: one of GnuCash's price sources. - `type` (string or null): New type; null clears it. - `value` (Amount or null): New value, stored exactly. ## Result What `price.update` did. - `price` (PriceInfo, required): The price as it now is. - `replaced` (Guid or null): A same-day price it replaced after moving. ## Related - [price.get](method/price.get) - [price.add](method/price.add) - [conflict](error/conflict) --- *red-ale Manual, `method/price.update`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # reconcile.autoClear Auto-clear an account: mark cleared the one set of uncleared splits that brings its cleared balance to a figure. Auto-clears an account: marks cleared (`c`) the one set of uncleared splits that brings its cleared balance to `clearedBalance`. It is [reconcile.findAutoClear](method/reconcile.findAutoClear) followed by setting those splits cleared, in one step. If no set reaches the figure, it is refused with `invalid` and `data.reason` `unreachable`, and nothing is cleared. ## Examples *Example: with a copy of the `reports/reconcile` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"reconcile.autoClear","params":{"account":"Root:Asset:Bank","clearedBalance":"6.00"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "outcome": "found", "splits": [ { "split": "d0000000000000000000000000000006", "…": "…" } ], "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"reconcile.autoClear","params":{"account":"Root:Asset:Bank","clearedBalance":"99.00"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "error": { "code": 2001, "message": "…", "data": { "reason": "unreachable", "help": "error/invalid" } } } ``` **Effect:** `write`, on the Book. ## Params Params of `reconcile.findAutoClear` and `reconcile.autoClear`. - `account` (AccountRef, required): The account; its sub-accounts are not included. - `clearedBalance` (Amount, required): The cleared balance wanted, raw sign (debits positive). Rounded to the account's SCU with banker's rounding. ## Result The result of an auto-clear search. - `account` (Guid, required): The account. - `currentClearedBalance` (Amount, required): The account's cleared balance before auto-clear: every split not `n`, raw sign. - `clearedBalance` (Amount, required): The cleared balance asked for, rounded to the account's SCU. - `outcome` (OutcomeWire, required): What the search found. - `message` (string or null): GnuCash's message for an outcome other than `found`. - `splits` (array of ClearedSplit, required): The splits found, in account order; empty unless `found`. ## Related - [reconcile.findAutoClear](method/reconcile.findAutoClear) - [reconcile.finish](method/reconcile.finish) - [invalid](error/invalid) --- *red-ale Manual, `method/reconcile.autoClear`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # reconcile.findAutoClear Find the one set of uncleared splits that brings an account's cleared balance to a figure, as GnuCash's Auto-clear does. Finds, without changing anything, the one set of uncleared splits that would bring an account's cleared balance to `clearedBalance`, as GnuCash's Auto-clear button searches. `outcome` says whether it was `found`; the `splits` are those to clear. If several sets reach the figure, or none does, no choice is made for you. ## Examples *Example: with a copy of the `reports/reconcile` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"reconcile.findAutoClear","params":{"account":"Root:Asset:Bank","clearedBalance":"6.00"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "currentClearedBalance": { "num": "2100", "denom": "100" }, "outcome": "found", "splits": [ { "split": "d0000000000000000000000000000006", "description": "desc-4", "amount": { "num": "-1500", "denom": "100" }, "…": "…" } ], "…": "…" } } ``` **Effect:** `read`. ## Params Params of `reconcile.findAutoClear` and `reconcile.autoClear`. - `account` (AccountRef, required): The account; its sub-accounts are not included. - `clearedBalance` (Amount, required): The cleared balance wanted, raw sign (debits positive). Rounded to the account's SCU with banker's rounding. ## Result The result of an auto-clear search. - `account` (Guid, required): The account. - `currentClearedBalance` (Amount, required): The account's cleared balance before auto-clear: every split not `n`, raw sign. - `clearedBalance` (Amount, required): The cleared balance asked for, rounded to the account's SCU. - `outcome` (OutcomeWire, required): What the search found. - `message` (string or null): GnuCash's message for an outcome other than `found`. - `splits` (array of ClearedSplit, required): The splits found, in account order; empty unless `found`. ## Related - [reconcile.autoClear](method/reconcile.autoClear) - [reconcile.start](method/reconcile.start) --- *red-ale Manual, `method/reconcile.findAutoClear`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # reconcile.finish Finish a reconciliation: ticked splits become reconciled and the statement date becomes the last reconcile date. Finishes a reconciliation: every ticked split becomes reconciled (`y`) with the statement date as its reconcile date, and the statement date becomes the account's last reconcile date. A postponed reconciliation is cleared. It is refused with `invalid` unless the `difference` is zero, the message saying how far off it is; `force: true` finishes anyway, as GnuCash does when you confirm "The account is not balanced". Unticked splits keep their state. ## Examples *Example: with a copy of the `reports/reconcile` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"reconcile.finish","params":{"account":"Root:Asset:Bank","statementDate":"1970-03-01","endingBalance":"21.00","ticked":["d0000000000000000000000000000005"]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "reconciled": [ { "split": "d0000000000000000000000000000005", "transaction": "c0000000000000000000000000000002", "from": "c", "to": "y" } ], "difference": { "num": "0", "denom": "100" }, "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"reconcile.info","params":{"account":"Root:Asset:Bank"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "lastDate": "…", "postponeDate": null, "…": "…" } } ``` An unbalanced statement is refused: *Example: with a copy of the `reports/reconcile` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"reconcile.finish","params":{"account":"Root:Asset:Bank","statementDate":"1970-03-01","endingBalance":"9.00","ticked":[]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": 2001, "message": "…", "data": { "help": "error/invalid" } } } ``` **Effect:** `write`, on the Book. ## Params Params of `reconcile.finish` and `reconcile.postpone`. - `account` (AccountRef, required): The account reconciled. - `statementDate` (Date, required): The statement date. - `endingBalance` (Amount, required): The statement's ending balance, raw sign. - `includeSubaccounts` (boolean or null): Reconcile the sub-accounts too. Defaults to the account's stored choice. - `utcOffsetMinutes` (integer (int32) or null): A fixed offset from UTC in minutes to use instead of the server's local time zone. - `ticked` (array of Guid, required): The ticked splits. - `force` (boolean): `reconcile.finish` only: finish even though the difference is not zero (GnuCash's "finish anyway"). ## Result What `reconcile.finish` did. - `reconciled` (array of StateChangeWire, required): The splits now reconciled. - `statementTime` (Timestamp, required): The statement date, now the last reconcile date and the splits' reconcile date. - `lastInterval` (IntervalWire or null): The interval recorded for proposing the next statement date. - `difference` (Amount, required): The difference at Finish (zero unless forced). ## Related - [reconcile.start](method/reconcile.start) - [reconcile.postpone](method/reconcile.postpone) - [reconcile.info](method/reconcile.info) - [invalid](error/invalid) --- *red-ale Manual, `method/reconcile.finish`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # reconcile.info An account's reconcile information: last reconcile date and interval, postponed reconciliation. Reads an account's reconcile information: the date of the last reconciliation, the interval between statements, a postponed reconciliation (its date and balance) and whether sub-accounts are included. All null for an account never reconciled. [reconcile.start](method/reconcile.start) uses the last date plus the interval as the next statement date. ## Examples *Example: with a copy of the `reports/reconcile` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"reconcile.info","params":{"account":"Root:Asset:Bank"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "lastDate": null, "lastInterval": null, "postponeDate": null, "postponeBalance": null, "includeSubaccounts": false, "…": "…" } } ``` **Effect:** `read`. ## Params Params naming an account. - `account` (AccountRef, required): The account. ## Result An account's reconcile information. - `account` (Guid, required): The account. - `lastDate` (Timestamp or null): When it was last reconciled. - `lastInterval` (IntervalWire or null): The interval between its last two reconciliations. - `postponeDate` (Timestamp or null): A postponed reconciliation's statement date. - `postponeBalance` (Amount or null): A postponed reconciliation's ending balance, raw sign. - `includeSubaccounts` (boolean, required): Reconciliations include sub-accounts. ## Related - [reconcile.setInfo](method/reconcile.setInfo) - [reconcile.start](method/reconcile.start) --- *red-ale Manual, `method/reconcile.info`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # reconcile.postpone Postpone a reconciliation: ticked splits become cleared and the statement is kept for next time. Postpones a reconciliation, GnuCash's Postpone button: the ticked splits become cleared (`c`), every other listed split posted on or before the statement date goes back to new (`n`), and the statement date and ending balance are kept in the account so the next [reconcile.start](method/reconcile.start) picks them up (`resumedPostponed`). Use it when the statement does not add up yet and you want to carry on later. A split that was cleared but is not in `ticked` loses its cleared state, as when you untick it in GnuCash's window, so pass every split you want kept: start with the `ticked` that `reconcile.start` gives. Splits after the statement date that you did not tick are left as they are. ## Examples *Example: with a copy of the `reports/reconcile` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"reconcile.postpone","params":{"account":"Root:Asset:Bank","statementDate":"1970-03-01","endingBalance":"1.00","ticked":["d0000000000000000000000000000000"]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "changed": [ { "split": "d0000000000000000000000000000005", "from": "c", "to": "n", "…": "…" }, { "split": "d0000000000000000000000000000000", "from": "n", "to": "c", "…": "…" } ], "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"reconcile.start","params":{"account":"Root:Asset:Bank"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "resumedPostponed": true, "endingBalance": { "num": "100", "denom": "100" }, "…": "…" } } ``` Without ticks, the cleared split of 31 December goes back to `n`, and the one of 1 February, after the statement date, stays cleared: *Example: with a copy of the `reports/reconcile` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"reconcile.setState","params":{"split":"d0000000000000000000000000000006","state":"c"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"reconcile.postpone","params":{"account":"Root:Asset:Bank","statementDate":"1970-01-15","endingBalance":"24.00","ticked":[]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "changed": [ { "split": "d0000000000000000000000000000005", "from": "c", "to": "n", "…": "…" } ], "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `reconcile.finish` and `reconcile.postpone`. - `account` (AccountRef, required): The account reconciled. - `statementDate` (Date, required): The statement date. - `endingBalance` (Amount, required): The statement's ending balance, raw sign. - `includeSubaccounts` (boolean or null): Reconcile the sub-accounts too. Defaults to the account's stored choice. - `utcOffsetMinutes` (integer (int32) or null): A fixed offset from UTC in minutes to use instead of the server's local time zone. - `ticked` (array of Guid, required): The ticked splits. - `force` (boolean): `reconcile.finish` only: finish even though the difference is not zero (GnuCash's "finish anyway"). ## Result What `reconcile.postpone` did. - `changed` (array of StateChangeWire, required): Splits whose state changed: ticked ones to `c`, unticked ones posted by the statement date to `n`. - `statementTime` (Timestamp, required): The statement date kept for next time. - `lastInterval` (IntervalWire or null): The interval recorded for proposing the next statement date. ## Related - [reconcile.start](method/reconcile.start) - [reconcile.finish](method/reconcile.finish) - [reconcile.info](method/reconcile.info) --- *red-ale Manual, `method/reconcile.postpone`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # reconcile.setInfo Set or remove an account's last reconcile date, interval, postponed reconciliation or sub-account flag. Sets or removes an account's reconcile information: the last reconcile date, the interval between statements (`{months, days}`), a postponed reconciliation (`{date, balance}`) and whether sub-accounts are included. A field you leave out is kept; `null` removes it. Use it to correct the dates after importing a book, or to drop a postponed reconciliation you no longer want. ## Examples *Example: with a copy of the `reports/reconcile` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"reconcile.setInfo","params":{"account":"Root:Asset:Bank","lastInterval":{"months":1,"days":0}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "lastInterval": { "months": 1, "days": 0 }, "lastDate": null, "…": "…" } } ``` **Effect:** `write`, on the Book. ## Params Params of `reconcile.setInfo`. An absent field is left alone; `null` removes it. - `account` (AccountRef, required): The account. - `lastDate` (Timestamp or null): The last reconcile date. - `lastInterval` (IntervalWire or null): The interval between reconciliations. - `postpone` (PostponeWire or null): A postponed reconciliation; `null` clears it. - `includeSubaccounts` (boolean or null): Whether reconciliations include sub-accounts. ## Result An account's reconcile information. - `account` (Guid, required): The account. - `lastDate` (Timestamp or null): When it was last reconciled. - `lastInterval` (IntervalWire or null): The interval between its last two reconciliations. - `postponeDate` (Timestamp or null): A postponed reconciliation's statement date. - `postponeBalance` (Amount or null): A postponed reconciliation's ending balance, raw sign. - `includeSubaccounts` (boolean, required): Reconciliations include sub-accounts. ## Related - [reconcile.info](method/reconcile.info) --- *red-ale Manual, `method/reconcile.setInfo`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # reconcile.setState Set a split's reconcile state (n, c, y or f); y stamps the reconcile date. Sets the reconcile state of one split: `n` (new), `c` (cleared), `y` (reconciled) or `f` (frozen). Setting `y` stamps the reconcile date with `date`, which GnuCash's engine leaves to its reconcile window; red-ale stamps it so a reconciled split always says when. `date` is a day, stamped at 23:59:59 local time as the reconcile window stamps a statement date, or an RFC 3339 timestamp for an exact time; by default it is now. Prefer [reconcile.finish](method/reconcile.finish) to reconcile a whole statement. `v` (void) cannot be set; it comes only from [transaction.void](method/transaction.void), and the splits of a voided transaction cannot be changed (`conflict`). ## Examples *Example: with a copy of the `reports/reconcile` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"reconcile.setState","params":{"split":"d0000000000000000000000000000000","state":"c"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "split": "d0000000000000000000000000000000", "transaction": "c0000000000000000000000000000000", "state": "c", "reconcileDate": null } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"reconcile.setState","params":{"split":"d0000000000000000000000000000002","state":"c"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "error": { "code": 2003, "message": "…", "data": { "help": "error/conflict" } } } ``` Reconciling a split as of a statement's day: *Example: with a copy of the `reports/reconcile` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"reconcile.setState","params":{"split":"d0000000000000000000000000000000","state":"y","date":"1970-01-31"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "split": "d0000000000000000000000000000000", "transaction": "c0000000000000000000000000000000", "state": "y", "reconcileDate": "1970-01-31T23:59:59Z" } } ``` **Effect:** `write`, on the Book. ## Params Params of `reconcile.setState`. - `split` (Guid, required): The split. - `state` (State, required): The new state: `n`, `c`, `y` or `f`. `v` comes only from voiding the transaction. - `date` (ReconcileDate or null): With `y` only: the reconcile date, `YYYY-MM-DD` for the end of that local day (as the reconcile window stamps its statement date), or an RFC 3339 timestamp for an exact time. Defaults to now. ## Result A split's reconcile state. - `split` (Guid, required): The split. - `transaction` (Guid, required): Its transaction. - `state` (State, required): Its reconcile state. - `reconcileDate` (Timestamp or null): When it was reconciled, if a date is stored. ## Related - [reconcile.finish](method/reconcile.finish) - [transaction.get](method/transaction.get) --- *red-ale Manual, `method/reconcile.setState`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # reconcile.start Start reconciling an account against a statement: GnuCash's defaults, the splits to tick and the balances. Begins reconciling an account against a bank statement, as GnuCash's Reconcile dialog opens. It fills in GnuCash's defaults (the statement date, the ending balance, a postponed reconciliation if there is one), lists the account's uncleared and cleared splits with the cleared ones already ticked, and shows the balances: `startingBalance`, `tickedBalance`, `reconciledBalance` and the `difference` from the `endingBalance`. It changes nothing. red-ale keeps no reconciliation window: you carry the statement and the ticked splits from call to call and hand them to [reconcile.status](method/reconcile.status), then to [reconcile.finish](method/reconcile.finish) or [reconcile.postpone](method/reconcile.postpone). Amounts use the account's raw sign (debits positive), whatever sign GnuCash's window would show for a credit account. ## Examples *Example: with a copy of the `reports/reconcile` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"reconcile.start","params":{"account":"Root:Asset:Bank","statementDate":"1970-03-01","endingBalance":"21.00"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "statementDate": "1970-03-01", "endingBalance": { "num": "2100", "denom": "100" }, "resumedPostponed": false, "startingBalance": { "num": "-800", "denom": "100" }, "tickedBalance": { "num": "2900", "denom": "100" }, "reconciledBalance": { "num": "2100", "denom": "100" }, "difference": { "num": "0", "denom": "100" }, "ticked": [ "d0000000000000000000000000000005" ], "splits": [ { "split": "d0000000000000000000000000000005", "state": "c", "ticked": true, "…": "…" }, { "state": "n", "ticked": false, "…": "…" }, { "state": "n", "ticked": false, "…": "…" } ], "…": "…" } } ``` **Effect:** `read`. ## Params Params of `reconcile.start`. Anything absent gets GnuCash's default. - `account` (AccountRef, required): The account to reconcile. - `statementDate` (Date or null): The statement date. Defaults to the last reconcile date plus the last interval, no later than today, or the postponed statement's date. - `endingBalance` (Amount or null): The statement's ending balance, raw sign (debits positive). Defaults to the postponed balance, else the account's balance at the end of the statement date. - `includeSubaccounts` (boolean or null): Reconcile the sub-accounts too. Defaults to the account's stored choice; refused when a sub-account holds another commodity. - `utcOffsetMinutes` (integer (int32) or null): A fixed offset from UTC in minutes to use instead of the server's local time zone, for GnuCash's local-time rules (the statement date ends at 23:59:59 local time). ## Result A reconciliation in progress: the statement, the splits to tick and the window's figures. Pass the statement fields and `ticked` back to the next call. - `account` (Guid, required): The account reconciled. - `statementDate` (Date, required): The statement date, local to the caller's offset. - `statementTime` (Timestamp, required): The statement date as an instant: the last second of the day, as GnuCash stores it. - `endingBalance` (Amount, required): The ending balance, raw sign. - `includeSubaccounts` (boolean, required): The sub-accounts are reconciled too. - `resumedPostponed` (boolean, required): The defaults came from a postponed reconciliation. - `lastReconcileDate` (Timestamp or null): When the account was last reconciled. - `startingBalance` (Amount, required): The reconciled balance before this statement. - `clearedBalance` (Amount, required): The cleared balance (every split not `n`). - `tickedBalance` (Amount, required): The sum of the ticked splits. - `reconciledBalance` (Amount, required): The starting balance plus the ticked splits. - `difference` (Amount, required): The ending balance minus the reconciled balance; `reconcile.finish` needs it to be zero. - `ticked` (array of Guid, required): The ticked splits. - `splits` (array of CandidateWire, required): Every split that can be ticked. ## Related - [reconcile.status](method/reconcile.status) - [reconcile.finish](method/reconcile.finish) - [reconcile.postpone](method/reconcile.postpone) --- *red-ale Manual, `method/reconcile.start`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # reconcile.status The splits, balances and difference of a reconciliation for a set of ticks, with marks and unmarks applied. Recomputes a reconciliation for a statement and a set of ticks, so you can see the `difference` change as you tick splits. Pass `ticked` (the splits ticked so far; leave it out to start from GnuCash's pre-ticked cleared splits) and `mark` or `unmark` to add or remove some. A tick that is not one of the listed splits is refused with `invalid`. Nothing is changed. ## Examples Ticking the 15.00 payment lowers the reconciled balance by 15.00, so the account is 15.00 off the statement: *Example: with a copy of the `reports/reconcile` example book open as `book.gnucash`.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"reconcile.status","params":{"account":"Root:Asset:Bank","statementDate":"1970-03-01","endingBalance":"21.00","mark":["d0000000000000000000000000000006"]}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "tickedBalance": { "num": "1400", "denom": "100" }, "reconciledBalance": { "num": "600", "denom": "100" }, "difference": { "num": "1500", "denom": "100" }, "…": "…" } } ``` **Effect:** `read`. ## Params Params of `reconcile.status`. - `account` (AccountRef, required): The account reconciled. - `statementDate` (Date, required): The statement date. - `endingBalance` (Amount, required): The statement's ending balance, raw sign. - `includeSubaccounts` (boolean or null): Reconcile the sub-accounts too. Defaults to the account's stored choice. - `utcOffsetMinutes` (integer (int32) or null): A fixed offset from UTC in minutes to use instead of the server's local time zone. - `ticked` (array of Guid or null): The ticked splits. Defaults to the ticks the window starts with: cleared splits posted by the statement date. - `mark` (array of Guid): Splits to tick. - `unmark` (array of Guid): Splits to untick. ## Result A reconciliation in progress: the statement, the splits to tick and the window's figures. Pass the statement fields and `ticked` back to the next call. - `account` (Guid, required): The account reconciled. - `statementDate` (Date, required): The statement date, local to the caller's offset. - `statementTime` (Timestamp, required): The statement date as an instant: the last second of the day, as GnuCash stores it. - `endingBalance` (Amount, required): The ending balance, raw sign. - `includeSubaccounts` (boolean, required): The sub-accounts are reconciled too. - `resumedPostponed` (boolean, required): The defaults came from a postponed reconciliation. - `lastReconcileDate` (Timestamp or null): When the account was last reconciled. - `startingBalance` (Amount, required): The reconciled balance before this statement. - `clearedBalance` (Amount, required): The cleared balance (every split not `n`). - `tickedBalance` (Amount, required): The sum of the ticked splits. - `reconciledBalance` (Amount, required): The starting balance plus the ticked splits. - `difference` (Amount, required): The ending balance minus the reconciled balance; `reconcile.finish` needs it to be zero. - `ticked` (array of Guid, required): The ticked splits. - `splits` (array of CandidateWire, required): Every split that can be ticked. ## Related - [reconcile.start](method/reconcile.start) - [reconcile.finish](method/reconcile.finish) --- *red-ale Manual, `method/reconcile.status`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # report.createStyleSheet Create a style sheet from a style sheet template in red-ale's configuration. Creates a style sheet from a style sheet template, with the options you give. It lives in red-ale's Configuration. A name already used is a `conflict`; an unknown template is `not-found`. Option values are checked: CSS text that could pull in anything outside the document (`@import`, `url(`, `csv` writes it: rows joined by `\n`, no newline after the last. ## Related - [report.run](method/report.run) - [report.export](method/report.export) --- *red-ale Manual, `method/report.exportCsv`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # report.importConfigurations Import GnuCash's saved report configurations from the text of its saved-reports-2.8 file, read as data, never run. Imports the saved report configurations from GnuCash's `saved-reports-2.8` file (or `saved-reports-2.4` if there is no 2.8 one), given as its `text`. The server never reads a path: the CLI's `--file` reads the file on your side. The text is data, never run, although it is Scheme. Each entry becomes a saved configuration with GnuCash's GUID and name, configuring the template it names, storing only the options that differ from the template's defaults. Entries go in file order, each on its own, so one that cannot be imported does not stop the others. `skipped` says why for each: `malformed`, `untranslated` (a report red-ale does not have), `exists` (importing twice adds nothing), `conflict` (the name is taken) or `invalid-option`. Options the template does not have are listed in `ignored`. With `dryRun` nothing is written. ## Examples *Example: with no book.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"report.importConfigurations","params":{"text":"(let ()\n (define (options-gen)\n (let\n (\n (options (gnc:report-template-new-options/report-guid \"d8b63264186b11e19038001558291366\" \"Net Worth Linechart\"))\n (new-embedded-report-ids '()) ;; only used with Multicolumn View Reports\n )\n; Section: General\n\n(let ((option (gnc:lookup-option options\n \"General\"\n \"Step Size\")))\n ((lambda (o) (if o (gnc:option-set-value o 'QuarterDelta))) option))\n\n\n options\n )\n )\n (gnc:define-report\n 'version 1\n 'name \"Quarterly net worth\"\n 'report-guid \"5e1f0a2b3c4d4e5f8a9b0c1d2e3f4a5b\"\n 'parent-type \"d8b63264186b11e19038001558291366\"\n 'options-generator options-gen\n 'menu-path (list gnc:menuname-custom)\n 'renderer (gnc:report-template-renderer/report-guid \"d8b63264186b11e19038001558291366\" \"Net Worth Linechart\")\n )\n)\n","dryRun":true}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "dryRun": true, "imported": [ { "line": 1, "configuration": { "guid": "5e1f0a2b3c4d4e5f8a9b0c1d2e3f4a5b", "name": "Quarterly net worth", "kind": "saved", "…": "…" }, "options": { "General": { "Step Size": "QuarterDelta" } }, "ignored": [] } ], "skipped": [] } } ``` **Effect:** `write`, on the Configuration only. ## Params Params of `report.importConfigurations` and `report.importStyleSheets`. - `text` (string, required): The file's text: GnuCash's `saved-reports-2.8` (else `saved-reports-2.4`), or `stylesheets-2.0`, from its user data directory. It is read as data and never run. - `dryRun` (boolean): Report what would be imported without writing the Configuration. ## Result The result of `report.importConfigurations`. - `dryRun` (boolean, required): True when nothing was written. - `imported` (array of ImportedConfiguration, required): The configurations imported (or that would be), in file order. - `skipped` (array of SkippedEntry, required): The entries skipped, in file order. ## Related - [report.importStyleSheets](method/report.importStyleSheets) - [report.saveConfiguration](method/report.saveConfiguration) --- *red-ale Manual, `method/report.importConfigurations`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # report.importStyleSheets Import GnuCash's style sheets from the text of its stylesheets-2.0 file, read as data, never run. Imports the style sheets from GnuCash's `stylesheets-2.0` file, given as its `text`; the server never reads a path and never runs the text. An entry that names a predefined style sheet (`Default`, `Easy`, …) holds the user's changes to it; any other name is a user style sheet. `skipped` says why an entry was left out: `malformed`, `untranslated` (a style sheet template red-ale does not have), `exists` (the Configuration already has an entry for that name, so edits made in red-ale are kept), `invalid-option` or `unchanged` (a predefined style sheet at its defaults). Image options are kept but not rendered. With `dryRun` nothing is written. ## Examples *Example: with no book.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"report.importStyleSheets","params":{"text":"(let ((template (gnc:html-style-sheet-template-find \"Footer\")))\n (if template\n (let ((options ((gnc:html-style-sheet-template-options-generator template))))\n\n; Section: Tables\n\n(let ((option (gnc:lookup-option options\n \"Tables\"\n \"Table border width\")))\n ((lambda (o) (if o (gnc:option-set-value o '2.0))) option))\n\n (gnc:restore-html-style-sheet \"Acme\" \"Footer\" options))))\n"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "dryRun": false, "imported": [ { "line": 1, "styleSheet": { "name": "Acme", "template": "Footer", "predefined": false, "…": "…" }, "…": "…" } ], "skipped": [] } } ``` **Effect:** `write`, on the Configuration only. ## Params Params of `report.importConfigurations` and `report.importStyleSheets`. - `text` (string, required): The file's text: GnuCash's `saved-reports-2.8` (else `saved-reports-2.4`), or `stylesheets-2.0`, from its user data directory. It is read as data and never run. - `dryRun` (boolean): Report what would be imported without writing the Configuration. ## Result The result of `report.importStyleSheets`. - `dryRun` (boolean, required): True when nothing was written. - `imported` (array of ImportedStyleSheet, required): The style sheets imported (or that would be), in file order. - `skipped` (array of SkippedEntry, required): The entries skipped, in file order. ## Related - [report.importConfigurations](method/report.importConfigurations) - [report.styleSheets](method/report.styleSheets) --- *red-ale Manual, `method/report.importStyleSheets`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # report.list Every report template and saved report configuration, and the user scripts that did not load. Lists every report template (GnuCash's, red-ale's translations of them, and your own scripts) and every saved report configuration, sorted by name, and the user scripts that failed to load (`problems`). Use it to find the name or GUID of a report to [run](method/report.run). It needs no book. A template's `menuPath` and `menuName` are GnuCash's menu fields; `exportTypes` says whether `report.exportCsv` works on it. ## Examples *Example: with no book.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"report.list","params":{}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "reports": [ { "guid": "3298541c236b494998b236dfad6ad752", "name": "Account Summary", "kind": "builtin", "script": "standard/account-summary.rhai", "…": "…" }, "…" ], "problems": [] } } ``` **Effect:** `read`. ## Params Params for methods that take none. Type: NoParams. ## Result The result of `report.list`. - `reports` (array of ReportInfo, required): Every template and saved configuration, sorted by name (bytewise), then GUID. - `problems` (array of LoadProblem, required): User scripts that did not load, so one bad file does not hide the others. ## Related - [report.options](method/report.options) - [report.run](method/report.run) --- *red-ale Manual, `method/report.list`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # report.options A report's options with their defaults and values, and the JSON Schema of its options param. Describes a report's options: each one's section, name, type, help text, default and current value, in GnuCash's order, and the JSON Schema of the `options` param of [report.run](method/report.run). Look here for the names and types before setting an option. A saved configuration shows its saved values. Defaults that depend on the book, such as the account list, are worked out from the open book, or from an empty one if none is open; with no book, accounts can only be given by GUID. ## Examples *Example: with no book.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"report.options","params":{"report":"Net Worth Linechart"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "report": { "name": "Net Worth Linechart", "kind": "builtin", "exportTypes": [ "csv" ], "…": "…" }, "options": [ { "section": "Accounts", "name": "Accounts", "type": "accountList", "…": "…" }, "…" ], "…": "…" } } ``` **Effect:** `read`. ## Params Params of `report.options`. - `report` (ReportRef, required): The report. ## Result The result of `report.options`. - `report` (ReportInfo, required): The report. - `options` (array of OptionInfo, required): Every option in GnuCash's order (sections by name, options by key), with its default and configured value. - `paramsSchema` (any, required): The JSON Schema (2020-12) of this report's `options` param. ## Related - [report.run](method/report.run) - [report.list](method/report.list) - [report.saveConfiguration](method/report.saveConfiguration) --- *red-ale Manual, `method/report.options`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # report.renameConfiguration Rename a saved report configuration. Renames a saved configuration. A name another saved configuration has is refused with `conflict`, as GnuCash's dialog refuses it. ## Examples *Example: with no book.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"report.saveConfiguration","params":{"name":"March balance sheet","report":"Balance Sheet"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": "…" } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"report.renameConfiguration","params":{"configuration":"March balance sheet","name":"Month-end balance sheet"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "name": "Month-end balance sheet", "kind": "saved", "…": "…" } } ``` **Effect:** `write`, on the Configuration only. ## Params Params of `report.renameConfiguration`. - `configuration` (ReportRef, required): The saved configuration, by GUID or name. - `name` (string, required): Its new name. ## Result A report template or saved report configuration, as `report.list` lists it. - `guid` (Guid, required): The template's GUID (GnuCash's, for a built-in report), or the saved configuration's. - `name` (string, required): The template's name, or the saved configuration's. - `kind` (ReportKind, required): `builtin`, `user` or `saved`. - `template` (Guid or null): For a saved configuration: the GUID of the template it configures. - `script` (string or null): The script defining the template: `standard/balance-sheet.rhai`, or `./` and a user script's path in the report directory. `null` for a saved configuration whose template is not loaded. - `menuPath` (array of string, required): GnuCash's menu path. Empty for a saved configuration, which GnuCash lists in its own dialog. - `menuName` (string or null): The menu entry when it differs from the name. - `menuTip` (string or null): The menu tip. - `inMenu` (boolean, required): Whether the template shows in menus; `false` for a saved configuration. - `exportTypes` (array of string, required): The exports offered besides HTML: `["csv"]` for the net and category charts (`report.exportCsv`), and for a saved configuration of one. - `readOnly` (boolean): `true` for a built-in saved configuration (v0.6), which cannot be changed, renamed or deleted, only copied with `report.saveConfiguration`; absent otherwise. ## Related - [report.saveConfiguration](method/report.saveConfiguration) - [report.deleteConfiguration](method/report.deleteConfiguration) --- *red-ale Manual, `method/report.renameConfiguration`. Licensed under the GNU Free Documentation License, version 1.1 or later, with no Invariant Sections: see [the notices](legal/notices) and [the licence](legal/gfdl).* --- # report.run Run a report on the open book: the report result, with exact figures. Runs a report on the open book and returns its result: tables, charts and text, with exact figures (every amount is a rational as well as a display string). Name the report by name or GUID, and change options with `options`, as `{"Section": {"Name": value}}`, only the ones you want; [report.options](method/report.options) lists them. It reads the book only: it works on a read-only book and never makes one dirty. "Today" and relative dates such as `end-this-month` follow the session's clock, or `now` if you give it. Numbers and dates are formatted in the Configuration's locale, or `locale`. A saved configuration is run by its name or GUID, and `options` are applied over its saved ones. For HTML use [report.export](method/report.export); each report has its own [Page](report/balance-sheet) with an example. A report that cannot show anything says so in a `warning` block instead of failing, such as `No accounts selected` or `No data`. Unknown options, options of the wrong type and unknown reports are errors; a name that matches a template and a saved configuration is a `conflict` that lists the matches. ## Examples *Example: with a copy of the `reports/test-data` example book open as `book.gnucash`, at 2024-03-15T12:00:00Z.* Request: ```json {"jsonrpc":"2.0","id":1,"method":"report.run","params":{"report":"Balance Sheet","options":{"General":{"Balance Sheet Date":{"absolute":"1978-12-31"}}}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 1, "result": { "title": " Balance Sheet 12/31/78", "report": { "name": "Balance Sheet", "…": "…" }, "sections": [ { "blocks": [ { "kind": "table", "rows": [ "…", "…", "…", "…", "…", "…", { "role": "total", "cells": [ { "text": "Total Assets", "…": "…" }, { "display": "$3,057.80", "…": "…" } ], "…": "…" }, "…" ], "…": "…" }, "…" ], "…": "…" }, "…" ], "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":2,"method":"report.run","params":{"report":"Transaction Report"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "title": "Transaction Report", "sections": [ { "blocks": [ { "kind": "warning", "title": "No accounts selected", "…": "…" }, "…" ], "…": "…" }, "…" ], "…": "…" } } ``` Request: ```json {"jsonrpc":"2.0","id":3,"method":"report.run","params":{"report":"Balance Sheet","options":{"General":{"Colour":"red"}}}} ``` Response: ```json { "jsonrpc": "2.0", "id": 3, "error": { "code": 3002, "message": "option General/Colour: unknown option", "data": { "section": "General", "name": "Colour", "reason": "unknown option", "help": "error/report-option" } } } ``` Request: ```json {"jsonrpc":"2.0","id":4,"method":"report.run","params":{"report":"Balance Shet"}} ``` Response: ```json { "jsonrpc": "2.0", "id": 4, "error": { "code": 2000, "message": "report Balance Shet not found", "data": { "kind": "report", "id": "Balance Shet", "help": "error/not-found" } } } ``` **Effect:** `read`. ## Params Params of `report.run`. - `report` (ReportRef, required): The report. - `options` (ReportOptions or null): Changes over the template's defaults, or over the saved configuration's values. - `now` (Timestamp or null): The time to run the report for; by default the session's clock. Relative dates and "today" follow it. - `locale` (string or null): The Locale to format numbers and dates in for this run: a supported POSIX locale name (`fr_FR`, `C`) or `environment`; by default the Configuration's `locale` setting. ## Result A finished report result, as `report.run` returns it. - `version` (string, required): The result's version: [`RESULT_VERSION`]. - `report` (ReportIdentity, required): The template and saved configuration that produced it. - `title` (string, required): The document title (`gnc:html-document-set-title!`): the HTML `