Calculate VAT

POST /v1/vat/calculate — Calculate VAT for a given amount, country, and tax class

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	Amount in minor currency units (e.g., €119.00 = `11900`)
`price_includes_vat`	`boolean`	Yes	Whether the gross amount already includes VAT
`transaction_date`	`string`	No	RFC 3339 or `YYYY-MM-DD` format. Defaults to current date.

Example Request

curl -X POST https://api.vat-engine.daily-automations.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.
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 writes an audit transaction row only. It does not create a committed supply event, so OSS threshold monitoring, Filing Prep, and other compliance surfaces will not move unless the sale is also recorded in the committed supply ledger.