DEV Community: VAT Engine

What Should a VAT Calculation Record Actually Contain?

Vasyl Kyryliuk — Thu, 08 Oct 2026 19:01:28 +0000

A VAT calculation can look deceptively simple.

You send an amount and a country. The system returns a VAT amount.

For example:

Net:   €100.00
VAT:    €19.00
Gross: €119.00

If all you need is the number right now, that may appear sufficient.

The problem starts six months later.

Someone asks:

Why was 19% used?
Which product tax class was selected?
Which transaction date determined the rate?
Was the input gross or net?
Which store or checkout produced the calculation?
Which rate dataset was used?
Has the calculation logic changed since then?
Can we reproduce the exact result?

If the only thing you stored was 19.00, most of those questions are impossible to answer reliably.

A useful VAT calculation record therefore needs to preserve more than the result.

It needs to preserve enough context, identity, and provenance to explain how that result came into existence.

The result is only one part of the record

A calculation record has several different responsibilities.

At minimum, it should let you answer four questions:

What was calculated?
Which inputs and tax context were used?
Which rate and calculation logic produced the result?
Can the result be reproduced later?

That means the record needs more than:

{
  "vat": 1900
}

A more useful model starts looking like this:

{
  "calculation_id": "e2d0940e-b123-47b7-80ad-8a3673fa4680",
  "country": "DE",
  "currency": "EUR",
  "vat_rate_bps": 1900,
  "gross_amount_minor": 11900,
  "net_amount_minor": 10000,
  "vat_amount_minor": 1900,
  "transaction_date": "2026-01-28T00:00:00Z"
}

Even this is only the beginning.

1. Start with a stable calculation identity

Every persisted calculation should have its own stable identifier.

For example:

calculation_id

This gives other systems something durable to reference.

A checkout, support ticket, export, reconciliation process, or internal business record can retain that ID without copying every implementation detail.

It also makes later retrieval straightforward:

GET /v1/transactions/{id}

In VAT Engine, calculation_id is the same identity exposed by the Transactions API rather than a second unrelated identifier.

That sounds like a small design choice, but duplicate identifiers quickly make financial systems harder to reason about.

One calculation should have one canonical identity.

2. Preserve the monetary values explicitly

A VAT calculation record should not store only the VAT amount.

You usually want all three values:

net
VAT
gross

For example:

{
  "net_amount_minor": 10000,
  "vat_amount_minor": 1900,
  "gross_amount_minor": 11900
}

This matters because one value should not need to be reverse-engineered later from another.

It also makes reconciliation easier.

If an external system says:

Gross: €119.00
VAT:   €19.00

you can compare the recorded values directly rather than reconstructing them using whatever calculation rules happen to exist today.

VAT Engine represents monetary values using integer minor units.

So:

€119.00 → 11900
€19.00  → 1900

This avoids making binary floating point the canonical representation of money.

I covered the reasoning in more detail here:

Why Money Calculations Should Not Use Floating Point

3. Record the rate — but not just the rate

You should obviously know which VAT rate was applied.

For example:

{
  "vat_rate_bps": 1900
}

VAT Engine represents VAT rates in basis points:

1900 = 19.00%
700  = 7.00%

But storing 1900 alone is not enough.

A rate without context raises another question:

Why was this the applicable 19% rate?

That question requires provenance.

A calculation record should ideally distinguish between:

the numeric rate

and:

the evidence explaining where that rate came from

Those are not the same thing.

4. Transaction date is part of the tax context

Tax rates and treatment rules can change over time.

So the record should preserve the transaction or supply date used by the calculation.

For example:

{
  "transaction_date": "2026-01-28T00:00:00Z"
}

This is particularly important for:

refunds
corrections
historical imports
migrations
support investigations
audits
delayed reconciliation

Recalculating an old transaction with today's rate can produce a perfectly valid calculation for the wrong date.

That is why a VAT API should treat the date as part of the calculation context rather than incidental metadata.

5. Preserve the tax classification

Country alone does not determine VAT treatment.

The product or service classification matters too.

A record should therefore preserve whichever classification was actually used.

In a simple tax-class model that might be:

{
  "tax_class_id": "standard"
}

Other systems may use:

CN codes
CPA codes
HS codes
merchant-defined tax categories
governed mappings between classifications

The important rule is that the record should preserve the actual classification input or resolved mapping, not merely the resulting percentage.

Otherwise two calculations using the same numeric rate can become indistinguishable even though they reached that rate through different assumptions.

VAT Engine exposes its public tax-class catalogue here:

Tax Classes API

6. Preserve whether the input included VAT

Consider these two requests:

€100 net + 19% VAT

and:

€100 gross including 19% VAT

They do not mean the same thing.

The first produces:

Net:   €100.00
VAT:    €19.00
Gross: €119.00

The second requires VAT extraction:

Net:   €84.03
VAT:   €15.97
Gross: €100.00

So the amount basis is part of the calculation contract.

VAT Engine makes this explicit through:

{
  "price_includes_vat": true
}

or:

{
  "price_includes_vat": false
}

A stored record should retain enough information to know which interpretation was used.

For more on the arithmetic:

VAT-Inclusive vs VAT-Exclusive Pricing: The Math Developers Get Wrong

7. Rate provenance should be a first-class field

A useful VAT record should not merely say:

rate = 19%

It should be able to explain the status of the evidence behind that rate.

VAT Engine exposes that separately as:

{
  "rate_provenance": {
    "schema_version": "rate-evidence/v1",
    "evidence_status": "legacy_unverifiable",
    "source": "legacy_recorded_window",
    "effective_at": "2026-01-28T00:00:00Z",
    "source_evidence": []
  }
}

The important part here is not the exact schema.

It is the distinction between:

numeric result

and:

strength of evidence behind that result

For example, historical data should not suddenly become verified merely because its numeric value happens to match a newer reviewed rate.

VAT Engine deliberately keeps older records marked as:

legacy_unverifiable

when the required source-supported historical evidence was not captured.

That is more useful than pretending certainty exists where it does not.

8. Record which calculation logic produced the result

Rates are only half of the equation.

The arithmetic implementation itself can also change.

Imagine that a system changes:

rounding behavior
currency-scale handling
inclusive VAT extraction
validation rules
allocation behavior

You now need to know which version created an old result.

That is why calculation provenance matters.

A record can retain fields such as:

{
  "calculation_provenance": {
    "schema_version": "calculation-evidence/v1",
    "calculation_version": "vat-calculator-half-up/v1",
    "execution_digest": "...",
    "algorithm_manifest_version": "vat-algorithm-manifest/v1",
    "algorithm_manifest_digest": "...",
    "evidence_status": "captured",
    "replay_status": "ineligible"
  }
}

This gives the result a technical identity.

Instead of saying:

"Our calculator currently returns this."

you can say:

"This calculation was produced using this recorded calculation contract."

That distinction becomes increasingly important as financial software evolves.

9. Source attribution helps explain where the calculation came from

A merchant may have several systems producing VAT calculations:

Shopify
WooCommerce
subscription billing
mobile checkout
POS
custom headless store

A stable source identifier helps distinguish them.

VAT Engine supports an optional:

X-Source-ID

For example:

headless-checkout
shopify-orders
stripe-subscriptions

That value can later appear as source_id in transaction history and reporting.

Importantly, the source tag does not change the VAT rate or amounts.

It is reporting and attribution metadata.

That separation is useful:

tax inputs determine the calculation
source metadata tells you where the calculation originated

Source identifiers should also remain non-sensitive.

