curatedapi
Browse the docs

Guides

Finance

Excel functions

Late payments

E-invoices

Accounting

Number checks

VAT and GST

Billing and pricing

Money and currencies

Dates and time

Math

Unit conversion

Everyday

Health

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

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).

InputTypeDescription
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.

ResultTypeDescription
net_totaldecimal (string)Total without tax. Unit: currency.
tax_totaldecimal (string)Total tax: the sum of the tax of each rate. Unit: currency.
gross_totaldecimal (string)Total with tax: net_total + tax_total. Unit: currency.
breakdownlist of objectOne row per tax rate, highest rate first.
lineslist of objectOne row per line, when rounding is per_line.
rate_sourcestringWhere the rate comes from, when country was given.
rate_source_urlstringThe source's address.
rate_checked_ondate (YYYY-MM-DD)The day the rate was last compared with that source.

Examples

An invoice with two rates (the Peppol example's lines)

Requestcurl
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"]
  }'
200 OKResponse
{
  "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

Requestcurl
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
  }'
200 OKResponse
{
  "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

Requestcurl
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"
  }'
200 OKResponse
{
  "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

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.