Alpha testing: all current functionality is free while VAT Engine is in active development

VAT Engine logo

Historical rate handling

Historical VAT rates API

A current rate is not always the right rate. Historical lookup uses approved source-supported coverage where available; older imported windows remain legacy evidence and do not by themselves prove legal applicability.

What this helps you do

Handle refunds, audits, migrations, and delayed imports using date-aware tax inputs rather than silently substituting today’s rate.

  • Date-indexed requests for supported VAT rates.
  • Reviewed calculation responses include bounded rate and calculation provenance; older records are not upgraded by inference.
  • Exact replay is available only for account-owned calculations whose recorded replay status is available, using their original request, sealed rate evidence, and registered calculator version.
  • The public rate-lookup and exact-replay endpoints do not accept caller-selected rate-data or calculator versions.

How to use it well

Use the original supply context

For a refund or correction, start from the relevant supply date and business facts rather than recalculating with a current default.

Keep corrections identifiable

Link a correction to a stable external event or order reference so review and reporting can distinguish revisions from duplicates.

Escalate gaps in source coverage

If the requested date or classification is not covered, stop for review instead of falling back to an unrelated rate.

Choose between a dated lookup and exact replay

Backfilling an old invoice and reproducing an existing calculation are different jobs. A fresh historical lookup selects covered data now; replay uses the original record’s sealed evidence.

  1. For a new dated lookup, pass at to the rates endpoint or transaction_date to the calculate endpoint and inspect the returned evidence.
  2. For an existing account-owned calculation, retrieve its transaction detail and check replay_status. Captured evidence alone is not enough.
  3. Only when replay_status is available, request replay using the transaction identifier. Do not submit new amounts, a replacement rate version, or a calculator override.
POST /v1/transactions/{calculation_id}/replay
X-API-Key: YOUR_API_KEY

Successful replay reports exact_match: true. Unavailable or inaccessible records remain unavailable; older legacy calculations are not automatically upgraded to replayable evidence.

Read exact replay prerequisites and failures