Do not put things like:

customer names
email addresses
access tokens
API credentials
individual order numbers

into a general source tag.

10. Evidence status should not be reduced to a boolean

A tempting model is:

{
  "verified": true
}

That usually loses too much information.

Evidence can exist in several meaningful states.

For example:

verified
legacy_unverifiable
unavailable

Calculation evidence may similarly distinguish between captured evidence and records that cannot be proven to the same standard.

This makes uncertainty explicit.

Financial systems become difficult to audit when:

unknown

is silently converted into:

false

or:

verified

A typed status is usually much safer.

11. Replay eligibility is different from evidence capture

Having evidence does not automatically mean you can reproduce a calculation exactly.

Exact replay requires enough preserved information to reconstruct the original decision without silently substituting today's data.

VAT Engine therefore treats replay as a separate state:

not_supported
ineligible
available

Only records reporting:

replay_status: available

are eligible for exact replay.

The replay endpoint can then use the original canonical request, pinned historical rate evidence, and registered calculator version:

POST /v1/transactions/{id}/replay

A successful exact replay returns the reproduced result rather than asking the caller to choose a different rate version.

That distinction is important.

If the caller selects a newer historical dataset or a different calculator version, that is no longer replay.

It is a new, counterfactual calculation.

12. Idempotency belongs near the calculation boundary

A calculation record is also easier to trust when network retries cannot accidentally create different stored results.

For operations that can be retried, an idempotency key can bind the original request.

VAT Engine supports:

Idempotency-Key

for authenticated calculations.

The same key with the same canonical request returns the existing calculation.

The same key with a different request fails instead of silently mutating the record.

That matters because distributed systems retry.

A timeout does not necessarily mean:

the calculation failed

It may mean:

the calculation succeeded but the response was lost

Stable calculation identity plus idempotency makes that situation much easier to handle safely.

13. A calculation record is not the same as a sales ledger

This distinction is especially important.

A VAT calculation can be useful evidence without being proof that a sale actually happened.

For example, a merchant could call a calculator while:

previewing a checkout
testing an integration
quoting a price
simulating a transaction
debugging an order

That does not mean the transaction should automatically enter OSS reporting.

VAT Engine therefore separates:

VAT calculation history

from:

committed sales data

Calling:

POST /v1/vat/calculate

records calculation history, but does not by itself add a sale to:

OSS threshold monitoring
Filing Prep
OSS/IOSS reporting

Those workflows rely on committed supply data.

This prevents an API calculation from being mistaken for an accounting event.

The Transactions API documentation makes this distinction explicit:

VAT Engine Transactions API

14. A record should preserve facts, not force conclusions

There is another architectural benefit to richer records.

You can improve interpretation later without rewriting history.

For example, if you preserve:

transaction date
classification
amount basis
source
rate evidence
calculation version
result

then future tooling can review that record with more context.

If you preserve only:

VAT = €19

most of that opportunity disappears.

This is why provenance-heavy systems can look verbose.

The extra fields are not there because JSON needs to be complicated.

They are there because financial decisions often need to survive longer than the code that originally produced them.

What I would consider the minimum useful record

For a straightforward VAT calculation API, I would want at least:

Stable calculation ID

Inputs:
- country / jurisdiction
- currency
- input amount
- whether VAT was included
- tax classification
- transaction date

Outputs:
- net amount
- VAT amount
- gross amount
- applied VAT rate

Context:
- source/store/channel identifier where useful

Evidence:
- rate evidence status
- rate source/version
- calculation version
- calculation evidence status
- replay status

For more complex tax systems, the model may need to go further.

For example, a transaction can contain separate tax or obligation components rather than one flat rate.

In that case the record should preserve those components individually rather than flattening them into a number that loses the calculation structure.

What not to store as your only record

These patterns tend to cause trouble later.

Only the final VAT amount

{
  "vat": 1900
}

You cannot explain the rate, date, classification, or arithmetic.

Only the rate

{
  "rate": 0.19
}

You do not know which amount it applied to or why that rate was selected.

A mutable reference to "current rate"

If historical records resolve through whatever the current configuration happens to be, old calculations can effectively change meaning.

Money as floating point

{
  "gross": 119.00
}

JSON may look harmless, but using binary floating point as the application's canonical monetary representation introduces unnecessary ambiguity.

A generic `verified: true`

It hides whether rate evidence, calculation evidence, and replay evidence were actually available.

The useful question is not "what did we calculate?"

The useful question is:

Can we explain why this exact result exists?

That changes the shape of the system.

A calculator returns numbers.

A useful calculation record preserves:

identity
inputs
context
result
rate evidence
calculation evidence
reproducibility

That makes debugging easier.

It makes reconciliation easier.

It makes historical review easier.

And it prevents future versions of your own software from silently rewriting the meaning of old calculations.

For financial APIs, that is usually worth a few extra fields.

You can see the current VAT Engine calculation contract here:

Calculate VAT API

And the calculation-history/evidence model here:

Transactions API

VAT Engine is currently in active alpha development. This article describes engineering and API design considerations and is not tax or legal advice.

Why Money Calculations Should Not Use Floating Point

Vasyl Kyryliuk — Fri, 02 Oct 2026 20:36:33 +0000

Financial software often starts with code that looks completely harmless:

const price = 19.99;
const vatRate = 0.19;

const vat = price * vatRate;

The formula is not the surprising part.

The representation is.

Most mainstream programming languages represent values such as 19.99, 0.1, and 0.19 using binary floating point.

That representation is extremely useful for scientific computing, graphics, statistics, simulations, and many other problems.

Money has a different set of requirements.

A payment, invoice, VAT amount, or accounting total usually needs to be:

reproducible;
represented at a known currency precision;
rounded according to an explicit rule;
consistent across services;
safe to persist and export;
understandable later.

Those requirements make binary floating point a poor default canonical representation for money.

For VAT software, even a small inconsistency can eventually appear in net amounts, VAT amounts, gross totals, reports, exports, or reconciliation.

Key takeaways

Many decimal fractions cannot be represented exactly using binary floating point.
Money is usually better modeled as an amount plus currency and scale.
Integer minor units make the monetary input exact.
VAT rates can also be represented using integer basis points.
Rounding belongs in the calculation contract, not only in UI formatting.
Decimal libraries are also valid when their precision and rounding rules are explicit.
Correct arithmetic still requires the correct tax class, rate, country, and transaction context.

The classic floating-point example

Open a JavaScript console and run:

0.1 + 0.2

You do not get exactly:

0.3

Instead, JavaScript produces:

0.30000000000000004

This is not a JavaScript bug.

It is a consequence of binary floating-point representation.

Many decimal fractions that are simple in base 10 do not have a finite representation in base 2.

A similar problem exists in decimal notation:

1 / 3 = 0.333333...

There is no finite decimal representation of one third.

Likewise, values such as 0.1 cannot be represented exactly using a finite binary fraction.

The runtime therefore stores the closest available approximation.

For many applications, that approximation is perfectly acceptable.

For money, it is usually better not to make that approximation part of the monetary domain model.

Money is discrete at a defined currency precision

Consider:

€19.99

For ordinary EUR calculations, that amount can be represented as:

1,999 cents

Instead of:

const price = 19.99;

the core financial representation can be:

const priceMinor = 1999;

Now:

const a = 10; // €0.10
const b = 20; // €0.20

const total = a + b;

console.log(total);
// 30

There is no floating-point approximation involved in:

10 + 20 = 30

