Update invoice
update_invoiceReplaces an existing invoice with the values given. Use it to edit a draft, to finalize a draft (isDraft=false), or to correct the recipient details, buyer reference, note or style of a finalized invoice. On a draft this is a full replacement, not a partial update: all line items and discounts are deleted and recreated from the input, the amounts are recalculated, and any field left out is reset to empty or to the sender-settings default. On a finalized invoice the invoice number, invoice date, currency, shipping, the invoice-level discounts, the number of line items and each line's quantity, unit, price, VAT rate and discount are locked: a call that changes any of them is rejected and nothing is saved. Recipient details, buyer reference, note, style, due date and line item titles and descriptions can still change. A finalized invoice keeps the amounts it was issued with: its totals and line amounts are never recalculated and its line items and discounts are never deleted or recreated. lineItems and discounts left out stay as stored; when they are sent, they are matched to the stored rows by position, and only a line's title and description and a discount's label are written. A field left out keeps its current value, and an empty string clears an optional text field (street, second address line, state, VAT ID, email, buyer reference, note); company name, postal code, city and country cannot be emptied. get_invoice returns the current values to send back. invoiceDate and dueDate are written in the date format stored on the invoice, the dateFormat field of get_invoice, which can differ from the sender's current format and is not changed by this tool. A date that cannot be read as day, month and year in that format is rejected. The check goes no further: a date written in another format with the same separator is read in the expected order (03/04/2026 is 3 April in DD/MM/YYYY and 4 March in MM/DD/YYYY), a day past the end of its month rolls into the next one (31.02.2026 becomes 3 March), and a two-digit year is read as 19xx (26 is 1926). Left out on a draft, they are not kept: they are reset to today and today plus the sender's payment terms. Left out on a finalized invoice, they stay as stored. Finalizing a draft spends credits. Finalizing uses one free invoice if any remain, otherwise it deducts the per-invoice price from the credit balance. It fails when the balance is too low, and the charge is not refunded. A finalized invoice cannot go back to draft. With isDraft left out the invoice keeps its current status: a draft stays a draft and a finalized invoice stays finalized. Editing a finalized invoice changes a document the recipient may already have, and the previous values are not kept. Line item prices take unitPrice (decimal, e.g. 110.00) or unitPriceCents (integer, e.g. 11000); VAT rates are basis points (1900 = 19%). Side effect: the recipient gets a customer record if none exists under that company name, created from the recipient details of the invoice, and the invoice is linked to it. An existing customer record is not changed. It does not email anyone.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Invoice ID to update | |
| dueDate | No | Due date in the date format stored on the invoice (dateFormat from get_invoice). Reset to today + the sender's payment terms if omitted on a draft; kept unchanged on a finalized invoice. | |
| isDraft | No | Save as draft (true) or final (false, charges credits if converting from draft). Left out, the invoice keeps its current status. | |
| currency | No | Currency code. Defaults to sender settings for drafts; kept unchanged on a finalized invoice if omitted. | |
| discounts | No | Invoice-level discounts. On a draft they replace the stored ones, and all are removed when this is left out. On a finalized invoice the stored ones stay untouched when this is left out; when sent, there must be as many as stored, in the same order, with the same type and value, and only the label may differ. | |
| lineItems | No | Line items. On a draft they replace the stored ones, and all are removed when this is left out. On a finalized invoice the stored ones stay untouched when this is left out; when sent, there must be as many as stored, in the same order, with the same quantity, unit, price, VAT rate and discount, and only title and description may differ. | |
| vatRateBps | No | VAT rate in basis points. Defaults to sender settings for drafts; kept unchanged on a finalized invoice if omitted. | |
| invoiceDate | No | Invoice date in the date format stored on the invoice (dateFormat from get_invoice). Reset to today if omitted on a draft; kept unchanged on a finalized invoice. | |
| invoiceNote | No | ||
| invoiceStyle | No | Invoice style. Defaults to sender settings for drafts; kept unchanged on a finalized invoice if omitted. | |
| invoiceNumber | No | Invoice number. Kept unchanged on a finalized invoice if omitted. | |
| recipientCity | No | ||
| shippingCents | No | Shipping cost in minor units. Defaults to 0 for drafts; kept unchanged on a finalized invoice if omitted. | |
| buyerReference | No | ||
| recipientEmail | No | ||
| recipientState | No | ||
| recipientVatId | No | ||
| recipientStreet | No | ||
| recipientCountry | No | ||
| recipientPostalCode | No | ||
| recipientCompanyName | No | ||
| recipientAddressLine2 | No |