Appearance
SPEC-020: Pre-registration VAT
Business intent
WEALTH TECH PROFESSIONALS LIMITED is about to register for VAT. Until it does, every line in its books must carry no VAT, yet the VAT shown on its receipts is not lost: HMRC lets a newly registered business reclaim VAT on goods bought in the four years before registration and still held, and on services bought in the six months before, on its first return (VAT Notice 700, section 11). Today GetMy Books does not know whether a company is registered, does not stop a 20% tax type being coded for one that is not, and keeps no record of the VAT a receipt showed when the line was coded No VAT. Protects SM-3.
User story
When my company is not yet VAT-registered, I want GetMy Books to keep every line at No VAT and to note the VAT each receipt shows, so that when I register I can list what the first return may reclaim, with the rule and the source behind each line.
Scope
- Profile (SPEC-015, ADR 0039).
entity_profilegainsvat_registration_status(not_registered,registering,registered, or null when not known) andvat_registration_date(nullable; the effective date of registration, once known).company_profile_settakes both;company_profile_suggestproposesregisteredwhen Xero holds a VAT number,not_registeredwhen it does not. A null status changes no behaviour (today's companies keep working). - No VAT while unregistered. When the status is
not_registeredorregistering,bank_entries_preview,vat_corrections_previewandinvoice_create_previewrefuse any tax type whose return boxes are not "outside" (onlyNONEpasses), saying the company is not VAT-registered;vat_prepare_returnandvat_verify_returnstop with the same message. - The log. A table
pre_registration_vat, one row per line the owner records: a reference to the Xero record or bank line, the supplier, the date, gross pence, VAT shown pence,kind(goodsorservices),still_held(goods only; the owner's word), a note, and when it was recorded. Under row-level security like every company table. Written byvat_remember_pre_registration(saves GetMy Books' own memory, not Xero; no card): the VAT shown is a pounds string parsed withparseAmountToPence, from the owner's words, never from a model's reading of a receipt. The three preview tools say, for a line codedNONEin an unregistered company, that the VAT shown on its receipt can be recorded with that tool. - The list.
vat_pre_registration_claims(read-only) runs the pure rule insrc/vat/pre-registration.ts: given the registration date and the recorded lines, each line is reclaimable or not with the reason and the HMRC source URL; goods within four years before the registration date and still held; services within six months before; a line dated on or after the registration date is not pre-registration ("claim it on the return for its period");still_heldunknown fails closed (not reclaimable until the owner says). Totals are sums of integer pence. Without a registration date the tool lists the lines and says the date is needed. - A received receipt (SPEC-021) for an unregistered company proposes a log entry instead of a VAT code.
Out of scope
- Registering for VAT, or filing the first return (ADR 0036, not-doing).
- Judging whether a document is a valid VAT invoice.
- Capital goods scheme, partial exemption, the flat rate scheme.
- Goods bought before registration and sold before it (not reclaimable; the owner answers
still_held). - Writing the reclaim into Xero: the first return's late claims are entered by the owner or their accountant in Xero.
Data model sketch
entity_profile + vat_registration_status text null check in ('not_registered','registering','registered'), vat_registration_date date null (migration, expand only).
`pre_registration_vat (id uuid pk, entity_id uuid not null references entity on delete cascade, record_kind text not null check in ('spend','bill','bank_line','other'), record_key text not null, supplier text not null, line_date date not null, gross_pence integer not null check
= 0, vat_shown_pence integer not null check >= 0, kind text not null check in ('goods','services'), still_held boolean null, note text null, created_at, updated_at; unique (entity_id, record_kind, record_key))
, with an RLS policy copied fromvat_treatment`, deleted with the company.
MCP tools sketch
| Tool | Read or write | Returns |
|---|---|---|
vat_remember_pre_registration | saves own memory | The line as recorded, in pence |
vat_pre_registration_claims | reads own records | Each recorded line, reclaimable or not with the reason and source; the total that may be reclaimed |
Scenarios
S1: The profile says whether the company is registered
Given WEALTH TECH PROFESSIONALS LIMITED with no VAT number in Xero When company_profile_suggest runs Then it suggests not_registered and asks for the registration date when known When company_profile_set saves registering Then the profile holds it and the reply shows it
S2: No VAT is accepted while unregistered
Given a company whose status is registering When bank_entries_preview or invoice_create_preview is given a line with INPUT2 Then it is refused before Xero is written, saying the company is not VAT-registered and only No VAT (NONE) is accepted And a line with NONE is accepted as before
S3: A company with no status is unchanged
Given a company whose status is null When any VAT tool runs Then it behaves exactly as before this spec
S4: Recording a line
Given a NONE-coded bill of £372.20 from British Airways dated 2026-10-14 whose receipt shows no VAT, and a NONE-coded spend of £120.00 from Dell dated 2026-09-01 whose receipt shows £20.00 VAT When vat_remember_pre_registration records the Dell line as goods, still held, VAT shown "20.00" Then the row holds 12000 gross pence and 2000 VAT pence, kind goods, still held true And "20.005" or "twenty" is refused as not pounds and pence
S5: Goods within four years and still held are reclaimable
Given a registration date of 2027-01-01 and goods dated 2023-01-02 still held When vat_pre_registration_claims runs Then the line is reclaimable, with the reason "goods bought within four years before registration and still held" and the HMRC source And goods dated 2023-01-01 (four years to the day) are reclaimable, and 2022-12-31 are not
S6: Goods not still held are not reclaimable
Given goods with still_held false or unknown When the list runs Then the line is not reclaimable and the reason says why (sold or used up; or still held not confirmed)
S7: Services within six months are reclaimable
Given a registration date of 2027-01-01 and services dated 2026-07-01 When the list runs Then the line is reclaimable; services dated 2026-06-30 are not And a registration date of 2027-08-31 with services dated 2027-02-28 is reclaimable (month ends clamp)
S8: A line on or after the registration date is not pre-registration
Given a line dated on the registration date When the list runs Then it is marked "claim it on the return for its period", not reclaimable here
S9: Totals are integer pence from the reclaimable lines
Given three recorded lines of which two are reclaimable with 2000 and 1500 VAT pence When the list runs Then the total is 3500 pence, and a line with 0 VAT shown adds nothing
S10: Without a registration date the list still helps
Given lines recorded and no registration date in the profile When the list runs Then every line is listed with "needs the registration date" and the total is not shown
S11: Companies are isolated
Given a session with access to FEAW only When a WealthTechPros line is recorded or listed Then nothing is written or returned
S12: The refusal is checked again at Approve (#338, 2026-11-03)
Given a company whose status is null, and a card previewing a bank entry or a bill coded INPUT2, or a VAT correction to EXEMPTINPUT When the profile is saved as registering (or not_registered) and the owner then presses Approve on that card Then nothing is written to Xero, and the card says the company is not VAT-registered and only No VAT (NONE) is accepted, naming the tax types not accepted, as S2 does at preview And a card whose lines are all No VAT is written as before
Edge cases
- A credit (negative gross) is refused: record the net position in one line.
- A registration date in the future: allowed for
registering; the list treats lines before it as pre-registration. - Four years from 29 February: clamped to 28 February as
fourYearsBeforedoes today.
Dependencies
- SPEC-015 (profile), ADR 0039; SPEC-003 S73 and SPEC-019 S6 (where the refusal hooks in); ADR 0018 (NONE outside the return); ADR 0025 (pence).
- QD-48 reopens QD-17(a)'s "nothing is built for its VAT until it registers" for the new company.
Exit test
Rob sets WEALTH TECH PROFESSIONALS LIMITED's profile to registering, records the VAT shown on three real receipts, asks for the list, and the total equals the sum he works out by hand from those receipts; a 20% line on a new bill is refused.
Validation
| id | name | rule | assert |
|---|---|---|---|
| V1 | Only No VAT while unregistered | A non-outside tax type is refused for not_registered or registering, at preview and again at Approve | S2, S12 |
| V2 | No behaviour change for unknown | A null status changes nothing | S3 |
| V3 | The owner's figure | VAT shown is parsed from the owner's words, never a model's reading | S4 |
| V4 | HMRC rule by code | Four years for goods still held, six months for services, inclusive of the boundary day | S5, S6, S7, S8 |
| V5 | Integer pence | Totals are sums of pence | S9 |
| V6 | Isolation | One company's log only | S11 |