VAT and GST API
VAT or GST on one amount or a whole invoice, added or taken out of tax-inclusive prices, with the per-rate rounding EN 16931 e-invoices require.
POST https://api.curatedapi.com/v1/calc/tax/vat
- Version 1
- MCP tool
calc_tax_vat - Try it in the browser
Works out net, tax and gross for one amount or for every line of an invoice. Give amounts without tax to add it, or set amounts_include_tax to take the tax out of prices that already include it. Lines can have different rates. By default the tax is worked out once for each rate on the sum of that rate's lines and rounded to the cent, which is how the European e-invoice standard EN 16931 (and so XRechnung, Peppol and Factur-X) defines the VAT breakdown. The other choice rounds the tax on each line and adds those up, as a till receipt does; the two can differ by a few cents on a long invoice. The rate can be given, or looked up as a country's standard rate, in which case the answer names the official page it came from.
Formula
tax = round(net × rate / 100); from a price with tax: net = round(gross / (1 + rate / 100)), tax = gross − net; per_rate applies this to each rate's sum of lines, per_line to each line
- Amounts are rounded to the cent (2 decimals) half up by default. Set options.decimals for currencies with other minor units (0 for JPY) and options.rounding for another rule.
- Each line amount is rounded first, because an invoice line has at most two decimals. Net, tax and gross then always add up exactly.
- Which rate applies to a sale, and whether tax is due at all, depends on what is sold, to whom and where. This calculator does the arithmetic for the rates you give.
Inputs
Send numbers as strings to keep every digit. options sets precision and rounding (see numbers and rounding).
| Input | Type | Description |
|---|---|---|
amounts required |
list of decimal (string) | The amount of each line: one item for a single price. Without tax, or with tax when amounts_include_tax is true. Negative amounts are credits. 1 to 1000 items. Each item: >= -1000000000000000 and <= 1000000000000000. Unit: currency. |
rate_percent |
decimal (string) | One tax rate for every line, in percent (20 for 20%). Allowed: >= 0 and <= 100. Unit: %. |
rates_percent |
list of decimal (string) | The tax rate of each line in percent, one per amount and in the same order. Up to 1000 items. Each item: >= 0 and <= 100. Unit: %. |
country |
AT | BE | BG | CY | CZ | DE | DK | EE | EL | ES | FI | FR | HR | HU | IE | IT | LT | LU | LV | MT | NL | PL | PT | RO | SE | SI | SK | GB | CH | NO | AU | NZ | SG | IN | CA | CA-NB | CA-NL | CA-NS | CA-ON | CA-PE | GR | UK | Use this country's standard rate for every line (see tax/vat-rates for the table). Reduced rates depend on what is sold, so give those as rate_percent. Options: AT: Austria: VAT 20%; BE: Belgium: VAT 21%; BG: Bulgaria: VAT 20%; CY: Cyprus: VAT 19%; CZ: Czechia: VAT 21%; DE: Germany: VAT 19%; DK: Denmark: VAT 25%; EE: Estonia: VAT 24%; EL: Greece: VAT 24%; ES: Spain: VAT 21%; FI: Finland: VAT 25.5%; FR: France: VAT 20%; HR: Croatia: VAT 25%; HU: Hungary: VAT 27%; IE: Ireland: VAT 23%; IT: Italy: VAT 22%; LT: Lithuania: VAT 21%; LU: Luxembourg: VAT 17%; LV: Latvia: VAT 21%; MT: Malta: VAT 18%; NL: Netherlands: VAT 21%; PL: Poland: VAT 23%; PT: Portugal: VAT 23%; RO: Romania: VAT 21%; SE: Sweden: VAT 25%; SI: Slovenia: VAT 22%; SK: Slovakia: VAT 23%; GB: United Kingdom: VAT 20%; CH: Switzerland: VAT (MWST) 8.1%; NO: Norway: VAT (MVA) 25%; AU: Australia: GST 10%; NZ: New Zealand: GST 15%; SG: Singapore: GST 9%; IN: India: GST 18%; CA: Canada (GST only): GST 5%; CA-NB: Canada: New Brunswick: HST 15%; CA-NL: Canada: Newfoundland and Labrador: HST 15%; CA-NS: Canada: Nova Scotia: HST 14%; CA-ON: Canada: Ontario: HST 13%; CA-PE: Canada: Prince Edward Island: HST 15%; GR: the same as EL; UK: the same as GB |
amounts_include_tax |
boolean default False |
true when the amounts already include the tax, to take it out. |
rounding |
per_rate | per_line default per_rate |
Where the tax is rounded. Options: per_rate: once for each rate, on the sum of that rate's lines (EN 16931, the usual rule for invoices); per_line: on each line, then added up (till receipts, and invoices that print tax per line) |
options.rounding |
half_even | half_up | half_down | up | down | ceiling | floor | Rounding mode applied once to each result. Default half_up. |
options.decimals |
integer | Round results to this many digits after the decimal point. |
Result
Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.
| Result | Type | Description |
|---|---|---|
net_total | decimal (string) | Total without tax. Unit: currency. |
tax_total | decimal (string) | Total tax: the sum of the tax of each rate. Unit: currency. |
gross_total | decimal (string) | Total with tax: net_total + tax_total. Unit: currency. |
breakdown | list of object | One row per tax rate, highest rate first. |
lines | list of object | One row per line, when rounding is per_line. |
rate_source | string | Where the rate comes from, when country was given. |
rate_source_url | string | The source's address. |
rate_checked_on | date (YYYY-MM-DD) | The day the rate was last compared with that source. |
Examples
An invoice with two rates (the Peppol example's lines)
curl https://api.curatedapi.com/v1/calc/tax/vat \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"amounts": ["4000", "900", "100", "2000"],
"rates_percent": ["25", "25", "25", "0"]
}'
{
"calculator": "tax/vat@1",
"result": {
"net_total": "7000.00",
"tax_total": "1250.00",
"gross_total": "8250.00",
"breakdown": [
{
"rate_percent": "25",
"net": "5000.00",
"tax": "1250.00",
"gross": "6250.00"
},
{
"rate_percent": "0",
"net": "2000.00",
"tax": "0.00",
"gross": "2000.00"
}
]
},
"exactness": {
"net_total": "exact",
"tax_total": "exact",
"gross_total": "exact"
},
"precision": {
"rounding": "half_up",
"decimals": 2
},
"inputs": {
"amounts": [
"4000",
"900",
"100",
"2000"
],
"rates_percent": [
"25",
"25",
"25",
"0"
],
"amounts_include_tax": false,
"rounding": "per_rate"
},
"formula": "tax = round(net × rate / 100); from a price with tax: net = round(gross / (1 + rate / 100)), tax = gross − net; per_rate applies this to each rate's sum of lines, per_line to each line",
"references": [
{
"title": "Peppol BIS Billing 3.0 (EN 16931): calculation of VAT, BT-116 and BT-117",
"url": "https://docs.peppol.eu/poacc/billing/3.0/bis/#_calculation_of_vat"
},
{
"title": "GOV.UK: VAT rates, working out VAT-inclusive and VAT-exclusive prices",
"url": "https://www.gov.uk/vat-businesses/vat-rates"
},
{
"title": "Australian Taxation Office: GST is one eleventh of the price",
"url": "https://www.ato.gov.au/other-languages/information-in-other-languages/gst/goods-and-services-tax-gst-when-you-sell-to-australia"
}
],
"warnings": []
}
Take 20% VAT out of a price of 180
curl https://api.curatedapi.com/v1/calc/tax/vat \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"amounts": ["180"],
"rate_percent": "20",
"amounts_include_tax": true
}'
{
"calculator": "tax/vat@1",
"result": {
"net_total": "150.00",
"tax_total": "30.00",
"gross_total": "180.00",
"breakdown": [
{
"rate_percent": "20",
"net": "150.00",
"tax": "30.00",
"gross": "180.00"
}
]
},
"exactness": {
"net_total": "exact",
"tax_total": "exact",
"gross_total": "exact"
},
"precision": {
"rounding": "half_up",
"decimals": 2
},
"inputs": {
"amounts": [
"180"
],
"rate_percent": "20",
"amounts_include_tax": true,
"rounding": "per_rate"
},
"formula": "tax = round(net × rate / 100); from a price with tax: net = round(gross / (1 + rate / 100)), tax = gross − net; per_rate applies this to each rate's sum of lines, per_line to each line",
"references": [
{
"title": "Peppol BIS Billing 3.0 (EN 16931): calculation of VAT, BT-116 and BT-117",
"url": "https://docs.peppol.eu/poacc/billing/3.0/bis/#_calculation_of_vat"
},
{
"title": "GOV.UK: VAT rates, working out VAT-inclusive and VAT-exclusive prices",
"url": "https://www.gov.uk/vat-businesses/vat-rates"
},
{
"title": "Australian Taxation Office: GST is one eleventh of the price",
"url": "https://www.ato.gov.au/other-languages/information-in-other-languages/gst/goods-and-services-tax-gst-when-you-sell-to-australia"
}
],
"warnings": []
}
Three lines of 0.99 at 19%, rounded on each line
curl https://api.curatedapi.com/v1/calc/tax/vat \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"amounts": ["0.99", "0.99", "0.99"],
"rate_percent": "19",
"rounding": "per_line"
}'
{
"calculator": "tax/vat@1",
"result": {
"net_total": "2.97",
"tax_total": "0.57",
"gross_total": "3.54",
"breakdown": [
{
"rate_percent": "19",
"net": "2.97",
"tax": "0.57",
"gross": "3.54"
}
],
"lines": [
{
"line": 1,
"rate_percent": "19",
"net": "0.99",
"tax": "0.19",
"gross": "1.18"
},
{
"line": 2,
"rate_percent": "19",
"net": "0.99",
"tax": "0.19",
"gross": "1.18"
},
{
"line": 3,
"rate_percent": "19",
"net": "0.99",
"tax": "0.19",
"gross": "1.18"
}
]
},
"exactness": {
"net_total": "exact",
"tax_total": "exact",
"gross_total": "exact"
},
"precision": {
"rounding": "half_up",
"decimals": 2
},
"inputs": {
"amounts": [
"0.99",
"0.99",
"0.99"
],
"rate_percent": "19",
"amounts_include_tax": false,
"rounding": "per_line"
},
"formula": "tax = round(net × rate / 100); from a price with tax: net = round(gross / (1 + rate / 100)), tax = gross − net; per_rate applies this to each rate's sum of lines, per_line to each line",
"references": [
{
"title": "Peppol BIS Billing 3.0 (EN 16931): calculation of VAT, BT-116 and BT-117",
"url": "https://docs.peppol.eu/poacc/billing/3.0/bis/#_calculation_of_vat"
},
{
"title": "GOV.UK: VAT rates, working out VAT-inclusive and VAT-exclusive prices",
"url": "https://www.gov.uk/vat-businesses/vat-rates"
},
{
"title": "Australian Taxation Office: GST is one eleventh of the price",
"url": "https://www.ato.gov.au/other-languages/information-in-other-languages/gst/goods-and-services-tax-gst-when-you-sell-to-australia"
}
],
"warnings": []
}
References
- Peppol BIS Billing 3.0 (EN 16931): calculation of VAT, BT-116 and BT-117
- GOV.UK: VAT rates, working out VAT-inclusive and VAT-exclusive prices
- Australian Taxation Office: GST is one eleventh of the price
Results follow each calculator's documented rules and the sources listed. They are not financial, tax or legal advice. Check that the rules fit your case before you rely on a result. See the terms.
Errors share one format; see errors. Billing, retries and batches work the same for every endpoint.