The application can convert the value into a formatted monetary string later:

30 minor units → €0.30

VAT Engine follows this model in its VAT calculation API.

For EUR:

€1.00   → 100
€19.99  → 1999
€119.00 → 11900

The API therefore uses fields such as:

gross_amount_minor
net_amount_minor
vat_amount_minor

rather than using binary floating-point monetary values as the core VAT calculation input and output.

Not every currency has two decimal places

A common simplification is:

Store everything in cents.

That works for currencies such as EUR and USD, but it is not a general money model.

Currencies can use different minor-unit scales.

Conceptually, a monetary value therefore needs at least:

amount
currency
scale

A domain type could look like:

type Money = {
  amountMinor: bigint;
  currency: string;
  scale: number;
};

For example:

EUR → 2 decimal places
JPY → 0 decimal places

Other currencies can use different defined scales.

VAT Engine's money model validates the currency and expected minor-unit scale instead of treating every currency as if it automatically had two decimal places.

Floating point mixes representation with rounding

Suppose we calculate 19% VAT on:

€19.99

A floating-point implementation may start with:

const net = 19.99;
const vatRate = 0.19;

const vat = net * vatRate;

Mathematically:

19.99 × 0.19 = 3.7981

EUR cannot represent:

€3.7981

as a final monetary amount.

At some point the result needs to be rounded.

For example:

€3.7981 → €3.80

That rounding decision is unavoidable.

The problem with using floating point as the money representation is that approximation already exists before the application's financial rounding policy is applied.

When values move through:

browser
→ API
→ worker
→ database
→ report
→ export

different implementations can also:

round at different stages;
serialize numbers differently;
aggregate before or after rounding;
use different numeric types.

A more predictable design keeps the monetary input exact and makes the rounding step explicit.

Minor units make the monetary input exact

Represent:

€19.99

as:

and represent the VAT rate separately.

For a VAT-exclusive price with a 19% rate:

VAT =
1999 × 19 / 100

which gives:

379.81 minor units

The currency cannot represent:

0.81

of a cent.

Now we have reached the actual financial decision:

How should the fractional minor unit be rounded?

Using half-up rounding:

379.81 → 380

The result becomes:

Net:   €19.99
VAT:   €3.80
Gross: €23.79

The important difference is that:

was exact.

Rounding happened deliberately at the monetary calculation boundary rather than being mixed with the representation of the input value.

VAT rates can be represented as integers too

Monetary amounts are not the only decimal-looking values involved in VAT.

A VAT rate such as:

19%

is often represented in application code as:

0.19

But the rate can also be represented using an integer.

VAT Engine's calculation contract uses basis points.

For example:

19.00% = 1900 basis points
20.00% = 2000 basis points
7.00%  = 700 basis points

A calculation response can therefore contain:

{
  "vat_rate_bps": 1900
}

For a VAT-exclusive calculation, the core arithmetic can be expressed as:

VAT minor units =
amount_minor × rate_bps / 10000

Using:

amount_minor = 1999
rate_bps     = 1900

gives:

1999 × 1900 / 10000

The fractional result is then rounded according to the defined calculation rule.

The Calculate VAT API exposes both money and VAT rates using these explicit integer representations.

VAT-inclusive pricing still requires fractional arithmetic

Integer representation does not mean that all intermediate mathematical results are integers.

Suppose:

Gross: €19.99
VAT rate: 19%

or:

gross_minor = 1999
rate_bps    = 1900

Because VAT is already included in the gross amount, it has to be extracted.

The formula is:

VAT =
Gross × Rate / (100% + Rate)

Using basis points:

VAT minor units =
1999 × 1900 / (10000 + 1900)

or:

1999 × 1900 / 11900

This produces a fractional minor-unit result.

That value is then rounded using the defined rounding rule.

The important distinction is:

Integer money representation does not eliminate rounding. It makes the point where rounding is required explicit.

For a deeper explanation of inclusive versus exclusive VAT arithmetic, see VAT-Inclusive vs VAT-Exclusive Pricing: The Math Developers Get Wrong.

Rounding is part of the financial contract

Once an intermediate result contains a fraction of a minor unit, the application needs a defined policy.

Possible approaches include:

round half up
round half away from zero
round half to even
truncate
round per line
round only after aggregation

These approaches are not interchangeable.

For example, imagine several order lines where each line creates a fractional cent of VAT.

One system might:

calculate → round every line → sum

while another might:

calculate every line → sum exact intermediates → round once

Those systems can produce different totals.

That does not necessarily mean either system has a floating-point bug.

It means the rounding contract differs.

VAT Engine's core VAT calculation arithmetic works with integer minor units and applies deterministic half-up rounding to the VAT fraction.

The behavior is documented in the Calculate VAT API reference.

Formatting is not calculation

Another useful separation is:

financial value
≠
display string

A core system might store:

{
  "currency": "EUR",
  "net_amount_minor": 1999,
  "vat_amount_minor": 380,
  "gross_amount_minor": 2379
}

A European UI could display:

€19.99
€3.80
€23.79

Another locale might display:

19,99 €
3,80 €
23,79 €

The formatting changed.

The money did not.

Currency formatting belongs at the presentation boundary.

It should not define how the underlying amount is represented or calculated.

An integer alone is not money

This:

is not enough information.

It could represent:

€19.99
$19.99
¥1,999

or another currency amount.

Money therefore needs currency identity as part of the value.

That also means this should not be accepted as ordinary addition:

€10.00 + $10.00

An explicit exchange-rate operation is required first.

A money type can enforce rules that a primitive number cannot.

For example:

type Money = {
  amountMinor: bigint;
  currency: string;
  scale: number;
};

Adding two values can require:

same currency
+
same scale

before the arithmetic is allowed.

Exchange rates are a separate numeric domain

There is an important nuance here.

Saying:

Do not use binary floating point as the canonical representation of money.

does not mean:

Every numeric value inside financial software must always be an integer.

Exchange rates, ratios, measurements, or other values may require precision beyond a currency's final minor-unit scale.

For example:

1 EUR = 4.3176 PLN

is a rate, not a monetary amount.

A cleaner architecture treats these as different domain concepts:

Money    → currency + minor units
VAT rate → basis points
FX rate  → explicitly defined rate representation

The conversion into money then happens at a well-defined boundary with a known rounding policy.

That is much easier to reason about than using one generic floating-point type for every financial concept.

Decimal libraries are also a valid solution

Integer minor units are not the only reasonable way to implement monetary arithmetic.

Arbitrary-precision or fixed-point decimal libraries can also be appropriate.

They are especially useful when:

intermediate values require more precision than the final currency scale;
decimal quantities need to remain exact;
financial formulas involve multiple precision stages.

The important requirements are still the same:

precision should be explicit;
scale should be explicit;
rounding should be explicit;
serialization should be predictable.

So the rule is not:

Only integers are acceptable for financial software.

A better rule is:

Do not let binary floating-point behavior silently define the semantics of your money.

For APIs, integer minor units have the additional advantage of creating a simple cross-language contract:

{
  "currency": "EUR",
  "amount_minor": 1999
}

Every consumer sees the same integer.

Keep the amount basis explicit

Correct monetary representation does not remove the need for correct business context.

For VAT calculations, a system also needs to know whether the input represents:

net

or:

gross

VAT Engine exposes this explicitly:

{
  "price_includes_vat": true
}

or:

{
  "price_includes_vat": false
}

For example:

