# How VAT Calculation Provenance Makes Results Explainable

A VAT calculation can be numerically correct and still be difficult to trust.

Imagine an API returns:

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

The arithmetic looks straightforward.

But if someone reviews that result six months later, they may ask:

- Where did the 19% rate come from?
- Which rate dataset was used?
- Which mapping participated in the decision?
- Which version of the calculator produced the amounts?
- What evidence was actually captured?
- Can the original result be reproduced exactly?
- Has the underlying rate data changed since then?

The final number alone cannot answer those questions.

That is what **calculation provenance** is for.

Provenance connects a financial result to the data, versions, mappings, and calculation contract that produced it.

For a VAT API, that can make the difference between:

```text
VAT = €19.00
```

and:

```text
VAT = €19.00
because this rate evidence, mapping context, date, and calculation contract produced it
```

The second result is much easier to explain.

## A result and its provenance are different things

The result tells you **what was calculated**.

Provenance helps explain **how the system arrived there**.

A VAT result might contain:

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

Its provenance can describe things such as:

```text
rate source
rate data version
mapping version
effective date
calculation version
evidence status
source references
replay status
```

These serve different purposes.

The calculation output is useful for checkout, invoices, reporting, and reconciliation.

The provenance becomes useful when someone needs to understand or review the result later.

## Why the percentage alone is not enough

Consider two calculations that both use:

```text
19%
```

They may look identical numerically.

But they could have been selected through completely different evidence paths.

For example:

```text
Calculation A:
country = DE
tax class = standard
reviewed rate evidence = A

Calculation B:
country = DE
tax class = standard
legacy recorded window = B
```

Both might produce:

```text
1900 basis points
```

That does not mean they have the same provenance.

A matching percentage does not prove:

- the same source was used,
- the same historical applicability was established,
- the same mapping was used,
- or the same evidence quality existed.

Numeric equality is not provenance.

## Start with rate provenance

VAT Engine separates the numeric VAT rate from the evidence describing where that rate came from.

A response can include a structure such as:

```json
{
  "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 is not the exact JSON shape.

It is that the API does not pretend:

```text
rate = 19%
```

is the complete explanation.

Instead, the result can carry information about the evidence state behind that rate.

## Evidence status should be explicit

A common design mistake is to reduce evidence to:

```json
{
  "verified": true
}
```

That usually hides too much.

Historical and financial data often has more than two meaningful states.

For rate evidence, VAT Engine distinguishes states such as:

```text
verified
legacy_unverifiable
unavailable
```

These communicate different things.

### `verified`

The required reviewed rate evidence is available for that recorded path.

### `legacy_unverifiable`

The historical record exists, but the evidence needed to prove it to the current standard was not captured.

### `unavailable`

The required evidence cannot currently be established.

This is more informative than silently converting uncertainty into certainty.

## Legacy records should stay legacy

Suppose an old VAT calculation used a recorded rate of:

```text
19%
```

Later, a reviewed source also contains:

```text
19%
```

It can be tempting to mark the old record as verified.

But the old record may not contain:

- the original reviewed source version,
- source-supported applicability evidence,
- the original mapping digest,
- or the source references needed by the newer evidence model.

So the safer rule is:

> Do not retroactively upgrade provenance merely because the numbers match.

VAT Engine keeps that distinction explicit.

Older records can remain:

```text
legacy_unverifiable
```

instead of being assigned stronger provenance by inference.

That preserves what the system actually knows.

## Historical rate windows need careful interpretation

This matters especially for historical VAT data.

A recorded lookup window may describe:

```text
when the system observed or applied a rate
```

while legal applicability asks:

```text
when the rate was actually applicable according to the authoritative source
```

Those are not automatically the same thing.

Older imported or live-recorded windows can reflect observation or application time.

Where approved source-supported coverage exists, the evidence can be stronger.

But a legacy recorded window should not suddenly be described as a legally verified applicability interval.

That distinction is part of provenance.

I covered this temporal boundary in more detail here:

[Current VAT Rate vs Transaction-Date VAT Rate: Why the Difference Matters](https://vat-engine.app/blog/current-vat-rate-vs-transaction-date-vat-rate)

## Mapping provenance matters too

A VAT rate is usually not selected from country alone.

The system may need to resolve something like:

```text
product or classification context
→ mapping
→ tax treatment
→ rate
```

Mappings can change over time.

If a mapping changes in July, the current mapping does not necessarily explain why a January calculation produced its result.

That is why a calculation record can benefit from preserving mapping identity.

VAT Engine can retain fields such as:

```text
mapping_version
mapping digest
```

alongside rate evidence.

This lets a later review distinguish:

```text
the mapping used then
```

from:

```text
the mapping configured now
```

## Calculation provenance is separate from rate provenance

Even if the selected rate is fully understood, the arithmetic still has its own provenance.

A financial calculation can depend on:

- rounding rules,
- inclusive vs exclusive pricing,
- currency scale,
- validation behavior,
- calculator version.

VAT Engine therefore exposes calculation provenance separately.

For example:

```json
{
  "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": "...",
    "ownership": "tenant_owned",
    "evidence_status": "captured",
    "replay_status": "ineligible"
  }
}
```

This answers a different question:

> Which registered calculation contract produced these amounts?

That remains useful even if the VAT rate itself has not changed.

## Why calculator versions matter

Financial software evolves.

Imagine that a later calculator version changes:

```text
rounding behavior
currency-scale handling
validation rules
```

If an old transaction is reviewed after that change, running today's code may not be enough to explain yesterday's result.

Without calculation provenance, the investigation becomes:

```text
Why does the API behave differently now?
```

With provenance, the question becomes:

```text
Which calculation contract produced the original result?
```

That is much more precise.

## An execution digest is not a source-code hash

Technical provenance should also be described carefully.

VAT Engine exposes an:

```text
execution_digest
```

That is not presented as:

```text
a hash of the compiled binary
```

or:

```text
cryptographic proof of every runtime instruction
```

It identifies the registered calculation-version contract.

VAT Engine can also retain an algorithm manifest version and digest that bind the defined arithmetic, validation, currency-scale, rounding, and frozen-fixture contract.

That gives the result a stable technical identity without claiming more than the evidence actually proves.

## Provenance should survive software updates

Your software will change.

Your rate imports will change.

Your mappings may change.

Your validation rules may change.

A historical calculation should not require today's mutable configuration to explain yesterday's result.

Instead, the record should preserve enough information to say:

```text
this result came from this request
using this rate evidence
using this mapping context
using this calculation contract
```

That makes historical behavior less dependent on current state.

## Provenance improves debugging

Imagine a customer reports:

> Your API charged 19% VAT, but I expected 7%.

Without provenance, the investigation might require reconstructing:

- which rate data was active,
- which tax class or mapping was selected,
- which transaction date was used,
- which calculator behavior was running.

With provenance, much of that context can already be attached to the calculation record.

A review becomes more structured:

```text
1. Retrieve the calculation.
2. Inspect the transaction date.
3. Inspect the selected tax context.
4. Inspect the rate evidence.
5. Inspect the mapping version.
6. Inspect the calculator version.
7. Compare the recorded assumptions with the expected business facts.
```

This does not automatically prove that the tax treatment was legally correct.

It does make the technical decision much easier to explain.

## Provenance improves reconciliation too

Reconciliation often means comparing two systems.

For example:

```text
VAT Engine
vs
Shopify

