Skip to content

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_profile gains vat_registration_status (not_registered, registering, registered, or null when not known) and vat_registration_date (nullable; the effective date of registration, once known). company_profile_set takes both; company_profile_suggest proposes registered when Xero holds a VAT number, not_registered when it does not. A null status changes no behaviour (today's companies keep working).
  • No VAT while unregistered. When the status is not_registered or registering, bank_entries_preview, vat_corrections_preview and invoice_create_preview refuse any tax type whose return boxes are not "outside" (only NONE passes), saying the company is not VAT-registered; vat_prepare_return and vat_verify_return stop 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 (goods or services), still_held (goods only; the owner's word), a note, and when it was recorded. Under row-level security like every company table. Written by vat_remember_pre_registration (saves GetMy Books' own memory, not Xero; no card): the VAT shown is a pounds string parsed with parseAmountToPence, from the owner's words, never from a model's reading of a receipt. The three preview tools say, for a line coded NONE in 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 in src/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_held unknown 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 from vat_treatment`, deleted with the company.

MCP tools sketch ​

ToolRead or writeReturns
vat_remember_pre_registrationsaves own memoryThe line as recorded, in pence
vat_pre_registration_claimsreads own recordsEach 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 fourYearsBefore does 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 ​

idnameruleassert
V1Only No VAT while unregisteredA non-outside tax type is refused for not_registered or registering, at preview and again at ApproveS2, S12
V2No behaviour change for unknownA null status changes nothingS3
V3The owner's figureVAT shown is parsed from the owner's words, never a model's readingS4
V4HMRC rule by codeFour years for goods still held, six months for services, inclusive of the boundary dayS5, S6, S7, S8
V5Integer penceTotals are sums of penceS9
V6IsolationOne company's log onlyS11