Save document
save_documentCreate or update a WHOLE document and its header (contact, dates, type, parent); to change lines on an existing document without resending it use update_document_item, and to add one line use add_document_line. Works for documents of ANY kind — all eight document types are supported here, not just invoices: invoice, quote, recurring, debit_note, credit_note, purchase_order, bill, grn (the type enum below documents what each one is for). Credit notes and debit notes are raised through this same tool — pass the matching type and, where it relates to an existing document, its id as parent. For one document, send its fields inline (pass an id to update, omit + include type to create). To create/update many at once, send an items array — 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 and must include type. This manages the document as a whole; to edit individual line items on an existing document use update_document_item (or update_document_items_bulk).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Document id. Present → update that document; omit → create a new one (must include type). | |
| date | No | Document date (ISO 8601). | |
| name | No | Display name / title of the document. | |
| sent | No | Whether the document has been sent to the recipient. | |
| type | No | The kind of document. One of: invoice — Bill a customer for goods or services. Money in.; quote — A pre-sale estimate for a customer; becomes money in once accepted.; recurring — An invoice that repeats on a schedule. Money in.; debit_note — Reduce what you owe a supplier (offsets a bill). Money in.; credit_note — Refund or reduce a customer's invoice. Money out.; purchase_order — Order goods or services from a supplier. Money out.; bill — A supplier's bill that you owe. Money out.; grn — Record stock received against a purchase order. Money out.. | |
| items | No | Vector of document objects to create/update in one all-or-nothing batch. Preferred over repeated calls. Each item with an id updates; each without creates and must include type. | |
| notes | No | Free-text notes. | |
| client | No | Client id, or an exact client name to resolve (see list_clients). | |
| locked | No | Whether the document is locked against further edits. | |
| number | No | Document number; auto-generated if omitted. | |
| parent | No | Id of the parent document this one derives from (e.g. the invoice a credit note relates to). | |
| contact | No | Contact id, or an exact client/supplier name to resolve (client for money-in document types, supplier for money-out; see list_clients / list_suppliers). | |
| duedate | No | Payment due date (ISO 8601). | |
| message | No | Message shown to the recipient on the document. | |
| settled | No | Whether the document has been fully settled/paid. | |
| showvat | No | Whether to display the VAT/sales-tax line on the document. | |
| accepted | No | Whether the recipient has accepted the document (e.g. a quote). | |
| currency | No | ISO 4217 currency code (e.g. "ZAR", "USD"). Defaults to the business currency. | |
| shipping | No | Shipping amount added to the document total. | |
| showbank | No | Whether to display the business's banking details on the document. Defaults to true on create; only shown to recipients on money-in documents (invoices, quotes). | |
| supplier | No | Supplier id, or an exact supplier name to resolve (see list_suppliers). | |
| accountid | No | Bank/ledger account id the payment moved through (see list_accounts). | |
| description | No | Free-text description of the document. | |
| showdeposit | No | Whether to display the deposit line on the document. | |
| accepteddate | No | Date the document was accepted (ISO 8601). | |
| paymentnotes | No | Free-text payment instructions shown on the document. | |
| showdiscount | No | Whether to display the discount line on the document. | |
| showshipping | No | Whether to display the shipping line on the document. | |
| baseaccountid | No | Base/control account id override; rarely needed — defaults from the category. | |
| depositamount | No | Explicit deposit amount; used instead of the percentage when deposituseamount is true. | |
| invoicebankid | No | PROD-2443. :bankaccount/id of one of the business's own bank accounts to show on this document instead of the default invoice bank. "$delete" clears it back to the default; null or omitted leaves it unchanged. An id the business does not own is refused. | |
| accountpayment | No | Amount paid against the document at save time. | |
| depositpercent | No | Deposit as a percentage of the total. | |
| discountamount | No | Explicit discount amount; used instead of the percentage when discountuseamount is true. | |
| discountpercent | No | Discount as a percentage of the subtotal. | |
| showpaymentlink | No | Whether to include an online payment link on the document. | |
| deposituseamount | No | When true, use depositamount instead of the percentage. | |
| discountuseamount | No | When true, use discountamount instead of the percentage. |