Skip to content

SPEC-001: VAT return, prepare and verify ​

Business intent ​

Give the owner an independent, explained VAT return for each company before the deadline, proven against what HMRC holds. Moves SM-3.

User story ​

When a VAT period is coming due, I want the return prepared from my Xero data, checked and explained, so I can file knowing the figures are right.

Scope ​

  • Connect Xero and HMRC for each company.
  • Sync VAT obligations from HMRC.
  • Derive the nine boxes from Xero line items under the standard accrual scheme or, since 2026-09-29, the cash accounting scheme (FEAW is on it: QD-16, issue #34), whichever Xero records: invoices, bills, credit notes, spend and receive money, and posted manual journals. No VAT lines are outside the return, as in Xero (ADR 0018).
  • Run the checks below and explain the result through MCP tools.
  • Send reminder emails ahead of the due date.

Out of scope ​

Filing (SPEC-002, not yet drafted). Flat rate and annual schemes: the derivation stops with "unsupported scheme". Amendments. Receipts.

Data model sketch ​

entity, entity_access, xero_connection, hmrc_connection, vat_obligation, vat_return_draft, alert_log, audit_event. Every table carries entity_id under a row-level security policy. Money is integer pence.

MCP tools sketch ​

ToolReturns
vat_obligationsOpen and recent periods with due dates, from the synced cache
vat_prepare_returnNine boxes, check results, included line count, rule ids and source links
vat_explain_boxThe lines and rule behind one box

No tool calls HMRC directly. No tool submits or approves.

Scenarios ​

S1: Back-test matches HMRC ​

Given a VAT period already filed for the company When the return is derived from Xero for that period Then each of the nine boxes equals the return held by HMRC

S2: Unknown tax type blocks the draft ​

Given a transaction line whose Xero tax type has no box mapping When the return is derived Then the draft is marked blocked and names that line

S3: Companies are isolated ​

Given a session authorised for FEAW When WealthTechPros VAT data is requested Then no rows are returned

S4: Xero token rotation survives a crash ​

Given Xero has issued a rotated refresh token And the process stops before the new token is saved When the next Xero call is made Then the call succeeds or the connection is marked for reconnect and an alert is sent

S5: Control account cross-check ​

Given a derived return for an open period When Box 5 differs from the VAT control account movement beyond tolerance Then the draft is marked blocked and shows both figures

S6: Reminder before the due date ​

Given an open VAT obligation When the due date is 30, 14, 7 or 3 days away Then one email per threshold is sent, and never twice

S8: Every source of VAT counts ​

Given a period with invoices, spend money coded 20% and a posted VAT correction journal When the return is derived Then each contributes to the boxes, with VAT-inclusive amounts turned into net for Boxes 6 and 7 And lines coded No VAT reach no box And the draft fails if any of them cannot be read from Xero

S9: Cash accounting counts VAT when money moves ​

Given a company Xero records as on the cash accounting scheme When the return is derived Then each invoice's and credit note's VAT counts on the date of each payment or refund, in proportion to how much it settles And spend and receive money and journals count on their own dates, as under accrual And the draft says it used the cash scheme

S10: A filed return is checked box by box ​

Given a VAT return already filed, with its filing date and nine figures as Xero or HMRC show them When it is checked with vat_verify_return Then each box shows the filed and derived figures and the difference in pence, with boxes 6 to 9 matched to the whole pound And it is derived twice: as at filing, leaving out documents Xero changed after the filing date, and as Xero stands now And every document changed since filing is listed with its effect, so any difference can be explained

S11: The draft says whether it is ready to file ​

Given a VAT draft that is not blocked When the return is derived Then each of the company's bank accounts is checked against Xero for the period, as in SPEC-003 And the draft is "ready to file" only when every account was checked and none has a line missing from Xero, a line to press OK, an ambiguous line, a Xero record with no bank line, or a possible VAT under- or over-claim And a Xero bank or card account that GetMy Books does not read counts as not checked if Xero has any record on it in the period, or if that cannot be read; with none, it is only noted (Product Owner, 2026-10-02) And otherwise it is "provisional", naming each account and what is outstanding, or why the account was not checked And the boxes are given either way, even when the bank accounts cannot be listed

Near matches (in Xero under another date or split), pending and unsettled bank lines do not stop a return being ready: they are not missing from Xero.

S12: A repayment return's Box 5 is checked as filed (approved 2026-10-06 by the Product Owner, pre-sale review) ​

Given a VAT return already filed where Box 4 is more than Box 1, so HMRC owes the company a repayment And Box 5 is given as the VAT100 shows it, a positive figure (or as a negative one) When it is checked with vat_verify_return Then Box 5 is compared as the net figure, without its sign, and matches when the amounts agree And Boxes 1 and 4 still show whether it is a payment or a repayment And the check and the tool both say so: "Box 5 is compared as the net figure; Boxes 1 and 4 show whether it's a payment or a repayment."

S7: Unsupported scheme stops ​

Given a company whose VAT scheme is neither standard accrual nor cash accounting, such as flat rate When the return is derived Then no draft is produced and the reason is "unsupported scheme"

S13: Document IDs are sent safely (approved 2026-10-06 by the Product Owner, pre-sale review) ​

Given an invoice, credit note or manual journal that is read on its own by its Xero ID When the read is made Then the ID is encoded in the request path, so an ID holding "/" or "?" cannot change which address is read And the IDs in a batched read of invoices (IDs=) are encoded too (review of PR #205)

S14: A period is two real dates, start before end (approved 2026-10-06 by the Product Owner, pre-sale review) ​

Given a period whose dates are not written YYYY-MM-DD (such as "2025-7-1"), are not real dates (such as "2026-13-45" or "2026-02-29"; "2028-02-29" is a leap day and is fine), or whose start is on or after its end When the return is derived, or any other tool is given that period (verify, bank check, outstanding, explain a line, receipts, entries, corrections, missing receipts, statement files) Then it is refused before anything is read from Xero, saying what is wrong with the period And no figure is given for it

S15: Credit notes set against invoices are looked for over six years, four at a time (2026-11-02, #297) ​

Given a company on the cash accounting scheme with years of credit notes in Xero When the return is derived Then only credit notes dated from six years before the period starts, up to the period's end, are listed as possible set-offs (six years is how long the records are kept) And each one that may hold an allocation is read on its own, at most four at once, with no pause between reads And the number of reads is unchanged, and the draft still fails if any of them cannot be read

S16: A document paid across two VAT periods adds up to its VAT across the two returns (2026-11-03, #297) ​

Given a company on the cash accounting scheme, and an invoice or credit note paid, refunded or set off in part in one period and the rest in a later one, whose VAT does not divide evenly (such as £20.01 paid in two halves) When the return for each period is derived Then the later period's share counts the payments and set-offs made on the document before that period, from the document as Xero already gives it, with no extra reads And each period's share is the document's share paid to the end of that period less its share paid before it, in whole pence And the shares in the two returns add up exactly to the document's net amount and VAT, never a penny over or under

Edge cases ​

  • Foreign currency documents: use the rate Xero stored on the document.
  • Items dated before the period and absent from earlier filed snapshots: included and flagged.
  • Draft documents in the period: warning, not blocking. Unreconciled bank lines: warning, not blocking (S11, issue #143).

Dependencies ​

Xero app registration; HMRC sandbox application; HMRC production read access for the back-test in S1.

Exit test ​

For the next real quarter of each company, the draft equals what is filed.

Validation ​

idnameruleassert
V1Control account to the pennyBox 5 equals the VAT control account movement for the period, with 0p tolerance (QD-03); any difference blocks the draft and is shown in penceS5