Calculate VAT
finance.calculate_vat
Overview
You provide an amount (or line items), an amount basis, and a VAT rate percent; we compute exclusive, VAT, and inclusive totals using decimal arithmetic with an explicit rounding point. We do not look up rates, jurisdictions, or reverse-charge rules. Do not use this to choose a tax rate or validate a full invoice document.
Backing exclusive out of an inclusive total in binary floating point loses cents, and every team invents its own rounding order. We do the division in exact decimals and let you choose whether rounding happens per line or once on the total.
Reliability
Same input, same figures — all arithmetic runs in exact decimals, never in floating point, and exclusive plus vat equals inclusive on every line and on the total. Rounding is yours to choose and always reported back in roundingApplied. VAT_RATE_INVALID — trigger: a ratePercent below 0, above 100, unreadable as a decimal, or exactly 0 on a vat_only line, which has nothing to divide by; retryable: no, the same rate always fails; next: send the rate as a plain string between "0" and "100", and use a non-zero rate for vat_only. AMOUNT_INVALID — trigger: an amount we cannot read as a plain decimal, a missing ratePercent in single-amount mode, a scale outside 0 to 12, an unknown rounding mode, or a roundingPoint that is not per_line or total_only; retryable: no; next: drop thousands separators and exponents from your amounts and check the options object against the accepted values. CURRENCY_UNKNOWN — trigger: a currency code outside the twenty we support, or a blank one; retryable: no; next: pick a supported code, and convert on your side first if the invoice is in another currency. VAT_LINE_LIMIT_EXCEEDED — trigger: your lines array holds more than 200 entries; retryable: no; next: split the invoice into batches of 200 lines or fewer and add the totals yourself, or keep the same rounding point so the batches stay comparable. VAT_BASIS_UNSUPPORTED — trigger: an amountBasis that is missing or is not exclusive, inclusive or vat_only, either at the top level or on one of your lines; retryable: no; next: set the basis explicitly on every line — we never guess whether a number already contains VAT.
Context footprint
Returns totals, per-line breakdown, by-rate aggregates, and effective rate in one call. A successful call costs 1 execution credit.
When to use it
When you already know the rate and you need exclusive, VAT, and inclusive figures that reconcile to the cent.
When you still have to pick the rate for a country or product, or when you want a whole invoice document checked.
Scope
Non-goals
- Does not select VAT rates by country or product
- Does not validate place-of-supply or reverse charge
- Does not produce tax filings or legal advice
Properties
Capabilities
Cost & billing
Flat rate per invocation
File handling
How we handle your data
What this means
This skill may receive sensitive content, but it does not target sensitive data and returns only a structured non-sensitive result.
Squillify guarantees
- Runs inside Squillify
- This skill runs inside Squillify.
- Payloads are not sent to an external service by this skill.
- Squillify does not permanently store submitted payloads.
- Telemetry records metadata only, not submitted content.
- Submitted payloads are not used for training.
- Submitted payloads are not reviewed by humans.
- This skill does not target sensitive data.
- The response does not contain submitted content.
Your responsibility
Squillify does not determine whether submitted content is sensitive. Your application is responsible for deciding what data it is allowed to submit. Your application is responsible for securing the response.
Input schema
| Field | Type | Required | Description |
|---|---|---|---|
| amount | object | No | Single amount as a plain decimal string or JSON number. Required unless lines is provided. |
| amountBasis | string | No | What the single amount already contains. Required unless lines is provided. |
| ratePercent | object | No | VAT rate percent from 0 through 100. Required unless lines is provided. |
| lines | array | No | Up to 200 closed VAT line objects; omit the array or send empty to use the single-amount fields instead. |
| currency | string | Yes | ISO 4217 code that fixes the default rounding scale; never converted. |
| options | object | No | Optional VAT rounding controls for mode, decimal scale, and whether each line is rounded before summing; omit it for HALF_UP, the currency scale, and per_line. |
Output schema
| Field | Type | Required | Description |
|---|---|---|---|
| currency | string | Yes | ISO 4217 code these totals were computed under, which also fixed the default rounding scale. |
| exclusive | string | Yes | Total before VAT at the applied scale. |
| vat | string | Yes | VAT total at the applied scale; exclusive plus vat equals inclusive. |
| inclusive | string | Yes | Total with VAT included at the applied scale. |
| ratePercent | string | Yes | Rate of the first computed line, normalized without trailing zeros; read byRate when rates differ. |
| effectiveRatePercent | string | Yes | vat divided by exclusive times 100 at six decimals, or 0.000000 when exclusive is zero. |
| lines | array | Yes | One computed line per input line in your order, or a single l1 row in single-amount mode, each with exclusive, vat, inclusive, and rate. |
| byRate | array | Yes | Lines grouped by distinct ratePercent with exclusive, vat, and inclusive totals, sorted by rate text. |
| roundingApplied | object | Yes | Closed rounding receipt naming the mode, scale, and per_line or total_only point actually used. |
| _meta | object | No | Audit count of how many lines were actually computed, including the synthetic single-amount line. |
API contract
POST /v1/executecurl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"finance.calculate_vat","input":{"amount":"100.00","amountBasis":"exclusive","ratePercent":"21","currency":"EUR"}}'import { Squillify } from "@squillify/sdk";
const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });
const { output } = await sq.execute("finance.calculate_vat", {"amountBasis":"exclusive","ratePercent":"21","options":{"rounding":"HALF_UP"},"currency":"EUR","amount":"100.00"});Errors
| Code | HTTP | Retryable | Description |
|---|---|---|---|
| VALIDATION_ERROR | 400 | No | The request payload failed schema validation. |
| UNAUTHORIZED | 401 | No | Missing or invalid API key. |
| SKILL_NOT_ACCESSIBLE | 403 | No | The API key is not granted access to this skill. |
| SKILL_NOT_AVAILABLE_FOR_PLAN | 403 | No | This skill is not included in your current plan. |
| PLAN_ELIGIBILITY_UNAVAILABLE | 503 | Yes | Plan eligibility could not be decided. Retry after backoff. |
| SKILL_NOT_FOUND | 404 | No | The requested skill or version does not exist. |
| TENANT_RATE_LIMITED | 429 | Yes | Request rate limit exceeded. Retry after backoff. |
| QUOTA_EXCEEDED | 429 | Yes | Plan quota exhausted. Retryable once the quota period resets. |
| EXECUTION_TIMEOUT | 504 | Yes | Execution exceeded the allowed time budget. |
| VAT_RATE_INVALID | 400 | No | The request payload failed this skill's input validation. |
| AMOUNT_INVALID | 400 | No | The request payload failed this skill's input validation. |
| CURRENCY_UNKNOWN | 400 | No | The request payload failed this skill's input validation. |
| VAT_LINE_LIMIT_EXCEEDED | 429 | No | A size, quota, rate, or time limit was exceeded. |
| VAT_BASIS_UNSUPPORTED | 400 | No | The skill does not support the requested variant. |
Other limits
| Limit | Value |
|---|---|
| Recommended inline bytes | 32 KiB |
Limitations
- Does not select VAT rates by country or product
- Does not validate place-of-supply or reverse charge
- Does not produce tax filings or legal advice
- Choosing a jurisdictional VAT rate
- Validating a full invoice document
- Tax compliance decisions
How to call
POST /v1/execute (requires authentication)
{
"skillKey": "finance.calculate_vat",
"input": {
"amountBasis": "exclusive",
"ratePercent": "21",
"options": {
"rounding": "HALF_UP"
},
"currency": "EUR",
"amount": "100.00"
}
}Examples
21% VAT on an exclusive EUR amount
{
"amountBasis": "exclusive",
"ratePercent": "21",
"options": {
"rounding": "HALF_UP"
},
"currency": "EUR",
"amount": "100.00"
}{
"inclusive": "121.00",
"exclusive": "100.00",
"lines": [
{
"id": "l1",
"inclusive": "121.00",
"ratePercent": "21",
"exclusive": "100.00",
"vat": "21.00"
}
],
"byRate": [
{
"inclusive": "121.00",
"ratePercent": "21",
"exclusive": "100.00",
"vat": "21.00"
}
],
"currency": "EUR",
"vat": "21.00",
"effectiveRatePercent": "21.000000",
"ratePercent": "21",
"roundingApplied": {
"scale": 2,
"mode": "HALF_UP",
"point": "per_line"
},
"_meta": {
"lineCount": 1
}
}Back out exclusive from an inclusive total
{
"amountBasis": "inclusive",
"ratePercent": "21",
"options": {
"rounding": "HALF_UP"
},
"currency": "EUR",
"amount": "121.00"
}{
"inclusive": "121.00",
"exclusive": "100.00",
"lines": [
{
"id": "l1",
"inclusive": "121.00",
"ratePercent": "21",
"exclusive": "100.00",
"vat": "21.00"
}
],
"byRate": [
{
"inclusive": "121.00",
"ratePercent": "21",
"exclusive": "100.00",
"vat": "21.00"
}
],
"currency": "EUR",
"vat": "21.00",
"effectiveRatePercent": "21.000000",
"ratePercent": "21",
"roundingApplied": {
"scale": 2,
"mode": "HALF_UP",
"point": "per_line"
},
"_meta": {
"lineCount": 1
}
}Two lines at different rates, grouped for a VAT return
{
"lines": [
{
"ratePercent": "21",
"amountBasis": "exclusive",
"amount": "100.00",
"id": "hosting"
},
{
"ratePercent": "6",
"amountBasis": "exclusive",
"amount": "200.00",
"id": "books"
}
],
"currency": "EUR"
}{
"inclusive": "333.00",
"exclusive": "300.00",
"lines": [
{
"id": "hosting",
"inclusive": "121.00",
"ratePercent": "21",
"exclusive": "100.00",
"vat": "21.00"
},
{
"id": "books",
"inclusive": "212.00",
"ratePercent": "6",
"exclusive": "200.00",
"vat": "12.00"
}
],
"byRate": [
{
"inclusive": "121.00",
"ratePercent": "21",
"exclusive": "100.00",
"vat": "21.00"
},
{
"inclusive": "212.00",
"ratePercent": "6",
"exclusive": "200.00",
"vat": "12.00"
}
],
"currency": "EUR",
"vat": "33.00",
"effectiveRatePercent": "11.000000",
"ratePercent": "21",
"roundingApplied": {
"scale": 2,
"mode": "HALF_UP",
"point": "per_line"
},
"_meta": {
"lineCount": 2
}
}Recommended use cases
- Compute line VAT when you already know the rate
- Derive exclusive amounts from an inclusive total
- Aggregate multi-line invoices by rate with explicit rounding
Avoid for
- Choosing a jurisdictional VAT rate
- Validating a full invoice document
- Tax compliance decisions
Related skills
Composable with
Safety & privacy
- Runs without calling any external service.
- Your payloads are never stored permanently.
- Telemetry captures metadata only — never your payload contents.
- We never train models on your payloads.
- No human reviews your payloads.