Update Invoice

Edits an invoice. A draft can change anything, while a posted invoice can change its Invoice Number, dates, memo, custom fields (fieldData), and line memos, and must resend its line items and category unchanged; send the full document from Get Invoice (getFinancialsInvoice) with its headJournalId as If-Match. To correct a posted invoice’s amounts, void it with Void Invoice (voidFinancialsInvoice) and create a new one; to move it to another claim or payee, use Re-link Invoice (relinkFinancialsInvoice) or Change Invoice Payee (changeFinancialsInvoicePayee).

Replaces the invoice’s economic document — the invoice.updated action. The body still carries the FULL document (categoryId, dates, memo, fieldData, lineItems); links are excluded by schema (they change via re-link and payee change).

Invoice Number. invoiceNumber, the sender’s invoice number, may be changed on draft and posted invoices. Omit it to keep the current value, send null or a blank string to clear it, or send a string to set it. Number-only corrections are journaled without changing balances, payments, or approval. The Transaction ID (transactionId) never changes and is not part of the body.

The immutability law. Once an invoice is POSTED (a non-draft creation, or finalize for drafts), its line items — ids, types, amounts — and its category are FIXED: an update may change only invoiceNumber, incurredDate, dueDate, memo, fieldData (and per-line memos), and must echo the stored line-item set and categoryId verbatim. ANY line-item or category deviation is rejected with 422 LINE_ITEMS_IMMUTABLE, at any payment count — zero included. Corrections are void-and-recreate, payments removed first. A DRAFT edits freely until finalize — the document (line items and category included) replaces wholesale while drafting.

Policy invoices (422 POLICY_INVOICE_BATCH_ONLY). A policy-linked invoice permits an Invoice Number correction when every other document field is resent unchanged, including dates, memo, custom fields, and line items. Other document changes, dates and memo included, require replacing it through the atomic policy invoice batch: void it with its watermark (remove its payments first) and create its replacement in one plan.

Concurrency. Send the invoice’s current headJournalId as If-Match (from any read or write response). Stale → 409 IF_MATCH_CONFLICT with the current invoice in the body; missing/malformed → 400.

Idempotency. actionId is a client-minted uuid; an identical retry replays the original outcome (the watermark is not re-evaluated on replay); reuse with a different payload is 409 ACTION_ID_REUSED.

Other preconditions (422). Cited types must belong to the cited category (UNKNOWN_ID, reachable on draft edits); newly-introduced refs must be live (DEPRECATED_CONFIG); voided/deleted invoices reject updates (INVOICE_VOIDED / INVOICE_DELETED).

Required permission: the edit permission of the invoice’s current stage — invoice.edit-draft (status draft), invoice.edit-finalized (owed or no_charges) or invoice.edit-paid (partially_paid or paid). An approved invoice that requires approval (approved and approvalRequired both true) also requires invoice.approve, the permission that approves it. A key without them receives 403.