VAT Routing Guide

This guide explains the claimantRoute vocabulary used by the VATBuild API, what each route means for VAT treatment, and how classification outcomes map to actions.

Claimant routes

The claimantRoute field tells the engine which UK VAT scheme applies to a project. It is required in POST /api/v1/check-line-item (context.claimantRoute) and POST /api/v1/projects (claimantRoute).

|---|---|---|

The full route configuration (labels, checklist keys, allowed outcome values) is available from the public reference endpoint:

GET /api/v1/reference/routes

Classification outcomes (claimRoute)

The classification engine (check_line_item, route_line_item) returns one of the following ten claimRoute values. Machine clients should branch on this field — values are stable within /api/v1/.

|---|---|---|

Stored-only routes

The following five values are assigned by the scope/work-package pipeline and are never returned by check_line_item or route_line_item. They may appear on items retrieved via list_line_items.

|---|---|

VAT treatment by route

self_build_431nb — New Build

Qualifying services (labour, subcontractor work, supply-and-install):

• Correct rate: 0%
• If charged 20%: claimRoute = "supplier_correction" — request a corrected invoice
• If charged 0%: claimRoute = "zero_at_source" — no action

Self-purchased materials (materials, professional services):

• Correct rate: 20%
• claimRoute = "hmrc_refund" — include in the VAT431NB form after practical completion

self_build_431c — Qualifying Conversion

Qualifying services:

• Correct rate: 5% (this is correct — do not flag 5% as an error for 431C)
• If charged 5%: claimRoute = "hmrc_refund" — fully reclaimable via VAT431C
• If charged 20%: claimRoute = "supplier_correction" — request corrected invoice at 5%
• If charged 0%: claimRoute = "supplier_correction" — undercharge; 5% is correct

Materials bought directly (not via contractor):

• claimRoute = "hmrc_refund" at 20%

self_build_standard — Standard Renovation

No relief scheme applies. VAT at 20% is the correct rate throughout. claimRoute = "not_reclaimable" for services and materials (there is no 431 form claim available).

self_build_reduced — Reduced Rate at Source

5% is applied at source by the contractor. There is no refund — this is claimRoute = "reduced_at_source". Nothing to reclaim.

developer / contractor — Input Tax Recovery

VAT is recovered via the developer's or contractor's periodic VAT return, not a 431 form. Reclaimable items return claimRoute = "input_tax". Blocked items (private use, entertainment) return claimRoute = "input_tax_blocked".

Complex-VAT types

Some line items require additional context before they can be definitively classified. These are flagged with a vatComplexTypeHint and return claimRoute = "pending_complex_answer" until a confirmation answer is provided.

|---|---|

Provide confirmedAnswer: true or confirmedAnswer: false (or a three-way string answer for supply_and_install) to resolve the outcome.

HMRC-excluded categories

Some categories are permanently blocked from reclaim under any route — no confirmation question is asked and no vatComplexTypeHint is required. The classifier detects these from the line text alone and returns claimRoute = "not_reclaimable" immediately with a specific rule.explanation citing the HMRC basis.

|---|---|---|

When a blocked item appears on the same line as qualifying works, the entire combined line is blocked. The rule.explanation in the response will instruct the supplier to reissue separate lines. See mcp-tool-reference.md for the full per-category details and firedRuleId values.

firedRuleId — which rule fired?

Every classification response includes a firedRuleId string (e.g. rule_4a7f3c8e2b916d05). This is a stable opaque token — the same rule always returns the same value across requests. The rule.label, rule.noticeRef, and rule.explanation fields translate this into human-readable form suitable for displaying to end users or auditors.

Compare firedRuleId for equality against a previously-observed token when you need to detect a specific outcome programmatically. Do not parse, pattern-match, or branch on the token's internal structure — it is intentionally opaque and the format may change between major API versions.

Example: classifying a line item

POST /api/v1/check-line-item

{
  "context": {
    "claimantRoute": "self_build_431c",
    "buildingType": "barn conversion",
    "newDwelling": "yes"
  },
  "item": {
    "lineText": "Structural steelwork",
    "netAmount": "12000.00",
    "vatCharged": "600.00",
    "supplyType": "subcontractor",
    "identifierName": "Structural works"
  }
}

Response:

{
  "ok": true,
  "data": {
    "outcome": {
      "claimRoute": "hmrc_refund",
      ...
    },
    "reclaimAmount": "600.00",
    "firedRuleId": "rule_9c2e5a1f7b843d0e",
    "rule": {
      "label": "431C conversion — correct 5% service charge",
      "noticeRef": "Notice 708 s3.3",
      "explanation": "Contractor services on a qualifying 431C conversion are correctly charged at 5% and are fully reclaimable via the VAT431C scheme."
    }
  }
}

The 5% charge (£600 on £12,000 net) is correct for a 431C conversion. Include the £600 in the VAT431C claim.

Supply types

The supplyType field tells the engine the nature of the supply. Providing it significantly improves classification accuracy.

|---|---|

Qualifying fitted furniture

*HMRC Notice 708 §13.5*

Two types of fitted furniture may qualify for zero/reduced-rate relief as incorporated building materials:

Fitted kitchens

A fitted kitchen qualifies when it is both supplied and installed by the same contractor (or subcontractor) carrying out the construction. Supply-only kitchen units — purchased separately without installation by the same party — are standard-rated at 20% and are not reclaimable.

Basic fitted wardrobes

A basic fitted wardrobe qualifies as an incorporated building material when it consists only of:

• A wall-to-wall unit, or a unit that fits entirely into a recess
• A hanging rail or shelf for hanging clothes
• Shelves

A basic wardrobe does not include: drawers, pull-out trays, shoe racks, mirrors, or decorative panelling. A wardrobe with any of these features is furniture under HMRC rules — not a building material — regardless of who installs it.

The same-contractor installation requirement that applies to fitted kitchens does not apply to basic wardrobes. A basic wardrobe qualifies on its structural description alone.

What does not qualify

• Free-standing wardrobes, dressers, or other bedroom furniture
• Modular wardrobe systems with carcasses, drawer packs, or internal fittings
• Bathroom vanity units and fitted bathroom cabinets (separate product category)
• Supply-only kitchen units (no same-contractor installation)
• Kitchen units where the units and installation are separately invoiced by different parties

Agent guidance

When classifying a fitted_furniture item, ask the user:

> *"Is this either (a) a fitted kitchen that was both supplied and installed by the same contractor, or (b) a basic fitted wardrobe consisting only of a wall-to-wall unit with a hanging rail or shelf for clothes and shelves — with no drawers, shoe racks, or decorative panelling?"*

Answer confirmedAnswer: true for either qualifying path. Answer confirmedAnswer: false only when neither path applies. Do not assume "bedroom furniture" means false — a basic wardrobe satisfying the structural conditions above is true.

HMRC reference

All routing decisions reference HMRC Notice 708 — Buildings and Construction:

https://www.gov.uk/government/publications/vat-notice-708-buildings-and-construction