API referenceTax rules

Decide whether to charge VAT

Given seller and buyer VAT numbers, returns whether to charge VAT, at what rate, under which mechanism, with legal basis and invoice note. Requires a Business-plan API key. Shares the monthly quota pool with /v1/validate.

Try it live

playground

Body

seller_vatrequiredstringbuyer_vatrequiredstring

30 requests per hour per IP · demo key used automatically

Auth

Requires the Authorization: Bearer <api_key> header. Use a vtv_live_* key in production or a vtv_test_* key for deterministic magic-number responses.

Body

seller_vatrequiredstring · min 4

Seller VAT number, full with country prefix. Seller country is derived from the prefix (e.g., "DE..." → Germany).

example DE811569869

buyer_vatrequiredstring · min 4

Buyer VAT number, full with country prefix. Buyer country is derived from the prefix. This endpoint is B2B-only in v1; for B2C transactions (consumer, no VAT number) support is on the roadmap.

example FR44732829320

200

Response

Decision result

datarequiredobject

data.charge_vatrequiredboolean

Whether the seller should charge VAT to the buyer on this transaction.

example false

data.raterequirednumber

VAT rate to charge, in percent. Zero when the mechanism is `reverse_charge` or `zero_rated`.

example 0

data.mechanismrequiredstring

VAT mechanism that applies. `standard` = seller charges VAT at the applicable rate. `reverse_charge` = buyer accounts for VAT (EU cross-border B2B, Article 196). `zero_rated` = 0% rate applies. `out_of_scope` = transaction falls outside VAT scope.

one of"standard""reverse_charge""zero_rated""out_of_scope"

data.legal_basisrequiredstring

Legal article or rule that justifies the mechanism. Cite this on the invoice when required by local tax authorities.

example EU VAT Directive Article 196

data.explanationrequiredstring

Plain-English explanation of why this mechanism applies. Safe to surface in your app as a tooltip or help text.

example

Your customer provided a valid French VAT number, so this is an EU cross-border B2B supply. The reverse-charge mechanism applies — you do not charge VAT, and the buyer self-accounts.

data.invoice_noterequiredstring

Text to print on the invoice when the mechanism requires it (e.g. reverse-charge notice). Empty string when no note is needed.

example Reverse charge — VAT to be accounted for by the recipient

data.disclaimerrequiredstring

Standard disclaimer. This endpoint applies deterministic tax rules — always confirm with a qualified tax adviser for your specific situation.

example This is guidance, not legal advice. Confirm with a qualified tax adviser for your specific situation.

data.buyer_vatobject

Summary of the buyer VAT validation performed as part of the decide call.

data.buyer_vat.validrequiredboolean

Whether the buyer VAT number is registered and active according to the upstream registry.

example true

data.buyer_vat.countryobject

Buyer country derived from the VAT prefix. Absent when the VAT is malformed.

data.buyer_vat.country.coderequiredstring

example FR

data.buyer_vat.country.namerequiredstring

example France

data.decided_atrequiredstring

ISO 8601 timestamp of when this decision was computed server-side.

example 2026-04-14T15:42:03.451Z

metarequiredobject

meta.request_idrequiredstring

UUID v7 identifying this specific HTTP request.

example 0190f8ea-a5b2-7000-a123-000000000000

meta.latency_msrequiredinteger

Total server-side processing time in milliseconds.

example 820

meta.source_statusrequiredstring

Rolled-up worst-case source status across all lookups (seller + buyer).

one of"live""cached""degraded"

meta.sourcesrequiredarray<object>

Per-VAT source details for the seller and buyer lookups.

Error responses

400Invalid request or unsupported scenario

401Missing or invalid API key

402Requires Business plan

404Test-mode VAT not in magic fixtures

429Rate limit exceeded

import { Vatverify } from '@vatverify/node';
const client = new Vatverify();

const result = await client.decide({
    "seller_vat": "DE811569869",
    "buyer_vat": "FR44732829320"
  });

{
  "data": {
    "charge_vat": false,
    "rate": 0,
    "mechanism": "reverse_charge",
    "legal_basis": "EU VAT Directive Article 196",
    "explanation": "Your customer provided a valid French VAT number, so this is an EU cross-border B2B supply. The reverse-charge mechanism applies — you do not charge VAT, and the buyer self-accounts.",
    "invoice_note": "Reverse charge — VAT to be accounted for by the recipient",
    "disclaimer": "This is guidance, not legal advice. Confirm with a qualified tax adviser for your specific situation.",
    "buyer_vat": {
      "valid": true,
      "country": {
        "code": "FR",
        "name": "France"
      }
    },
    "decided_at": "2026-04-14T15:42:03.451Z"
  },
  "meta": {
    "request_id": "0190f8ea-a5b2-7000-a123-000000000000",
    "latency_ms": 820,
    "source_status": "live",
    "sources": [
      {
        "role": "buyer",
        "source": "vies",
        "source_status": "live",
        "cached": false,
        "cached_at": null,
        "stale_seconds": null
      }
    ]
  }
}

List VAT rates for all 44 countries

Return VAT rates for all 44 countries in our dataset (EU-27 + XI + 16 non-EU European states). Public endpoint — no API key required. Rate-limited to 20 requests per hour per IP. Response body is cacheable (`Cache-Control: public, max-age=3600, stale-while-revalidate=86400`). Clients should honor the `ETag` and use `If-None-Match` for conditional GETs to avoid hitting the limit.

Per-day usage rollup for a key

Returns day-level rollups keyed by (day, endpoint, country, source) for one API key across a date range (≤ 90 days). Free plan returns 402.