For web hosting providers, SaaS companies, and digital agencies using WHMCS, complying with European Union Value Added Tax (EU VAT) regulations is non-negotiable.
Under the EU One-Stop Shop (OSS) rules, businesses selling electronic, telecommunications, and digital hosting services to European consumers (B2C) must charge VAT at the rate of the customer’s EU Member State of residence (destination-based taxation). Meanwhile, cross-border sales to verified VAT-registered businesses (B2B) must apply the reverse-charge mechanism (0% VAT), provided their VAT identification number is verified against the European Commission’s VIES system.
Failing to report and remit accurate VAT by country can lead to steep penalties and account freezes.
In this comprehensive tutorial, you will learn how to configure WHMCS for strict EU VAT compliance, avoid dangerous manual schema alterations, and build an optimized custom EU VAT report module using WHMCS’s native Capsule ORM to generate ready-to-file quarterly OSS returns.
1. Understanding EU VAT Compliance and OSS Rules
Before touching the codebase, let’s clarify the legal rules governing digital services in the EU:
- B2C (Business-to-Consumer): If you sell hosting or cloud services to an individual in Germany, you must charge Germany’s 19% VAT. If you sell to a consumer in France, you must charge France’s 20% VAT. All collected taxes are reported quarterly through a single EU OSS return.
- B2B (Business-to-Business): If an EU business provides a valid VAT identification number from a different EU Member State, VAT is not charged (0% rate). The customer accounts for the tax under the reverse-charge mechanism.
- Domestic Sales: If you are based in Spain and sell to a Spanish client (B2B or B2C), domestic VAT always applies regardless of reverse-charge rules.
- VIES Validation: You must validate the client’s VAT number via the European Commission’s VIES (VAT Information Exchange System) database at checkout and retain timestamped audit records.
2. Native WHMCS Tax Architecture and Configuration
WHMCS possesses a dedicated tax engine and database schema. Never attempt to execute direct ALTER TABLE schema changes or fabricate standalone Eloquent models inside WHMCS core directories—doing so breaks core upgrades and invalidates license integrity.
WHMCS Database Schema for Taxes
WHMCS manages taxation across three primary tables:
tbltax: Stores configured tax levels, country codes, state codes, and rates.tblclients: Stores client country, state, tax exemption flags (taxexempt), and custom fields (such as the EU VAT number).tblinvoices: Stores the invoice total, tax (tax), secondary tax (tax2), tax rate (taxrate), and payment dates.
Enabling the Native EU VAT Addon
WHMCS includes an official EU VAT Addon that automates country-specific VAT rules, customer registration prompts, and real-time VIES API queries.
To activate it:
- Log in to the WHMCS Admin Area.
- Navigate to Configuration > System Settings > Addon Modules (or Setup > Addon Modules).
- Locate EU VAT Addon, click Activate, and assign Full Administrator permissions.
- Navigate to Addons > EU VAT Addon in the navigation bar to configure options:
- Home Country: Select your company’s registration country.
- Tax Exempt: Check to automatically mark clients with a validated VIES VAT number as tax-exempt.
- Enable Custom Field: Allow WHMCS to create or link the VAT ID customer field.
3. Developing a Custom EU VAT Compliance Report in WHMCS
While WHMCS records transactions accurately, its default reports do not group sales and VAT amounts into the exact format required for quarterly One-Stop Shop (OSS) tax declarations.
We will develop a custom report module in WHMCS following the official WHMCS Reporting API specifications.
How WHMCS Reports Work
WHMCS reports are standalone PHP scripts placed inside the /modules/reports/ directory. Each script defines metadata and data inside a global $reportdata array, which the WHMCS admin theme automatically renders with sorting, pagination, and export tools.
Create a new file: modules/reports/eu_vat_oss_summary.php:
<?php
/**
* Custom WHMCS Report: EU VAT One-Stop Shop (OSS) Quarterly Compliance Summary
*
* File: /modules/reports/eu_vat_oss_summary.php
*/
if (!defined("WHMCS")) {
die("This file cannot be accessed directly");
}
use WHMCS\Database\Capsule;
use WHMCS\Carbon;
$reportdata["title"] = "EU VAT OSS Compliance Summary";
$reportdata["description"] = "Aggregates B2C and B2B sales by EU Member State for quarterly VAT returns under the One-Stop Shop (OSS) scheme.";
// 1. Filter parameters (Start and End Dates)
$range = $whmcs->get_req_var('range');
$startDate = $whmcs->get_req_var('start_date');
$endDate = $whmcs->get_req_var('end_date');
if (!$startDate || !$endDate) {
// Default to the previous completed quarter
$now = Carbon::now();
$quarter = $now->quarter;
$startDate = $now->copy()->subQuarter()->startOfQuarter()->format('Y-m-d');
$endDate = $now->copy()->subQuarter()->endOfQuarter()->format('Y-m-d');
}
// 2. Define EU Member State Country Codes
$euCountries = [
'AT' => 'Austria', 'BE' => 'Belgium', 'BG' => 'Bulgaria', 'CY' => 'Cyprus',
'CZ' => 'Czech Republic', 'DE' => 'Germany', 'DK' => 'Denmark', 'EE' => 'Estonia',
'ES' => 'Spain', 'FI' => 'Finland', 'FR' => 'France', 'GR' => 'Greece',
'HR' => 'Croatia', 'HU' => 'Hungary', 'IE' => 'Ireland', 'IT' => 'Italy',
'LT' => 'Lithuania', 'LU' => 'Luxembourg', 'LV' => 'Latvia', 'MT' => 'Malta',
'NL' => 'Netherlands', 'PL' => 'Poland', 'PT' => 'Portugal', 'RO' => 'Romania',
'SE' => 'Sweden', 'SI' => 'Slovenia', 'SK' => 'Slovakia'
];
// 3. Render HTML Filter Form
$reportdata["headertext"] = '
<form method="post" action="' . $PHP_SELF . '?report=' . $report . '" class="form-inline" style="margin-bottom: 20px;">
<div class="form-group">
<label for="start_date">From:</label>
<input type="date" name="start_date" id="start_date" value="' . htmlspecialchars($startDate) . '" class="form-control" />
</div>
<div class="form-group" style="margin-left: 10px;">
<label for="end_date">To:</label>
<input type="date" name="end_date" id="end_date" value="' . htmlspecialchars($endDate) . '" class="form-control" />
</div>
<button type="submit" class="btn btn-primary" style="margin-left: 10px;">Generate Report</button>
</form>
';
// 4. Define Table Columns
$reportdata["tableheadings"] = [
"Country Code",
"Country Name",
"Invoice Count",
"Applied Tax Rate",
"Net Sales (Subtotal)",
"VAT Collected",
"Gross Total"
];
// 5. Query Paid Invoices using WHMCS Capsule ORM
try {
$results = Capsule::table('tblinvoices')
->join('tblclients', 'tblinvoices.userid', '=', 'tblclients.id')
->whereIn('tblclients.country', array_keys($euCountries))
->where('tblinvoices.status', '=', 'Paid')
->whereBetween('tblinvoices.datepaid', [$startDate . ' 00:00:00', $endDate . ' 23:59:59'])
->select(
'tblclients.country',
'tblinvoices.taxrate',
Capsule::raw('COUNT(tblinvoices.id) as invoice_count'),
Capsule::raw('SUM(tblinvoices.subtotal) as total_net'),
Capsule::raw('SUM(tblinvoices.tax + tblinvoices.tax2) as total_vat'),
Capsule::raw('SUM(tblinvoices.total) as total_gross')
)
->groupBy('tblclients.country', 'tblinvoices.taxrate')
->orderBy('tblclients.country', 'ASC')
->get();
$grandNet = 0;
$grandVat = 0;
$grandGross = 0;
foreach ($results as $row) {
$countryName = $euCountries[$row->country] ?? $row->country;
$net = (float) $row->total_net;
$vat = (float) $row->total_vat;
$gross = (float) $row->total_gross;
$grandNet += $net;
$grandVat += $vat;
$grandGross += $gross;
$reportdata["tablevalues"][] = [
$row->country,
$countryName,
$row->invoice_count,
number_format($row->taxrate, 2) . '%',
formatCurrency($net),
formatCurrency($vat),
formatCurrency($gross),
];
}
// Add Summary Row
$reportdata["tablevalues"][] = [
"<strong>TOTAL</strong>",
"<strong>All EU Member States</strong>",
"<strong>-</strong>",
"<strong>-</strong>",
"<strong>" . formatCurrency($grandNet) . "</strong>",
"<strong>" . formatCurrency($grandVat) . "</strong>",
"<strong>" . formatCurrency($grandGross) . "</strong>",
];
} catch (\Exception $e) {
$reportdata["headertext"] .= '<div class="alert alert-danger">Database error: ' . htmlspecialchars($e->getMessage()) . '</div>';
}Upload this script into your WHMCS installation under /modules/reports/. Immediately, the new report will be visible under Reports > EU VAT OSS Compliance Summary in your WHMCS administrator sidebar!
4. Exporting and Formatting Data for Quarterly OSS Returns
Tax authorities in EU Member States (such as the German Federal Central Tax Office or the Irish Revenue Commissioners) require quarterly OSS filings with exact breakdowns:
- Country of Consumption
- Standard or Reduced VAT Rate
- Taxable Base Amount (EUR)
- VAT Amount (EUR)
Because WHMCS’s report runner provides native CSV and Print export hooks, clicking Export to CSV in the report header automatically produces a clean spreadsheet file formatted for your accounting software or tax portal.
If your WHMCS store operates in multiple currencies (e.g. USD, GBP, and EUR), convert your quarterly balances to Euros using the European Central Bank’s published end-of-period exchange rates, which WHMCS updates automatically when currency auto-updating is enabled under Configuration > System Settings > Currencies.
5. Automating VAT Rate and VIES Health Checks via Cron
The EU VIES API occasionally experiences downtime or per-country server maintenance. When the VIES API is unreachable, a legitimate EU B2B customer could mistakenly be charged VAT or blocked at checkout.
To ensure continuous compliance without checkout disruption:
- WHMCS Automation Cron:
Verify that your server crontab includes the standard WHMCS cron runner executing every 5 minutes:*/5 * * * * php -q /path/to/whmcs/crons/cron.php - Scheduled EU VAT Verification Hook:
Create a WHMCS hook in/includes/hooks/eu_vat_health_check.phpto log and re-validate unverified customer VAT numbers:
<?php
/**
* Hook: Scheduled Re-validation for Pending EU VAT Numbers
* File: /includes/hooks/eu_vat_health_check.php
*/
use WHMCS\Database\Capsule;
use WHMCS\Module\Addon\EuVat\Vies;
add_hook('DailyCronJob', 1, function ($vars) {
// Locate clients with VAT numbers that were validated more than 90 days ago
$staleClients = Capsule::table('tblclients')
->where('taxexempt', '=', 1)
->whereNotNull('tax_id')
->where('tax_id', '!=', '')
->limit(50)
->get();
foreach ($staleClients as $client) {
try {
// WHMCS EU VAT Addon internal helper
$isValid = Vies::check($client->tax_id);
if (!$isValid) {
logActivity("EU VAT Audit: Client ID {$client->id} VAT number [{$client->tax_id}] failed re-validation. Removing tax exemption.");
Capsule::table('tblclients')
->where('id', $client->id)
->update(['taxexempt' => 0]);
}
} catch (\Exception $e) {
// Keep status quo if VIES is unreachable
logActivity("EU VAT Audit: VIES API unavailable for Client ID {$client->id}: " . $e->getMessage());
}
}
});6. Testing, Validation, and Post-Brexit Handling
Before closing your audit review, execute test purchases against these scenarios:
- Domestic B2C & B2B: Ensure your home country VAT is always charged regardless of whether the buyer enters a valid VAT number.
- Cross-Border EU B2C: Verify that selecting Germany calculates 19% and France calculates 20% on checkout line items.
- Cross-Border EU B2B: Enter a valid foreign EU VAT number (e.g., French business buying from an Irish host). Confirm that tax drops to 0% and the invoice displays the note: “VAT reverse-charged pursuant to Article 196 of Council Directive 2006/112/EC”.
- Post-Brexit UK & Northern Ireland: The UK is no longer an EU Member State for OSS purposes. However, Northern Ireland goods transactions are covered by the
XIprefix under the Northern Ireland Protocol, while digital services from the UK to the EU are treated as standard non-EU exports.
By using native WHMCS configuration, the EU VAT Addon, and our custom OSS summary report module, your billing platform remains 100% compliant, auditable, and resilient to core upgrades.
Frequently Asked Questions
What is the One-Stop Shop (OSS) scheme in WHMCS?
The EU One-Stop Shop (OSS) allows businesses selling cross-border digital services to EU consumers to collect VAT at the customer’s domestic rate and remit all collected taxes via a single quarterly return in their home Member State.
How does WHMCS handle B2B reverse-charge VAT?
When the official EU VAT Addon is enabled, WHMCS validates the customer’s VAT identification number against the European Commission’s VIES database. If valid, the customer is marked tax-exempt and the invoice applies the 0% reverse-charge rate.
Where should custom reports be placed in WHMCS?
Custom report modules must be placed inside the /modules/reports/ directory as standalone PHP files. They populate the global $reportdata array and are automatically recognized by the WHMCS Admin reporting interface.
Why should I avoid modifying the WHMCS database schema directly?
Executing direct ALTER TABLE queries on core WHMCS tables (or creating fabricated tables) violates data integrity, risks breaking core WHMCS upgrades, and can void software support.
How does WHMCS handle VIES API downtime?
You can configure the EU VAT Addon to either fail safely (allow purchase without tax exemption until verified) or utilize background cron hooks to re-validate pending VAT numbers when VIES services recover.