# 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`).

| `claimantRoute` | Scheme | VAT treatment |
|---|---|---|
| `self_build_431nb` | HMRC VAT431NB (new build) | Qualifying contractor **services** are zero-rated (0%). Self-purchased **materials** are standard-rated (20%) and reclaimable via the 431NB form after completion. |
| `self_build_431c` | HMRC VAT431C (qualifying conversion) | Contractor **services** are reduced-rated (5%) and fully reclaimable via the 431C form. |
| `self_build_standard` | No relief scheme | Standard renovation or extension — 20% VAT throughout. Nothing is reclaimable via a 431 form. |
| `self_build_reduced` | Reduced-rate-at-source only | Empty dwelling scheme (2+ years unoccupied) — 5% applied at source on contractor services. Not a refund scheme; no 431 form. |
| `developer` | Input-tax recovery | Developer recovers VAT via periodic VAT returns, not a 431 form. |
| `contractor` | Input-tax recovery | Contractor recovers input tax via periodic VAT returns. |

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 engine returns one of the following `claimRoute` values in every classification response. Machine clients should branch on this field — values are stable within `/api/v1/`.

| `claimRoute` | Meaning | Action for claimant |
|---|---|---|
| `hmrc_refund` | Reclaimable via HMRC 431NB or 431C form | Include in the 431 form claim |
| `full_hmrc_refund` | Fully reclaimable via HMRC form (100%) | Include in full in the 431 form |
| `zero_at_source` | VAT correctly charged at 0% — nothing to reclaim | No action needed; contractor billed correctly |
| `reduced_at_source` | VAT correctly charged at 5% — no refund | No action needed; reduced rate applied at source |
| `input_tax` | Recoverable via VAT return (developer/contractor) | Include on periodic VAT return |
| `supplier_correction` | Supplier charged wrong VAT rate | Request corrected invoice from supplier |
| `undercharged_vat` | Supplier undercharged VAT (liability risk) | Notify supplier; do not claim until corrected |
| `esm_zero_rate` | Energy-saving materials — zero-rated (ESM scheme) | Zero-rated install; confirm qualifying before deadline |
| `not_reclaimable` | VAT is blocked or not recoverable | Do not include in any claim |
| `input_tax_blocked` | Input tax explicitly blocked (e.g. private use) | Not recoverable; excluded from claim |
| `split_required` | Mixed supply — needs apportionment | Apportion the line item before claiming |
| `reverse_charge_cis` | Domestic reverse charge applies | Self-account for VAT under CIS DRC rules |
| `outside_scope` | Supply is outside the scope of UK VAT | No VAT action required |
| `pending` | Insufficient context to classify | Provide additional context (supplyType, identifierName) |
| `pending_complex_answer` | Complex-VAT question awaiting confirmation | Present the confirmation question to the user or agent |

## 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.

| `vatComplexTypeHint` | What the question determines |
|---|---|
| `esm_install` | Is this a qualifying energy-saving materials installation? (zero-rated if yes) |
| `supply_and_install` | Is this a supply-and-install or supply-only? (affects whether labour or materials rules apply) |
| `scaffolding` | Is scaffolding supplied independently or as part of qualifying construction? |
| `fitted_furniture` | Is furniture integral to the building (reclaimable) or freestanding (not)? |
| `soft_landscaping` | Landscaping — qualifying if part of approved planning consent |
| `garage_outbuilding` | Garage/outbuilding — qualifying only if integral to the dwelling |

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

## `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

```json
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:

```json
{
  "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.

| `supplyType` | Description |
|---|---|
| `labour` | Labour-only service (no materials supplied) |
| `subcontractor` | Subcontractor services (treated as services for 431NB/431C) |
| `materials` | Materials purchased directly by the self-builder |
| `supply_and_install` | Combined supply and installation (complex — may trigger vatComplexTypeHint) |
| `installation_service` | Installation service only (no materials component) |
| `professional_services` | Architect, surveyor, structural engineer fees |

## HMRC reference

All routing decisions reference **HMRC Notice 708 — Buildings and Construction**:
https://www.gov.uk/government/publications/vat-notice-708-buildings-and-construction