{
  "country": "DE",
  "currency": "EUR",
  "gross_amount_minor": 11900,
  "price_includes_vat": true,
  "tax_class_id": "standard",
  "transaction_date": "2026-01-28"
}

A calculation can return:

{
  "vat_rate_bps": 1900,
  "gross_amount_minor": 11900,
  "net_amount_minor": 10000,
  "vat_amount_minor": 1900
}

The full request and response contract is available in the VAT calculation API documentation.

You can also experiment with gross and net calculations using the VAT calculator.

Exact money does not automatically mean correct VAT

Using minor units solves a particular class of engineering problems.

It does not determine the correct VAT treatment.

A calculation can still depend on:

destination country;
tax class;
transaction date;
selected VAT rate;
relevant transaction facts.

So:

integer arithmetic

does not automatically imply:

correct VAT treatment

A more complete model is:

correct transaction facts
+ correct rate selection
+ exact money representation
+ explicit rounding
= reproducible VAT calculation

VAT Engine separates these concerns.

You can inspect:

independently.

Persist the canonical monetary representation

A system can implement its calculator correctly and still lose that consistency later.

For example:

API calculation → integer minor units
database        → converted into floating point
frontend        → Number
export          → decimal regenerated from float

The original calculation was deterministic.

The persistence contract was not.

If minor units are the canonical representation, keep them canonical across:

request
→ calculation
→ persistence
→ read-back
→ export

VAT Engine's authenticated transaction calculation records retain the calculated minor-unit amounts together with their calculation context.

That allows the stored result to be inspected later without reconstructing monetary amounts from presentation strings.

Calculation history is not a sales ledger

There is another important boundary.

A calculation does not necessarily represent a completed transaction.

A checkout may calculate VAT repeatedly:

customer changes country
→ calculate

quantity changes
→ calculate

discount applied
→ calculate

shipping option changes
→ calculate

customer leaves

Those calculations can be useful for technical history and review.

They are not necessarily completed sales.

VAT Engine therefore keeps calculation history separate from committed supply events used by its compliance and reporting workflows.

This prevents a calculation API call from being mistaken for a legal or accounting business event.

A practical TypeScript model

Instead of making every monetary value a generic number:

type Price = number;

use an explicit type:

type Money = {
  amountMinor: bigint;
  currency: string;
  scale: number;
};

For example:

const price: Money = {
  amountMinor: 1999n,
  currency: 'EUR',
  scale: 2,
};

Keep the VAT rate separate:

const vatRateBps = 1900;

A calculation result can then have a clear contract:

type VatResult = {
  netAmountMinor: bigint;
  vatAmountMinor: bigint;
  grossAmountMinor: bigint;
  vatRateBps: number;
};

Using bigint here also avoids accidentally exceeding JavaScript's safe integer range in systems that may process very large amounts.

For smaller bounded values, a regular integer number can also be used safely when the range is explicitly constrained.

The important part is that money semantics are deliberate rather than implicit.

Common mistakes

1. Storing prices as floating-point numbers

const price = 19.99;

This makes binary approximation part of the canonical financial representation.

Prefer a fixed-scale money model.

2. Rounding only for display

value.toFixed(2)

is presentation formatting.

Financial rounding affects the actual stored amount and should happen at the defined calculation boundary.

3. Assuming every currency uses two decimals

Do not make:

amount / 100

a universal currency rule.

Currency scale belongs in the money model.

4. Treating an integer as sufficient monetary context

without a currency and scale is not a complete money value.

5. Mixing currencies

1000 EUR minor units
+
1000 USD minor units

is not a valid ordinary addition.

6. Using decimals without defining rounding

Decimal arithmetic can avoid binary approximation, but the application still needs to define what happens when a result exceeds the currency's supported precision.

7. Converting back to floating point during persistence

A safe calculator cannot protect a system that later discards the canonical money representation.

Money arithmetic should be boring

The best financial arithmetic is rarely clever.

It should be predictable.

Before calculating a monetary result, the system should be able to answer:

What currency is this?
What is its minor-unit scale?
What amount is being calculated?
Does the amount include VAT?
Which VAT rate is being used?
Where does rounding happen?
Which rounding rule applies?
What values will be persisted?

When those decisions are explicit, a large class of subtle financial bugs becomes much easier to prevent.

That is why VAT Engine's VAT calculation API uses minor-unit monetary amounts, integer VAT basis points, an explicit price-inclusion flag, and deterministic VAT rounding for its core calculation path.

The result is not sophisticated mathematics.

That is exactly the point.

Financial arithmetic should be simple enough to reproduce, test, store, and explain later.

You can explore the Calculate VAT API, browse available tax classes, inspect calculation history, or try the free VAT calculator.

Note: This article discusses monetary arithmetic and software design. It is not tax, accounting, or legal advice. The correct VAT treatment of a transaction depends on the applicable rules and the actual transaction facts.

VAT-Inclusive vs VAT-Exclusive Pricing: The Math Developers Get Wrong

Vasyl Kyryliuk — Fri, 25 Sep 2026 20:18:49 +0000

VAT calculation often looks like simple percentage arithmetic:

Take the price, multiply it by the VAT rate, and you are done.

That only works when you know exactly what the input price represents.

A €100 net price with 19% VAT and a €100 VAT-inclusive price with 19% VAT are two different calculations.

For developers building checkout, billing, ecommerce, or accounting systems, confusing those two cases is an easy way to create small errors that later propagate into transaction records, reports, reconciliation, and financial exports.

The distinction is simple:

VAT-exclusive price → VAT must be added to the net amount.
VAT-inclusive price → VAT must be extracted from the gross amount.

Those operations do not use the same formula.

Key takeaways

Net × VAT rate works when the input is VAT-exclusive.
Gross × VAT rate is not the correct way to extract VAT from a VAT-inclusive price.
VAT-inclusive extraction uses Gross × Rate / (1 + Rate).
Money should be represented in integer minor units rather than binary floating point.
Rounding needs to be part of the calculation contract.
Correct arithmetic still depends on the correct country, tax class, rate, and transaction date.

VAT-exclusive pricing: add VAT to the net amount

A VAT-exclusive amount represents the price before VAT.

Suppose:

Net amount: €100.00
VAT rate:   19%

VAT is calculated from the net amount:

VAT = Net × Rate
VAT = €100.00 × 0.19
VAT = €19.00

Then:

Gross = Net + VAT
Gross = €100.00 + €19.00
Gross = €119.00

The result is:

Component	Amount
Net	€100.00
VAT	€19.00
Gross	€119.00

This is the straightforward case.

VAT Engine's Calculate VAT API makes the amount basis explicit with price_includes_vat.

For a VAT-exclusive amount:

{
  "country": "DE",
  "currency": "EUR",
  "gross_amount_minor": 10000,
  "price_includes_vat": false,
  "tax_class_id": "standard",
  "transaction_date": "2026-01-28"
}

Here:

"price_includes_vat": false

means that the supplied amount is treated as a net input and VAT is added on top.

The gross_amount_minor field name is retained by the VAT Engine API for compatibility. The actual amount basis is explicitly defined by price_includes_vat.

For a 19% VAT rate, the calculation produces:

{
  "vat_rate_bps": 1900,
  "gross_amount_minor": 11900,
  "net_amount_minor": 10000,
  "vat_amount_minor": 1900
}

VAT Engine represents monetary amounts in minor currency units:

10000 = €100.00
1900  = €19.00
11900 = €119.00

You can also experiment with the same calculation using the VAT calculator.

VAT-inclusive pricing: where the common mistake happens

Now consider a customer-facing price of:

