Update invoice
well_update_invoiceUpdate an existing invoice in Well.
Call well_get_schema("invoices") to discover all available fields.
REQUIRED: invoice_id OPTIONAL (only pass fields you want changed):
reference_number, issue_date (ISO date), due_date (ISO date)
status (draft | issued | paid | canceled). "paid" is an "issued" request that also records the source's claim that the invoice was settled; it is never a lifecycle word of its own. Never set a draft to issued or paid here: finalize a draft with well_issue_invoice. A status change to issued or paid on a draft is refused.
terms, description
grand_total, items_total, tax_total (numbers)
local_currency (ISO 4217 three-letter code, e.g. "EUR", "USD")
document_type_code (UN/CEFACT 1001 code, e.g. "380")
billing_context (e.g. subscription, one_time, project, ...)
valid_until (YYYY-MM-DD, the last day a quote stays valid) and quote_outcome (pending, accepted, denied, invoiced or expired, the customer's answer): both only on a quote (document_type_code "310"); null clears either one. A quote moved to another type needs both cleared in the same call.
issuer_company_id / receiver_company_id (uuid to set, null to clear, omit to leave unchanged)
receiver_person_id (a private individual's person id from well_list_customers or well_create_person; uuid to set, null to clear). A receiver is a company or a person: setting one clears the other, and both in one call is refused.
Cannot change line items, payment_means, or document attachment via this tool.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| terms | No | Payment terms text; pass null to clear | |
| status | No | Invoice lifecycle status | |
| due_date | No | Payment due date (ISO 8601); pass null to clear | |
| tax_total | No | Total tax amount; pass null to clear | |
| invoice_id | Yes | The UUID of the invoice to update | |
| issue_date | No | Issue date (ISO 8601, e.g. 2026-04-27); pass null to clear | |
| description | No | Free-form description; pass null to clear | |
| grand_total | No | Total invoice amount including tax; pass null to clear | |
| items_total | No | Sum of line items before tax; pass null to clear | |
| valid_until | No | Last day the quote stays valid, YYYY-MM-DD (quotes only); pass null to clear | |
| workspace_id | No | Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which. | |
| quote_outcome | No | The customer's answer to a quote: pending, accepted, denied, invoiced or expired (quotes only); pass null to clear | |
| local_currency | No | ISO 4217 three-letter currency code (e.g. EUR, USD); pass null to clear | |
| payment_status | No | User-driven payment_status override — requires override_version (CAS) | |
| billing_context | No | Billing context / business model; pass null to clear | |
| conversation_id | No | The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation. | |
| idempotency_key | No | Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation. | |
| workspace_scope | No | Restrict this call to the family: the token's primary workspace plus the company workspaces under it that you are a member of. Unrelated authorized workspaces drop out of the read; row reads merge across the family, while a per-workspace figure still reports exactly one workspace. | |
| override_version | No | Required when payment_status is present — current override_version for CAS | |
| reference_number | No | Invoice reference number (e.g. INV-2026-001); pass null to clear | |
| issuer_company_id | No | Issuer company UUID. Omit = no change, null = clear, uuid = set. | |
| document_type_code | No | UN/CEFACT 1001 document type code (e.g. 380 for commercial invoice); pass null to clear | |
| receiver_person_id | No | Receiver person UUID, for a private individual. Omit = no change, null = clear, uuid = set. | |
| receiver_company_id | No | Receiver company UUID. Omit = no change, null = clear, uuid = set. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | ||
| lines | No | ||
| status | No | ||
| sources | No | The tools that hold a copy of the invoice, highest source precedence first. Empty when no tool holds it. | |
| success | Yes | ||
| currency | No | ||
| tax_total | No | ||
| invoice_id | No | ||
| issue_date | No | ||
| grand_total | No | ||
| items_total | No | ||
| source_count | No | How many tools hold the invoice; sources may list fewer. | |
| customer_name | No | ||
| design_layout | No | ||
| fx_conversion | No | ||
| customer_siren | No | The SIREN the invoice prints for its customer. Absent while the customer has none. | |
| missing_fields | No | On a draft, every part the person gives that it still lacks before it can be issued. The draft is complete only when this list is empty. | |
| card_line_count | No | ||
| conversation_id | No | The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation. | |
| newly_connected | No | Tools that connected to this workspace since the last result and that no session was told about yet, oldest first. Present only when at least one tool is new. The connected-line rule says when to tell an entry; when it does, one line per entry, in the person's language: "<name> is connected.". Never fold several entries into one sentence. Each entry comes back once, on one result only: never repeat its line later. | |
| reference_number | No | ||
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| conversation_id_source | No | Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened. | |
| next_invoice_number_state | No | Whether the workspace's next invoice number lets the issue go ahead. Well settles it when the invoice is issued: it is never named to the person and never makes the draft incomplete. |