{"openapi":"3.1.0","info":{"title":"UK VAT Flat Rate Calculator API","version":"0.1.0","description":"UK VAT Flat Rate Calculator works out what a small business would pay under the HMRC VAT Flat Rate Scheme and how that compares with standard VAT accounting. list_frs_categories and lookup_frs_rate return the flat rate percentage of the GOV.UK table for a trade category, choosing the dated row for catering, hotel and pub businesses (whose rates changed on 15 July 2020, 1 October 2021 and 1 April...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://uk-vat-frs-calc.connectorbay.com/mcp.\n\nDisclaimer: General information only, not legal, tax, accounting or payment advice. UK VAT Flat Rate Calculator is an independent tool: it is not affiliated with, endorsed by or operated by any government body, central bank, standards body or scheme operator. Rates, thresholds and rules change; check the cited official source and confirm with a qualified professional before you rely on a result.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/uk-vat-frs-calc/docs"},"termsOfService":"https://connectorbay.com/uk-vat-frs-calc/terms"},"servers":[{"url":"https://uk-vat-frs-calc.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/uk-vat-frs-calc/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_frs_categories":{"post":{"operationId":"list_frs_categories","summary":"List the Flat Rate Scheme trade categories of the GOV.UK table with the percentage in force on a date, optionally filter","description":"List the Flat Rate Scheme trade categories of the GOV.UK table with the percentage in force on a date, optionally filtered by a search word. Use for \"Which Flat Rate Scheme category and percentage fits a consultancy business?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Optional word or words that must all appear in the category name, for example consult or retailing.","title":"Search"},"on_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date the percentage applies to, YYYY-MM-DD. Defaults to today (UTC).","title":"On Date"}},"title":"list_frs_categoriesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/lookup_frs_rate":{"post":{"operationId":"lookup_frs_rate","summary":"Return the flat rate percentage of one trade category on a date, with the 1 percent first-year discount when a VAT regis","description":"Return the flat rate percentage of one trade category on a date, with the 1 percent first-year discount when a VAT registration date is given. Use for \"What is the flat rate for management consultancy and does the first-year discount apply if I registered in March 2026?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"description":"Category name or id from list_frs_categories; a unique part of the name also works (for example 'management consultancy').","title":"Category","type":"string"},"on_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date the percentage applies to, YYYY-MM-DD. Defaults to today (UTC).","title":"On Date"},"vat_registration_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date the business became VAT-registered, YYYY-MM-DD; needed for the 1 percent first-year discount.","title":"Vat Registration Date"}},"required":["category"],"title":"lookup_frs_rateArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/compute_frs_payment":{"post":{"operationId":"compute_frs_payment","summary":"Apply the flat rate percentage to VAT-inclusive turnover and return the VAT to pay for the period. Use for \"My consultan","description":"Apply the flat rate percentage to VAT-inclusive turnover and return the VAT to pay for the period. Use for \"My consultancy had GBP 24,000 of VAT-inclusive turnover this quarter: how much VAT do I pay on the Flat Rate Scheme?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"vat_inclusive_turnover":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}],"description":"GBP amount as a plain decimal string such as 1234.50 (digits and one '.'; no commas or symbols).","title":"Vat Inclusive Turnover"},"category":{"description":"Category name or id from list_frs_categories; a unique part of the name also works (for example 'management consultancy').","title":"Category","type":"string"},"on_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date the percentage applies to, YYYY-MM-DD. Defaults to today (UTC).","title":"On Date"},"vat_registration_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date the business became VAT-registered, YYYY-MM-DD; needed for the 1 percent first-year discount.","title":"Vat Registration Date"},"limited_cost_trader":{"default":false,"description":"True to use the 16.5 percent limited cost rate instead of the category percentage (decide it with limited_cost_trader_test). Default false.","title":"Limited Cost Trader","type":"boolean"}},"required":["vat_inclusive_turnover","category"],"title":"compute_frs_paymentArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/limited_cost_trader_test":{"post":{"operationId":"limited_cost_trader_test","summary":"Test goods spend against 2 percent of turnover or GBP 1,000 a year and return the 16.5 percent limited cost rate when th","description":"Test goods spend against 2 percent of turnover or GBP 1,000 a year and return the 16.5 percent limited cost rate when the business is limited cost. Use for \"I spent GBP 300 on goods against GBP 24,000 of turnover: am I a limited cost business?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"goods_spend":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}],"description":"VAT-inclusive cost of the goods that count under HMRC's limited cost rules for the period, in GBP as a plain decimal string (which purchases count is not modelled here).","title":"Goods Spend"},"vat_inclusive_turnover":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}],"description":"Turnover for the same period including VAT, in GBP, greater than zero.","title":"Vat Inclusive Turnover"},"period_months":{"default":12,"description":"Length of the period both figures cover: 12 (a year) or 3 (a quarterly return). Default 12.","title":"Period Months","type":"integer"}},"required":["goods_spend","vat_inclusive_turnover"],"title":"limited_cost_trader_testArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/compare_standard_vs_flat":{"post":{"operationId":"compare_standard_vs_flat","summary":"Compare output VAT minus input VAT under standard accounting with the flat rate result for the same period. Use for \"Wit","description":"Compare output VAT minus input VAT under standard accounting with the flat rate result for the same period. Use for \"With GBP 4,000 VAT charged and GBP 500 VAT on purchases, would standard VAT accounting or the flat rate cost less this quarter?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"vat_inclusive_turnover":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}],"description":"GBP amount as a plain decimal string such as 1234.50 (digits and one '.'; no commas or symbols).","title":"Vat Inclusive Turnover"},"output_vat":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}],"description":"VAT charged to customers in the period, in GBP (included in the turnover).","title":"Output Vat"},"input_vat":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}],"description":"VAT on purchases you could reclaim under standard accounting in the period, in GBP.","title":"Input Vat"},"category":{"description":"Category name or id from list_frs_categories; a unique part of the name also works (for example 'management consultancy').","title":"Category","type":"string"},"on_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date the percentage applies to, YYYY-MM-DD. Defaults to today (UTC).","title":"On Date"},"vat_registration_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date the business became VAT-registered, YYYY-MM-DD; needed for the 1 percent first-year discount.","title":"Vat Registration Date"},"limited_cost_trader":{"default":false,"description":"True to use the 16.5 percent limited cost rate. Default false.","title":"Limited Cost Trader","type":"boolean"},"capital_asset_input_vat":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}],"default":"0","description":"VAT you can reclaim under the scheme on qualifying capital assets (GOV.UK: certain capital assets over GBP 2,000), in GBP. Default 0; you decide eligibility.","title":"Capital Asset Input Vat"}},"required":["vat_inclusive_turnover","output_vat","input_vat","category"],"title":"compare_standard_vs_flatArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/joining_limit_check":{"post":{"operationId":"joining_limit_check","summary":"Compare expected VAT taxable turnover excluding VAT with the GBP 150,000 figure for joining the Flat Rate Scheme. Use fo","description":"Compare expected VAT taxable turnover excluding VAT with the GBP 150,000 figure for joining the Flat Rate Scheme. Use for \"I expect about GBP 120,000 of VAT taxable turnover next year: am I within the Flat Rate Scheme joining limit?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"expected_vat_taxable_turnover_excl_vat_next_12_months":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}],"description":"Expected VAT taxable turnover for the next 12 months, excluding VAT, in GBP as a plain decimal string.","title":"Expected Vat Taxable Turnover Excl Vat Next 12 Months"}},"required":["expected_vat_taxable_turnover_excl_vat_next_12_months"],"title":"joining_limit_checkArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/frs_reference":{"post":{"operationId":"frs_reference","summary":"Return the Flat Rate Scheme figures and rules held here (joining figure, limited cost rate, first-year discount, dated r","description":"Return the Flat Rate Scheme figures and rules held here (joining figure, limited cost rate, first-year discount, dated rows) with sources and verification labels. Use for \"Where do the Flat Rate Scheme percentages come from and how sure are they?\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"on_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Date the percentage applies to, YYYY-MM-DD. Defaults to today (UTC).","title":"On Date"}},"title":"frs_referenceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}