€119.00 including 19% VAT

A tempting calculation is:

€119.00 × 19% = €22.61

But that is wrong.

The 19% rate applies to the net tax base, not to a gross amount that already contains VAT.

The €119 consists of:

Net + VAT = Gross

VAT is already embedded inside the €119.

So instead of adding 19%, we need to extract the VAT portion.

The correct formula for extracting VAT

Let:

G = Gross amount
r = VAT rate as a decimal

The net amount is:

Net = G / (1 + r)

VAT is then:

VAT = G - Net

Or directly:

VAT = G × r / (1 + r)

For €119 including 19% VAT:

VAT = 119 × 0.19 / 1.19
VAT = 19

and:

Net = 119 - 19
Net = 100

So:

Component	Amount
Net	€100.00
VAT	€19.00
Gross	€119.00

The important part is this:

Gross × VAT rate

is not the VAT extraction formula.

Why the formulas are different

With VAT-exclusive pricing:

Net   = 100%
VAT   = 19%
Gross = 119%

The VAT rate is expressed relative to the net amount.

That makes:

VAT = Net × 19%

correct.

With VAT-inclusive pricing, however, the supplied gross amount represents 119% of the net amount.

The VAT portion of gross is therefore:

19 / 119

not:

19 / 100

That is why adding VAT and extracting VAT cannot use the same multiplication.

Make the amount basis explicit

Before performing VAT arithmetic, a system should know:

Does this amount already include VAT?

Do not try to infer that from:

the currency;
the destination country;
the amount itself;
the frontend where the value came from;
whether the transaction appears to be B2C;
how another system happens to display the price.

Make the amount basis part of the API contract or data model.

VAT Engine requires this explicitly:

"price_includes_vat": true

or:

"price_includes_vat": false

When it is true, VAT is extracted from the supplied amount.

When it is false, VAT is added to the supplied amount.

The complete contract is documented in the Calculate VAT API reference.

The same rate can produce different arithmetic

Consider two requests using the same:

country;
currency;
tax class;
transaction date;
VAT rate.

VAT-exclusive input

Input: €100.00 net
Rate:  19%

Result:

Net:   €100.00
VAT:   €19.00
Gross: €119.00

VAT-inclusive input

Input: €100.00 gross
Rate:  19%

Now the result is approximately:

Net:   €84.03
VAT:   €15.97
Gross: €100.00

The rate did not change.

The meaning of the input amount changed.

That is why an API that accepts only:

{
  "amount": 10000,
  "rate": 1900
}

without defining whether the amount is net or gross has an incomplete financial contract.

Do not use floating point for money

Correct formulas are only part of the problem.

Another common mistake is representing money using binary floating-point values.

For example:

const vat = 19.99 * 0.19;

looks harmless.

But many decimal fractions cannot be represented exactly in binary floating point. Small representation errors can then interact with rounding and aggregation.

That becomes particularly uncomfortable when the same values move through:

checkout
→ backend
→ database
→ reporting
→ export
→ accounting system

A safer approach is to represent monetary values using integer minor units.

Instead of:

€119.00

store:

for a currency with two decimal places.

VAT Engine follows this model. The calculation API accepts and returns fields such as:

gross_amount_minor
net_amount_minor
vat_amount_minor

That means the monetary representation remains integer-based throughout the core calculation path.

VAT rates can use integers too

VAT Engine represents rates using basis points.

For example:

19.00% = 1900 basis points
20.00% = 2000 basis points
7.00%  = 700 basis points

A response therefore contains:

{
  "vat_rate_bps": 1900
}

instead of requiring calculation code to depend on a floating-point 0.19.

This gives the calculation contract explicit integer representations for both:

monetary amounts;
VAT rates.

Rounding is part of the financial contract

Even with the correct formula, VAT can produce fractions smaller than the currency's minor unit.

Consider:

Gross: €9.99
VAT rate: 19%

VAT extraction gives:

VAT = 9.99 × 0.19 / 1.19

The mathematical result contains more precision than EUR can represent.

Eventually it needs to become cents.

With deterministic rounding, a system can resolve this to:

Net:   €8.39
VAT:   €1.60
Gross: €9.99

The important question is not whether rounding happens.

It must happen.

The important question is where and how.

A risky architecture might have:

checkout      → rounding rule A
backend       → rounding rule B
report export → rounding rule C

Each individual result may look reasonable while totals disagree by one or more minor units.

A financial calculation API should therefore make rounding behavior part of a stable calculation contract.

VAT Engine performs its core VAT arithmetic using integer amounts and deterministic rounding rather than delegating that decision to different callers.

Correct arithmetic does not determine the correct VAT rate

There is another important separation.

Even perfectly implemented VAT arithmetic cannot answer:

Which rate applies to this product and transaction?

The arithmetic needs a rate as an input.

Rate selection may depend on factors such as:

destination country;
product classification;
transaction date;
applicable tax treatment.

That is why VAT Engine accepts a tax_class_id.

For example:

{
  "tax_class_id": "standard"
}

Available classifications can be inspected through the public Tax Classes API.

A more realistic VAT calculation flow is therefore:

Amount
+ amount basis
+ country
+ tax class
+ transaction date
↓
Rate selection
↓
VAT arithmetic
↓
Net + VAT + Gross

not simply:

Amount × percentage

The transaction date belongs in the calculation

VAT is also time-dependent.

Rates and tax treatment can change.

A calculation for an older transaction should therefore not silently substitute today's rate simply because today's rate is easier to retrieve.

VAT Engine accepts an explicit:

{
  "transaction_date": "2026-01-28"
}

and uses the requested date as part of rate selection.

The underlying rate contract is described in the VAT Rates API documentation.

There is an important evidence distinction here.

Older recorded lookup windows do not automatically prove the same thing as a reviewed, source-supported legal applicability interval.

VAT Engine therefore distinguishes evidence states rather than assuming that any historical numeric match has identical provenance.

That matters when a calculation is reviewed later.

Preserve calculation context, not just the final percentage

Imagine seeing this six months later:

VAT rate: 19%
VAT: €19.00

You still do not know enough to understand how the result was produced.

Useful calculation context includes:

country;
currency;
tax class;
transaction date;
input amount;
whether the input included VAT;
selected rate;
net amount;
VAT amount;
gross amount;
calculation identity;
rate evidence where available;
calculation version where available.

VAT Engine stores authenticated calculation history and exposes it through the Transactions API.

This is deliberately more useful than retaining only:

rate = 19%

because the question during a later review is usually not:

What is the VAT rate today?

It is:

What inputs and calculation context produced this particular result?

Keep calculation history separate from the business event

There is also an architectural distinction worth preserving.

Calling a tax calculator and recording a real sale are not necessarily the same event.

A checkout might calculate VAT several times before the customer actually pays:

cart updated
→ calculate

shipping country changed
→ calculate again

coupon applied
→ calculate again

customer pays
→ committed sale

Treating every calculation request as a legal or reporting transaction would create a very different problem.

VAT Engine therefore keeps calculation records separate from committed supply data used by its compliance and reporting workflows.

This separation keeps an API calculation useful for debugging and audit context without pretending that every calculation represents a completed sale.

A practical implementation pattern

For an ecommerce or SaaS application, keep the calculation boundary explicit.

For example:

type VatCalculationInput = {
  country: string;
  currency: string;
  amountMinor: number;
  priceIncludesVat: boolean;
  taxClassId: string;
  transactionDate: string;
};

The result can then be handled as structured financial data:

