Calculate VAT

Reference for POST /v1/vat/calculate, including required fields, price-inclusive logic, supply-date handling, and example VAT breakdown responses.

Endpoint

POST /v1/vat/calculate

Required scope: full or calculate-only

Optional Headers

Header	Type	Description
`X-Source-ID`	`string`	Optional headless storefront or custom checkout tag for reporting. Not required for calculation.

X-Source-ID does not affect the VAT rate, net amount, VAT amount, or gross amount. It is captured with the logged VAT calculation event when transaction logging is enabled, so later reports can filter or export rows by checkout/source. Use a stable, non-sensitive source tag from 1 to 100 characters using letters, digits, _, -, or / (for example headless-checkout, custom-store/eu, or mobile-checkout). Do not put customer names, emails, order numbers, API credentials, or other personal/secrets data in this header.

Request Body

Parameter	Type	Required	Description
`country`	`string`	Yes	ISO 3166-1 alpha-2 code (e.g., `DE`, `FR`, `IT`)
`currency`	`string`	Yes	ISO 4217 code (e.g., `EUR`, `USD`)
`tax_class_id`	`string`	Yes	Tax class identifier (e.g., `standard`, `books`, `food`)
`gross_amount_minor`	`integer`	Yes	Input amount in minor currency units (e.g., €119.00 = `11900`)
`price_includes_vat`	`boolean`	Yes	Send explicitly: `true` for a gross input; `false` for a net input
`transaction_date`	`string`	No	RFC 3339 or `YYYY-MM-DD` format. Defaults to current date.

Example Request

curl -X POST https://api.vat-engine.app/v1/vat/calculate \-H "X-API-Key: YOUR_API_KEY" \-H "Content-Type: application/json" \-d '{  "country": "DE",  "currency": "EUR",  "gross_amount_minor": 11900,  "price_includes_vat": true,  "tax_class_id": "standard",  "transaction_date": "2026-01-28"}'

To tag the logged calculation for multi-store or multi-channel reports, add the optional source header:

-H "X-Source-ID: headless-checkout-eu"

Response

{
  "country": "DE",
  "currency": "EUR",
  "vat_rate_bps": 1900,
  "gross_amount_minor": 11900,
  "net_amount_minor": 10000,
  "vat_amount_minor": 1900
}

Response Fields

Field	Type	Description
`country`	`string`	ISO country code
`currency`	`string`	ISO currency code
`vat_rate_bps`	`integer`	VAT rate in basis points (1900 = 19.00%)
`gross_amount_minor`	`integer`	Gross amount in minor units
`net_amount_minor`	`integer`	Net amount (excluding VAT) in minor units
`vat_amount_minor`	`integer`	VAT amount in minor units

Notes

All amounts are in minor currency units (cents) to avoid floating-point errors.
VAT rates are in basis points (1/100th of a percent). 1900 bps = 19.00%.
When price_includes_vat is true, the API extracts VAT from the gross amount. When false, it adds VAT on top.
Send price_includes_vat explicitly, including false for net input. Omitted or null values return 400 missing_price_includes_vat.
X-Source-ID is optional reporting metadata. Omit it if you do not need store/channel filtering in transaction reports.
Managed source profiles can also register the same source key through POST /v1/sources, but the header itself stays a raw stable integration tag.
This endpoint records calculation history only. It does not add a sale to OSS threshold monitoring, Filing Prep, or other compliance reports.

transaction_date resolves a rate from recorded/imported lookup windows. Current live TEDB apply history can reflect when a change was applied, so this is not yet a guarantee that the selected window is the source-supported legal applicability interval. Responses also do not yet carry an immutable TEDB rate-data version or support snapshot-pinned replay. Legal-date preservation, version pinning, and knowledge-time selection are planned additions.