Appearance
0017: VAT coding errors corrected by journal, from chat, with guards
Context
The reconciliation check flags purchases whose VAT coding looks wrong: EE and Virgin Media coded No VAT (under-claims), insurance coded 20% (over-claims). On FEAW's Starling and Amex accounts, September 2026, that came to about £468 under-claimed and £95 over-claimed. The owner asked for the tool to fix them, with explicit permission, instead of doing it by hand.
Xero's API cannot change the tax rate on a reconciled bank transaction, and unreconciling in order to edit is a UI-only action. Editing the original would also move VAT between returns already filed. HMRC's route for small past errors is to correct them on the next return (VAT Notice 700/45): net errors up to £10,000, or up to 1% of Box 6 capped at £50,000, and above that form VAT652.
Decision
One MCP tool, vat_corrections_preview, posts one Xero manual journal per call. It needs the accounting.manualjournals scope.
- Only records that the under- or over-claim check, re-run in the same call over the same bank account and period, flags now can be corrected. The call supplies only the record id and the new tax rate.
- Under-claims may move to INPUT2 or REVERSECHARGES; over-claims to EXEMPTINPUT or NONE. The rate must be active in the entity's Xero.
- Each correction is two VAT-inclusive lines on the same account: minus the gross at the old rate, plus the gross at the new one. The journal nets to zero on the profit and loss account and moves only VAT. Account, gross and old rate come from Xero's record, never from the call.
- The journal is dated today (or the given date) so it falls in the open VAT period. The original transactions are never touched.
- A net change over £10,000 is refused with a pointer to form VAT652. The 1%-of-Box-6 limit is not used, because the check has no Box 6.
- The tool only previews: it stores the journal and returns a preview ID.
vat_corrections_confirmposts it, taking only that ID, once, within 15 minutes, by the person who made it, and only if the flags still give the same journal (audit M4, replacing the earlierpost: trueflag). - Each corrected record is logged in
ledger_writeasvat-correction:<recordId>, with the journal id. The existing unique index means a record is corrected once, and corrected records are no longer flagged. - No MCP tool submits or approves a filing (ADR 0005, CLAUDE.md rule 5).
Consequences
- The journal is visible in Xero under Manual Journals, with one line description per original purchase, and the owner's accountant can see what was changed and why.
- The VAT change uses the checks' estimate of one sixth of the gross. For a mixed receipt the owner should correct the original in Xero instead.
- As in ADR 0016, the journal is posted before the log row is written, so two calls racing could both post; the second log row would fail and be reported as not logged. Single-owner use makes this unlikely.
- SPEC-001's VAT derivation reads only invoices and credit notes. It must include bank transactions and manual journals before it can reproduce the return Xero builds.
Amendment, 2026-10-05: records the owner names (QD-32, SPEC-003 S37)
On 2026-10-05 the Product Owner recoded about 30 lines by hand in Xero (Anthropic to reverse charge, Amex fees to exempt, personal costs to No VAT) because none was flagged. QD-32 decided that the owner may name any reconciled record, with a reason, for the same preview and Approve. Decision 1 is widened; everything else above stands.
vat_corrections_previewalso takesnamedCorrections:recordId(a Xero GUID),toTaxTypeandreason(3 to 200 characters, the owner's words). The entity comes from the session only.- A named record must be a reconciled spend or receive money on the chosen bank account (Xero type SPEND or RECEIVE, so not an overpayment or prepayment), dated in the period and no more than 4 years before the journal (VAT Notice 700/45), with one line and an amount, not flagged now (a flagged one goes under
corrections) and not corrected before. Anything else is refused, naming the record. Invoice payments, batches, transfers and bills are refused: they carry no coding on the bank account. Ids are compared in lower case. The journal may not be dated after today. - The old rate and the new must both be ones SPEC-001's box mapping places, on the record's side of the return: for money out CAPEXINPUT2, EXEMPTINPUT, INPUT2, NONE, REVERSECHARGES or ZERORATEDINPUT; for money in EXEMPTOUTPUT, NONE, OUTPUT2 or ZERORATEDOUTPUT. The new rate must be active in Xero and, for a purchase, agree with the supplier's saved treatment (S17).
- The VAT Xero holds on the record must be what its rate gives on the gross (one sixth at 20%, else nothing), within a penny either way for Xero's rounding of a half penny. A mixed or edited receipt is refused, as the journal could not reverse it exactly.
- The VAT before and after, box by box, comes from code (
src/vat/vat-box-effect.ts, using SPEC-001's mapping): reverse charge adds the same 20% of the gross to Boxes 1 and 4; exempt and zero-rated move only the net box; No VAT is outside the return. Money received is reversed with a debit and re-posted with a credit. - Named and flagged corrections go in one journal. The £10,000 limit applies to the net change in the VAT payable (Box 5), counting every correction journal already posted for the entity and dated in the same VAT return's quarter (from the company's VAT quarters; with none known, the two months either side of the journal's month). The card shows "Already corrected for this VAT return". It lists named corrections apart from flagged ones, as "Corrections proposed for you to approve", with the "Reason given" (control and format characters taken out, shown as data on one line) and the change to Boxes 1, 4 and 5. The re-post line's description in Xero ends "Owner: <reason>".
- At Approve the plan is made again from Xero. If any record changed (its rate, gross, or whether it can still be corrected), nothing is posted and each changed record is named. A journal posts all of what was previewed or none of it. Posting is serialised per entity by a transaction-scoped Postgres advisory lock held from reading what is already corrected, through the Xero post, to the log rows: under it the records are checked as not corrected since the preview and the limit is checked again, so two approved previews cannot both post the same record, nor together pass the limit. This replaces, for VAT corrections, the race noted under Consequences.
- Each correction is logged in
ledger_writeasvat-correction:<recordId>with the journal's date in the entry; a named one also has the reason in the entry and in itsafter, so the once-per-record rule covers named records too.
Also fixed with this amendment: the under- and over-claim checks took Xero's line amount as gross, but it is net on a record stored Exclusive. A single-line record now uses its Total, and a line of a multi-line Exclusive record is grossed up by its own VAT from Xero, or else by its rate.