type VatCalculationResult = {
  rateBps: number;
  netAmountMinor: number;
  vatAmountMinor: number;
  grossAmountMinor: number;
};

The important property is that the system never has to guess later whether:

meant:

€100.00 net

or:

€100.00 gross

That decision was explicit at the calculation boundary.

Common VAT calculation mistakes

1. Multiplying a VAT-inclusive price directly by the VAT rate

Wrong:

VAT = Gross × Rate

Correct:

VAT = Gross × Rate / (1 + Rate)

2. Inferring whether the input includes VAT

Make the amount basis explicit.

{
  "price_includes_vat": true
}

is much safer than relying on assumptions somewhere else in the application.

3. Using floating point for monetary values

Prefer integer minor units with a known currency scale.

€19.99 → 1999

rather than treating 19.99 as a binary floating-point financial value.

4. Implementing different rounding rules in different services

VAT arithmetic should have one deterministic rounding contract.

5. Treating the VAT rate as the entire tax decision

Correct arithmetic still depends on selecting the relevant country, tax class, rate data, and transaction date.

6. Saving only the final VAT amount

Keep enough context to understand how the result was produced.

The Transactions API exists for exactly this kind of calculation history.

The math should be boring

VAT arithmetic is not the most complicated part of VAT software.

But it should be predictable.

Before calculation starts, a system should be able to answer:

What amount was supplied?
Does it already include VAT?
Which currency is it in?
Which country applies?
Which tax class is being used?
What is the transaction date?
Which rate was selected?
How are fractional minor units rounded?

Once those inputs are explicit, the arithmetic becomes deterministic.

That is the approach behind the VAT Engine calculation API: explicit price basis, integer minor-unit amounts, tax-class-aware rate selection, transaction-date context, and structured net, VAT, and gross outputs.

You can test the arithmetic interactively with the free VAT calculator, browse the available tax classes, or inspect the full Calculate VAT API reference.

Note: This article explains VAT calculation mechanics and software design. It is not tax or legal advice. The correct tax treatment of a transaction depends on its actual facts and the applicable rules.

EU VAT for SaaS & Subscription Billing

Vasyl Kyryliuk — Fri, 18 Sep 2026 19:34:08 +0000

EU VAT for SaaS & Subscription Billing

Selling SaaS subscriptions across the EU turns VAT into more than a simple percentage calculation.

The billing flow may need to consider the customer's country, product tax treatment, whether the displayed price already includes VAT, the transaction date, refunds or corrections, and the information finance teams will need later for reporting.

VAT Engine is designed to keep those pieces connected instead of forcing every SaaS product to maintain its own VAT tables and tax logic.

EU VAT becomes part of the billing architecture

A typical SaaS billing system is already responsible for subscriptions, renewals, invoices, payments, cancellations, and refunds.

EU VAT adds another layer of decisions.

For a transaction, your application may need to know:

which country the sale belongs to
which tax class applies to the product
which VAT rate should be used
whether the amount is VAT-inclusive or VAT-exclusive
which transaction date should be considered
and what context should be retained for later review

A billing system that stores only something like VAT rate: 19% loses much of the information needed to understand that result later.

VAT Engine separates VAT calculation from the rest of the billing implementation while keeping the relevant transaction context available.

Calculate VAT from structured transaction data

A SaaS application can send transaction information to the VAT Engine REST API and receive a structured VAT calculation result.

Typical calculation inputs include:

destination country
product tax class
transaction amount
currency
VAT-inclusive or VAT-exclusive pricing
transaction date

This allows your own application to remain responsible for subscriptions and payments while VAT-specific rate resolution and calculation logic is handled separately.

A simplified flow looks like:

**Customer → SaaS billing flow → VAT Engine → VAT result → Payment → Transaction record**

The API can be used from a custom checkout, subscription backend, billing service, or internal application.

Handle VAT-inclusive and VAT-exclusive pricing correctly

The same VAT rate produces different arithmetic depending on how a price is represented.

If a subscription costs €100 before VAT and the applicable rate is 20%, VAT is added to the net amount.

The result is:

Net: €100
VAT: €20
Gross: €120

But if the customer-facing €100 price already includes 20% VAT, the VAT portion is not €20.

It must be extracted from the gross amount.

VAT Engine makes the pricing basis explicit so the calling application does not have to infer whether VAT should be added or extracted.

This can be particularly useful when the same SaaS product serves different customer types, markets, or pricing models.

Use the transaction date when working with older records

Subscription systems do not only process transactions created today.

Teams frequently need to work with:

refunds
corrections
imported historical transactions
billing migrations
reconciliation
audit or accountant reviews

Using today's VAT rate for every historical operation can produce a result that does not match the original transaction.

VAT Engine supports date-aware lookup using recorded rate windows where historical coverage is available.

This means the transaction date can participate in VAT rate resolution instead of the system automatically assuming the currently active rate.

Recorded lookup windows are kept distinct from a guarantee of legally verified historical applicability. Stronger source provenance and deterministic historical replay are areas being developed further.

Keep enough context to understand the result later

For financial systems, returning the correct number is only part of the job.

Imagine someone reviews a subscription transaction several months later and asks:

Why was this VAT treatment applied?

A percentage alone does not answer that question.

A useful transaction record can retain context such as:

country
product tax class
transaction date
original amount
currency
VAT-inclusive or VAT-exclusive pricing basis
VAT result
source identity
calculation timestamps
available rate context

Keeping this information together makes later reconciliation, refunds, reporting, and accountant review easier than reconstructing the original VAT decision from several disconnected systems.

Support renewals and recurring billing

Recurring subscription billing creates a new transaction each time a customer renews.

Instead of permanently hard-coding VAT rates into a billing service, the application can resolve VAT using the transaction context relevant to each renewal.

This provides a cleaner separation between:

subscription logic
payment processing
VAT calculation
transaction records
compliance preparation

It also means VAT-related logic can evolve without requiring every billing workflow to maintain its own copy of tax data.

Handle refunds and corrections with historical context

Refunds are one of the places where transaction context becomes particularly important.

A refund issued today may relate to a subscription transaction created months earlier.

The original:

transaction date
country
product classification
price basis
and recorded VAT context

can all matter when reviewing how the refund should relate to the original sale.

Keeping the original transaction record available is generally more useful than attempting to reconstruct everything from today's configuration.

Prepare transaction data for OSS workflows

For B2C SaaS sales across EU countries, VAT calculation is only one part of the operational process.

Finance or accounting teams eventually need an organized set of transactions that can be reviewed by reporting period, country, and source.

VAT Engine provides compliance-oriented workflows around committed transaction records, including support for:

OSS/IOSS preparation
transaction review
accountant-oriented exports
multi-source reporting
reconciliation

VAT Engine does not submit VAT returns on behalf of the business and does not replace professional tax advice.

The purpose is to make the underlying VAT data easier to organize, inspect, and prepare for downstream compliance work.

Keep multiple billing sources organized

As a SaaS business grows, revenue may start arriving through more than one system.

For example:

the main subscription checkout
an additional storefront
marketplace sales
imported historical billing records
internal payment flows
connected commerce platforms

VAT Engine uses source profiles to keep transactions attributable to the system or sales channel they came from.

That provides a consistent source model for reporting and reconciliation instead of requiring separate tax-data structures for every integration.

Use SME threshold data alongside VAT workflows

VAT obligations can also depend on the circumstances of the business itself.

VAT Engine provides EU SME VAT threshold data that can be used alongside other compliance workflows, including values represented in EUR and relevant national currencies where supported.

