Save expense
save_expenseCreate or update expense(s). For one expense, send its fields inline (pass an id to update, omit to create). To create/update many at once, send an items array — this is preferred over repeated calls: the whole batch is one all-or-nothing transaction with a single ledger recompute. Each item with an id updates; each without creates. To pay a bill / purchase order / GRN, set accountid to that document's id. Use update_expenses_bulk when you only need to recategorise/relink existing expenses, or create_income_expenses_bulk to add income and expenses together in one transaction.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ai | No | Internal: set when the expense was produced by AI enrichment. | |
| id | No | Expense id. Present → update that expense; omit → create a new one. | |
| date | No | Expense date (ISO 8601). | |
| name | No | Display name / description of the expense. | |
| paid | No | Whether this expense has been paid. | |
| alert | No | Alert/reminder note to surface on this expense. | |
| items | No | Vector of expense objects to create/update in one all-or-nothing batch. Preferred over repeated calls. Each item with an id updates; each without creates. | |
| notes | No | Free-text notes. | |
| split | No | Whether this expense is one line of a split transaction. | |
| total | No | Total amount including quantity; overrides amount×quantity if set. | |
| amount | No | Unit amount before quantity/tax, in the record's currency. | |
| method | No | Payment method as free text (e.g. "cash", "card", "eft") — no fixed set. | |
| unlink | No | Pass the id of a currently-linked transaction/document to detach it. | |
| groupid | No | Group id linking split lines of one real-world transaction together. | |
| taglist | No | Tag ids to set on this expense (replaces the existing set). | |
| currency | No | ISO 4217 currency code (e.g. "ZAR", "USD"). Defaults to the business currency. | |
| paiddate | No | Date payment was made (ISO 8601). | |
| quantity | No | Number of units. | |
| salestax | No | Whether sales tax (VAT) applies. May also be an array of salestax refs. | |
| supplier | No | Supplier id, or an exact supplier name to resolve (see list_suppliers). | |
| accountid | No | Chart-of-accounts account id (or an exact account name to resolve) used to categorise this expense (see list_accounts). ALSO how a payment is recorded against a purchase document: set this to the bill / purchase order / GRN document id (cont-…) and the expense counts toward that document's paid amount, inheriting the document's accounting category. This is how a money-out document is settled via a pre-existing expense. To record a fresh payment against a bill / purchase order / GRN, prefer record_document_payment — it now handles both directions, minting the accountid-linked expense for you from the payment details. | |
| exchangerate | No | Manual FX rate to the business base currency; omit to use the stored/auto rate. | |
| showquantity | No | Whether to display the quantity column on the document. | |
| bankaccountid | No | Bank account id the money moved through (see list_accounts). | |
| baseaccountid | No | Base/control account id override; rarely needed — defaults from the category. | |
| transactionid | No | Bank transaction id to reconcile this expense against. | |
| salestaxamount | No | Explicit sales tax amount; used instead of the percentage when salestaxuseamount is true. | |
| salestaxpercent | No | Sales tax rate as a percentage (e.g. 15 for 15%). | |
| salestaxuseamount | No | When true, use salestaxamount as the tax figure instead of computing from the percentage. |