Update invoice status

Transitions an invoice to a new status along the enforced lifecycle table (see the resource description). The public targets are sent (issue a draft), cancelled (drafts only), written_off (issued, unpaid), and voided (issued, unpaid, raised in error). Any transition not in the table is rejected; a missing invoice is reported as not found. Setting the current status again produces no lifecycle change.

Transitioning to sent stamps the sentAt timestamp on first issue only (never restamped) and posts the double-entry issue journal atomically with the status change, dated at the invoice's issue date, balanced, immutable, linked to the invoice in both directions. Every line must carry an accountId; issuing with unmapped lines is rejected and changes nothing.

Transitioning to written_off posts the bad-debt journal at the outstanding amount (Bad Debts debited, Trade Debtors credited). VAT bad-debt relief remains a VAT-return-level claim per HMRC Notice 700/18.

Transitioning to voided is for an invoice raised in error that should never have existed (issued, nothing paid). It reverses the issue journal in full, so the ledger nets to zero. It does NOT adjust the VAT return: void is scoped to error correction whose VAT has not been relied upon in a filed return. To reverse the VAT of an invoice whose VAT has been filed, issue a credit note, which is the HMRC instrument for an in-period compensating adjustment. When you void an invoice that carried VAT, the response data includes an advisory string restating this, so a clean ledger is not mistaken for a corrected VAT return.

For payment-driven transitions, use the Record Payment endpoint instead; it sets partial or paid automatically from the cumulative amount; those statuses cannot be set here.