Keeping threshold information accessible through the same platform reduces the need to maintain another independent dataset inside the application.

Where VAT Engine fits into a SaaS stack

VAT Engine is not intended to replace your payment processor or subscription-management platform.

Your existing systems can continue handling:

subscriptions
payment methods
invoices
payment collection
cancellations
customer accounts

VAT Engine provides the VAT-specific layer around those workflows:

EU VAT calculation
VAT rate resolution
product tax classes
date-aware rate lookup
transaction records
source profiles
SME VAT threshold data
OSS/IOSS preparation workflows

The REST API can be integrated into an existing architecture without requiring VAT Engine to become the system responsible for the entire billing lifecycle.

Example: a new B2C subscription

Consider a SaaS customer purchasing a subscription from another EU country.

The billing application collects the required transaction context and sends the relevant data to VAT Engine.

VAT Engine resolves the recorded VAT rate and calculates the VAT amounts.

The billing application can then use the result when presenting or processing the transaction.

After the sale, the transaction context can be retained for reporting and later review.

Example: a subscription renewal

When the subscription renews, the billing service creates a new transaction.

The current transaction context can be evaluated again rather than assuming that every renewal must reuse tax data stored when the customer originally subscribed.

This keeps recurring billing logic separate from VAT rate maintenance.

Example: refunding an older subscription

A refund may relate to a transaction that occurred during an earlier reporting period.

The original transaction date and recorded VAT context provide a better basis for reviewing the refund than simply applying today's rate.

Date-aware lookup and retained transaction records help support that workflow.

Example: migrating historical billing data

A SaaS company moving from another billing architecture may need to import older transactions.

Historical records can be organized using consistent source profiles, tax classes, countries, dates, and recorded VAT context.

That creates a more structured foundation for reconciliation and future reporting.

Who this use case is for

VAT Engine can be useful for:

SaaS businesses selling subscriptions across EU countries
developers building custom subscription billing systems
B2C digital service providers
finance teams preparing OSS data
platforms that need VAT calculation through an API
teams reconciling or migrating historical billing data

Keep VAT logic outside your billing code

A SaaS billing system already has enough responsibilities.

Maintaining VAT rates, tax classifications, historical rate context, and compliance-oriented transaction records does not necessarily need to become another permanent part of that codebase.

VAT Engine provides a dedicated EU VAT layer that can be integrated through the API while keeping the transaction context needed for later review.

**VAT Engine is currently available in free alpha. No payment method is required.**

Why a VAT API Needs More Than a Rate Lookup

Vasyl Kyryliuk — Fri, 18 Sep 2026 19:27:11 +0000

When developers first add VAT to an ecommerce or SaaS product, the problem can look surprisingly small:

Find the customer's country.
Look up the VAT rate.
Multiply the price by that percentage.
Done.

That works until the first real edge cases arrive.

What product was sold? Was the displayed price VAT-inclusive? Which country actually has taxing rights? Was this transaction created today or six months ago? Is it a refund of an older sale? Which rate was used when the original transaction happened?

At that point, a VAT integration stops being a percentage lookup and starts becoming a data and decision-traceability problem.

A country does not have one VAT rate

A basic VAT table might look like this:

{
  "DE": 19,
  "FR": 20,
  "IT": 22
}

Useful, but incomplete.

EU member states can apply standard, reduced, zero, and other rates depending on the type of supply. Books, accommodation, food, pharmaceuticals, and other categories may receive different treatment.

So the more useful question is not:

What is Germany's VAT rate?

It is closer to:

Which VAT rate applies in Germany to this product category for this transaction?

That means a useful API needs product tax context, not only a country code.

The transaction date matters

Using today's rate for every calculation creates another problem.

Imagine processing:

a refund for an order placed last year,
an imported historical transaction,
an audit of an older sale,
a correction to previously recorded data.

The rate that is active today is not necessarily the rate that was used for the original transaction.

A VAT API therefore benefits from accepting an explicit transaction or supply date:

{
  "country": "DE",
  "tax_class": "standard",
  "date": "2026-01-15"
}

The response can then identify the recorded rate window used for that lookup.

One important distinction: a recorded historical window and a legally verified effective date are not automatically the same thing.

If the underlying source data does not prove legal applicability for a historical period, the API should make that limitation explicit rather than pretending to know more than it does.

Failing clearly is much safer than silently returning a convenient number.

VAT-inclusive and VAT-exclusive prices are different calculations

There is also a basic arithmetic distinction that often gets buried inside tax code.

If €100 is VAT-exclusive at 20%, the total is:

Net:   €100
VAT:    €20
Gross: €120

But if €100 already includes 20% VAT, the VAT portion is not €20.

It is:

VAT = 100 - (100 / 1.20)

which is approximately €16.67.

An API should therefore require the caller to make the price basis explicit instead of guessing.

For financial calculations, I also prefer integer minor units rather than floating-point money:

{
  "amount": 10000,
  "currency": "EUR",
  "price_includes_vat": true
}

Here 10000 represents €100.00.

That avoids a whole class of floating-point rounding problems.

Returning the correct number is only half the job

Suppose an API returns this:

{
  "vat_rate": 0.19,
  "vat_amount": 1597
}

Six months later, someone asks:

Why did this transaction use 19% VAT?

The number alone cannot answer that.

A more useful calculation record may also retain:

country
product tax class
transaction date
VAT-inclusive/exclusive basis
input amount
rate used
source/store identity
calculation timestamp
relevant rate-data version or provenance where available

This turns the VAT result from a disposable API response into something that can actually be reviewed later.

Source identity matters in multi-store commerce

The problem becomes more visible when a business has several sales channels.

An order might come from:

Shopify
a custom checkout
another marketplace
an imported CSV
an internal billing system

For reporting purposes, simply storing "transaction 12345" may not be enough.

The system also needs to know which source owns that transaction.

That is why I think source profiles are useful as a first-class concept rather than just another string attached to an order.

They make it possible to group and reconcile records without losing where those records originally came from.

Compliance workflows need committed data

There is another important boundary between a calculator and a compliance system.

Someone calling a VAT calculator ten times should not automatically create ten filing records.

Reporting workflows need a defined population of committed business transactions, not every exploratory API request ever made.

That separation becomes important for OSS/IOSS preparation, accountant review, exports, and reconciliation.

Calculation and compliance can share the same data model, but they should not be treated as the same action.

What I am building around these ideas

These problems are what pushed VAT Engine beyond a simple VAT-rate endpoint.

The current direction combines:

EU VAT calculation
TEDB-backed rate data
product tax classes
date-aware rate lookup
transaction records
source profiles
SME VAT threshold data
OSS/IOSS preparation workflows
ecommerce integrations

There is still more work to do, particularly around stronger rate provenance, immutable source evidence, and deterministic replay.

The long-term goal is not just to answer:

What VAT rate should I use?

It is to make it possible to answer:

What information produced this VAT result, and can I understand that decision later?

For financial infrastructure, I think that second question is ultimately the more interesting one.

What Building a Shopify Integration Taught Me About Trusting External APIs

Vasyl Kyryliuk — Sat, 01 Aug 2026 17:31:28 +0000

Building a Shopify integration looks straightforward at first:

Authenticate the store.
Request orders.
Transform the response.
Store the result.

The difficult part begins when the integration needs to become reliable enough for production.

While building the Shopify integration for VAT Engine, I learned that consuming an external API is not only about parsing its response. It is about defining exactly what you trust, what you verify, and what must fail closed.