VAT Engine
vs
a billing platform

VAT Engine
vs
an accounting export
```

If both systems show:

```text
VAT = €19.00
```

there may be nothing to investigate.

But if one says:

```text
€19.00
```

and the other says:

```text
€7.00
```

the useful question is not just:

> Which number is correct?

You also need to know:

> Which assumptions produced each number?

That may include:

- jurisdiction,
- product classification,
- transaction date,
- rate source,
- amount basis,
- rounding behavior.

Provenance turns reconciliation from a number comparison into a decision comparison.

## Source references make evidence inspectable

A useful provenance model can include bounded references to the evidence behind a decision.

For reviewed rate paths, this can include public-safe references associated with:

```text
rate versions
source snapshots
rate rows
mapping evidence
```

The public response does not need to expose every internal database object.

It needs enough stable, safe references to explain what the system relied on.

This keeps the API useful without leaking internal implementation details.

## Provenance is not the same as logging

Logging and provenance overlap, but they are not interchangeable.

A log might say:

```text
2026-01-28 10:03:12 calculated VAT for DE
```

That is operational telemetry.

Provenance belongs to the calculation record itself.

It answers questions such as:

```text
Which rate source?
Which version?
Which mapping?
Which calculator?
Which evidence status?
```

Logs can be rotated.

Trace IDs can disappear.

Infrastructure can change.

The stored calculation should still retain the information needed to explain its own result.

## Provenance is not a committed sale either

Another boundary matters.

A calculation with useful provenance is still a calculation.

It does not automatically mean:

```text
a sale happened
```

or:

```text
this record is a committed accounting event
```

VAT Engine's Transactions API exposes VAT calculation history and evidence.

Calling:

```text
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 use committed supply data.

Calculation provenance explains the API calculation.

It does not manufacture a business event.

## Provenance and replay are related, but not identical

Another useful distinction is between:

```text
evidence captured
```

and:

```text
exactly replayable
```

A calculation may retain useful evidence without retaining everything required for exact replay.

VAT Engine exposes that boundary through:

```text
replay_status
```

Possible states include:

```text
not_supported
ineligible
available
```

