DEV Community: VAT Engine

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.