Appearance
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
| Tool | Returns |
|---|---|
vat_obligations | Open and recent periods with due dates, from the synced cache |
vat_prepare_return | Nine boxes, check results, included line count, rule ids and source links |
vat_explain_box | The 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
| id | name | rule | assert |
|---|---|---|---|
| V1 | Control account to the penny | Box 5 equals the VAT control account movement for the period, with 0p tolerance (QD-03); any difference blocks the draft and is shown in pence | S5 |