Only calculations reporting:

```text
replay_status: available
```

can use the exact replay endpoint.

That prevents the API from claiming reproducibility where the required sealed evidence does not exist.

## Exact replay makes provenance testable

For eligible calculations:

```text
POST /v1/transactions/{id}/replay
```

uses the recorded:

```text
original canonical request
+ sealed historical rate evidence
+ registered calculator version
```

A successful replay returns:

```text
exact_match: true
```

with the reproduced amounts.

This makes provenance stronger than descriptive metadata alone.

The system can test whether the recorded evidence reproduces the stored result.

But replay still has strict boundaries.

The caller cannot choose:

```text
another rate-data version
another calculator version
```

because that would describe a different calculation, not a replay of the original one.

## A useful provenance record answers several layers of "why"

When someone asks:

> Why is the VAT €19?

there are several possible meanings.

### Arithmetic

```text
Why is €19 the mathematical VAT amount?
```

Answer:

```text
because €100 net at 19% produces €19 VAT
```

### Rate selection

```text
Why was 19% selected?
```

Answer:

```text
because this recorded rate evidence was selected for this context and date
```

### Mapping

```text
Why did this product or classification use that treatment?
```

Answer:

```text
because this recorded mapping context participated in the decision
```

### Reproducibility

```text
Can we reproduce the original result?
```

Answer:

```text
only when the required sealed evidence exists and replay_status is available
```

A single `vat_rate` field cannot answer all of those questions.

Provenance gives each one a place in the model.

## What I would preserve in a provenance-aware VAT API

At minimum, I would separate the result from the evidence explaining it.

A useful structure might preserve:

```text
Calculation identity

Input context:
- country / jurisdiction
- currency
- amount basis
- tax classification
- transaction date

Result:
- net amount
- VAT amount
- gross amount
- selected VAT rate

Rate provenance:
- evidence status
- rate source
- rate data version
- effective date
- rate-row identity
- source references where available

Mapping provenance:
- mapping version
- mapping digest or stable identity

Calculation provenance:
- calculation version
- execution identity
- algorithm manifest identity
- calculation evidence state

Reproducibility:
- replay status
```

Not every financial API needs exactly these field names.

The architectural point is the separation.

## What provenance should not do

Provenance is useful because it describes what the system actually knows.

It should not silently invent stronger claims.

Avoid patterns such as:

### Upgrading old history because the number matches

```text
old rate = 19%
reviewed rate = 19%

therefore old history is verified
```

That does not follow.

### Treating a recorded window as automatic legal applicability

Recorded/imported windows can reflect system history rather than authoritative legal dates.

### Calling evidence capture exact replay

Evidence can be useful without being complete enough for replay.

### Treating calculation history as a committed sale

A calculator call does not prove that a business transaction occurred.

### Hiding uncertainty

`legacy_unverifiable` is more informative than pretending old evidence is equivalent to newly reviewed evidence.

## Explainability is mostly about preserving context

A financial API does not become explainable because it adds a field called:

```text
reason
```

Explainability comes from preserving the actual chain of context behind the result.

For VAT, that can look like:

```text
business input
→ classification or mapping
→ rate evidence
→ calculation contract
→ result
```

If those links survive, the result remains understandable even after the software changes.

If they disappear, a historical VAT amount becomes just another unexplained number in a database.

## The goal is not to store everything

There is a balance.

A provenance-aware API should not dump:

```text
every SQL row
every internal log
every deployment detail
every implementation object
```

into every response.

The goal is to preserve the identities and evidence boundaries that matter.

That usually means:

- stable versions,
- digests or identifiers,
- evidence states,
- bounded public references,
- and enough context to reproduce or review the decision.

Good provenance is not maximum data.

It is the right data.

## A financial result should be able to explain itself

The most useful way to think about provenance is this:

> A stored calculation should carry enough context that a future version of your system can still explain why the result exists.

For VAT, that means going beyond:

```text
19%
```

and preserving:

```text
where the rate came from
which mapping participated
which calculation contract ran
what evidence was available
whether the result can be replayed
```

That does not turn an API into a tax authority.

It does make the API's own decisions easier to inspect, debug, reconcile, and reproduce.

For financial software, that is a meaningful improvement over returning the right number and forgetting how you got there.

---

You can inspect the current VAT Engine calculation contract here:

[Calculate VAT API](https://vat-engine.app/docs/api/calculate)

The stored evidence and replay model:

[Transactions API](https://vat-engine.app/docs/api/transactions)

And the historical-rate evidence boundary:

[VAT Rates API](https://vat-engine.app/docs/api/rates)

VAT Engine is currently in active alpha development. Evidence strength varies by record and source coverage; older records can remain `legacy_unverifiable`, and provenance does not by itself establish legal or tax correctness. VAT Engine does not provide tax or legal advice.