External APIs are contracts, not just endpoints

A GraphQL query can continue returning a successful response while the meaning of the returned data changes around it.

An integration depends on more than the endpoint itself:

API version
requested fields
required access scopes
pagination behaviour
nullable fields
partial GraphQL errors
protected customer-data permissions
webhook topics
authentication requirements
assumptions made during transformation

That entire combination is the real contract.

If any part changes silently, the integration may continue running while producing incomplete or misleading results.

For a tax-related system, that is worse than a visible failure.

Make every dependency explicit

We created a source-contract matrix for the Shopify integration.

For every operation, it records information such as:

the GraphQL operation name
the Shopify API version
required scopes
fields used by the application
validation gates
evidence limitations
associated tests
downstream consumers

This turns undocumented assumptions into something reviewable.

Instead of saying:

The order query gives us everything we need.

The system has to answer more precise questions:

Which order fields are required?
Which fields are optional?
What happens when Shopify returns partial GraphQL errors?
Can a missing duties field be interpreted as zero?
Which evidence is sufficient to classify a transaction?
Which missing evidence must send the order to manual review?

Missing data is not the same as zero

This was one of the most important design rules.

Imagine that Shopify returns an order but cannot return duties or additional-fee information for part of the query.

There are at least three possible meanings:

The amount is genuinely zero.
The field is unavailable.
Shopify returned a partial error.

Treating all three cases as zero creates false confidence.

A safer model distinguishes between:

confirmed_zero
known_value
unavailable
conflicting
needs_review

This pattern is useful far beyond VAT.

It applies to payments, inventory, shipping, identity verification, analytics, and almost any integration where incomplete data can affect a business decision.

Validate the contract in CI

Documentation alone eventually becomes outdated.

The next step was making the contract machine-readable and validating it during CI.

The validation checks for problems such as:

an operation missing from the inventory
an undocumented validation gate
malformed contract data
unsafe file references
claims that exceed the available evidence
drift between queries, tests, and documentation

The goal is not to prove that an external API will never change.

The goal is to make our own assumptions visible and make accidental drift difficult.

Authorization must be tested as an attacker would use it

A valid Shopify session token is only the beginning.

An embedded application also needs to defend against:

forged tokens
expired tokens
tokens that are not valid yet
wrong audience values
tokens issued for another shop
cross-tenant resource access
resource enumeration
mutation replay
oversized request bodies
unsafe proxy destinations
sensitive information leaking into logs

Many authorization tests verify only the successful path:

valid user + valid token + owned resource = success

The more valuable tests cover combinations that must fail:

valid user + valid token + another store's resource = rejected
valid token + wrong audience = rejected
expired token + valid resource = rejected
replayed mutation = rejected

Multi-tenant security is not complete until ownership is checked at every relevant boundary.

Webhooks require a different trust model

Webhook endpoints are public by design.

That means their processing order matters.

A safer flow is:

Read the bounded raw request body.
Verify the HMAC signature.
Reject invalid requests.
Parse the payload.
Resolve the relevant integration.
Apply idempotency.
Persist minimal required information.
Queue expensive processing.

Parsing or resolving tenant data before signature verification creates unnecessary exposure.

Webhook retries also mean that duplicate delivery is normal, not exceptional. Idempotency must therefore be part of the design from the beginning.

Fail closed, but preserve recoverability

Failing closed does not have to mean permanently losing the transaction.

When evidence is incomplete, the system can:

retain a minimal diagnostic record
place the transaction into a review queue
allow a controlled replay
run a reconciliation job later
preserve the reason why automated processing stopped

This provides a useful balance:

do not silently accept uncertain data
do not discard potentially recoverable data
do not hide the decision from operators

What I would do earlier next time

If I were starting another integration today, I would define these before implementing the first production query:

A machine-readable inventory of external operations.
Explicit trust boundaries for each response field.
A distinction between zero, missing, unavailable, and conflicting data.
Cross-tenant authorization abuse tests.
Webhook idempotency and reconciliation.
Evidence-based review states instead of optimistic defaults.
CI checks that detect contract drift.

These decisions are much cheaper to make early than after customers depend on the integration.

Final thought

A production integration is not simply a connector between two APIs.

It is a boundary between two systems with different data models, security assumptions, failure modes, and release cycles.

The safest approach is to treat every external value as evidence that must be verified, classified, and preserved, not merely as JSON that successfully parsed.

I am applying these principles while building the Shopify integration for VAT Engine, an EU VAT compliance platform. Shopify is the first native commerce connector, with additional ecommerce integrations planned on the same shared ingestion model.

I would be interested to hear how other developers prevent external API contract drift in production integrations.

DEV Community: VAT Engine

What Should a VAT Calculation Record Actually Contain?

The result is only one part of the record

1. Start with a stable calculation identity

2. Preserve the monetary values explicitly

3. Record the rate — but not just the rate

4. Transaction date is part of the tax context

5. Preserve the tax classification

6. Preserve whether the input included VAT

7. Rate provenance should be a first-class field

8. Record which calculation logic produced the result

9. Source attribution helps explain where the calculation came from

10. Evidence status should not be reduced to a boolean

11. Replay eligibility is different from evidence capture

12. Idempotency belongs near the calculation boundary

13. A calculation record is not the same as a sales ledger

14. A record should preserve facts, not force conclusions

What I would consider the minimum useful record

What not to store as your only record

Only the final VAT amount

Only the rate

A mutable reference to "current rate"

Money as floating point

A generic verified: true

The useful question is not "what did we calculate?"

Why Money Calculations Should Not Use Floating Point

Key takeaways

The classic floating-point example

Money is discrete at a defined currency precision

Not every currency has two decimal places

Floating point mixes representation with rounding

Minor units make the monetary input exact

VAT rates can be represented as integers too

VAT-inclusive pricing still requires fractional arithmetic

Rounding is part of the financial contract

Formatting is not calculation

An integer alone is not money

Exchange rates are a separate numeric domain

Decimal libraries are also a valid solution

Keep the amount basis explicit

Exact money does not automatically mean correct VAT

Persist the canonical monetary representation

Calculation history is not a sales ledger

A practical TypeScript model

Common mistakes

1. Storing prices as floating-point numbers

2. Rounding only for display

3. Assuming every currency uses two decimals

4. Treating an integer as sufficient monetary context

5. Mixing currencies

6. Using decimals without defining rounding

7. Converting back to floating point during persistence

Money arithmetic should be boring

VAT-Inclusive vs VAT-Exclusive Pricing: The Math Developers Get Wrong

Key takeaways

VAT-exclusive pricing: add VAT to the net amount

VAT-inclusive pricing: where the common mistake happens

The correct formula for extracting VAT

Why the formulas are different

Make the amount basis explicit

The same rate can produce different arithmetic

VAT-exclusive input

VAT-inclusive input

Do not use floating point for money

VAT rates can use integers too

Rounding is part of the financial contract

Correct arithmetic does not determine the correct VAT rate

The transaction date belongs in the calculation

Preserve calculation context, not just the final percentage

Keep calculation history separate from the business event

A practical implementation pattern

Common VAT calculation mistakes

1. Multiplying a VAT-inclusive price directly by the VAT rate

2. Inferring whether the input includes VAT

3. Using floating point for monetary values

4. Implementing different rounding rules in different services

5. Treating the VAT rate as the entire tax decision

6. Saving only the final VAT amount

The math should be boring

EU VAT for SaaS & Subscription Billing

A generic `verified: true`