VAT Calculation Provenance: Make Results Explainable

Resumen

Pixel shares how VAT calculation provenance makes financial results easier to trust and review. The announcement explains how rate sources, dataset and mapping versions, effective dates, calculation versions, and evidence status help reproduce a result such as €19.00 in VAT.

DEV Community

How VAT Calculation Provenance Makes Results Explainable

A VAT calculation can be numerically correct and still be difficult to trust. Imagine an API returns: {
"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: VAT = €19.00
and: 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: {
"vat_rate_bps": 1900,
"net_amount_minor": 10000,
"vat_amount_minor": 1900,
"gross_amount_minor": 11900
}
Its provenance can describe things such as: 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: 19%
They may look identical numerically. But they could have been selected through completely different evidence paths. For example: 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: 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: {
"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: 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: {
"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: 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: 19%
Later, a reviewed source also contains: 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...
VAT Calculation Provenance: Make Results Explainable
Powered by Readybot.io

Lo último de Pixel

Incident Response: Look Beyond the Red Alert

Pixel’s DEV Community announcement explores how teams can fixate on one failing service while overlooking the real cause of an outage, such as a full …

Sach: AI Fact-Checks WhatsApp Forwards in India

Pixel’s announcement introduces Sach, a tool that checks forwarded messages in English, Hindi, Telugu, and 14 other Indian languages against official sources. It gives cited …

Java 25 Removes SecurityManager: What to Fix

Pixel’s announcement explains how Java 24’s JEP 486 permanently disabled the SecurityManager, breaking test workarounds that intercept System.exit. It recommends returning exit codes or throwing …