Collect and Check EU VAT Numbers
Selling to businesses in the EU means asking for a VAT number, checking it and removing VAT under the reverse charge. Doing that by hand means refunding the VAT after the fact and keeping screenshots of the VIES check for your tax office.
VAT Numbers adds a VAT number field to the EDD checkout, next to the billing address, on the checkout page and the Checkout block. It checks the number with the EU’s VIES service. A valid business buyer in another EU country pays no VAT, and the totals update as soon as the number is entered. The order keeps the number and the proof of the check.
Before You Start
- Taxes are on in EDD, with your EU tax rates set under Downloads → Settings → Taxes.
- The checkout shows billing address fields. EDD shows them when taxes are on, or when you turn address fields on in its checkout settings. The VAT field shows only with them.
- Prices are entered exclusive of tax. With prices that include tax, the reverse charge keeps the gross price, so the buyer pays the same total with no VAT line.
- EDD’s own EU VAT handling is off. When it’s on, VAT Numbers does nothing at checkout and its settings page says so. The EDD EU VAT add-on pauses the module too, and the Dashboard says which one.
Turn On VAT Numbers
Open Stackless → Dashboard and turn on VAT Numbers. It’s in the Checkout group. Then open Stackless → Settings → VAT Numbers.
Settings
- Field label: the label at checkout, on receipts and in emails. Default “VAT number”.
- Field: Optional (the default) or Required for EU billing addresses (business-only stores). Required asks for a number whenever the billing country is in VIES, except the UK.
- VIES check: Check numbers with VIES (results are cached for a week). On by default.
- Invalid numbers: Ask the customer to correct it (the default), or Accept the order and charge VAT.
- When VIES is down: Accept a well-formed number, remove VAT and check again later (the default), or Charge VAT until VIES confirms the number.
- Reverse charge: Remove VAT for valid business buyers in another EU country. On by default.
- Same country: Also remove VAT for buyers in your store’s own country. Off by default, and rarely correct, so ask your accountant first.
- Your VAT number: optional, such as DE123456789. It’s sent with each check so VIES returns a consultation number you can show a tax office. A number in a format VIES doesn’t know isn’t saved.
The Field at Checkout
The field sits at the bottom of the billing details. On the checkout page it has a line under the label: “Businesses in the EU can enter their VAT number to buy without VAT under the reverse charge.” Buyers can type the number with or without the country prefix, in any case, with spaces or dots.
When the number changes, the field shows “Checking the number with VIES…” and then a message under it. EDD recalculates the taxes at the same time, so the totals refresh without a reload:
| Message | When |
|---|---|
| VAT is removed under the reverse charge. | The number is valid and VAT comes off. |
| Valid VAT number. VAT still applies to this order. | The number is valid, but the buyer is in your own country, or Reverse charge is off. |
| VIES could not be reached. Your number is accepted without VAT and will be checked again. | VIES is down and the fallback accepts the number. |
| VIES could not be reached, so VAT is charged for now. | VIES is down and the fallback charges VAT. |
| VIES does not recognize this number, so VAT is charged. | The number isn’t valid and Invalid numbers accepts the order. |
| The number is saved with your order. VAT still applies. | A number VIES doesn’t cover, such as a UK or Swiss one. |
These stop the purchase until they’re fixed: “VAT number is required.”, “This VAT number does not match your billing country.”, “This VAT number is not in the right format.” and, with the default Invalid numbers choice, “VIES does not recognize this VAT number. Check it, or leave the field empty to pay with VAT.”
Checkouts for an invoice, a renewal or a plan switch show no field and keep the tax they bill.
Who Pays VAT
| The buyer enters | VAT |
|---|---|
| A number VIES confirms, with a billing address in another EU country | Removed under the reverse charge |
| A number VIES confirms, with a billing address in your own country | Charged, unless Same country is on |
| A number VIES doesn’t recognize | Charged, or the checkout asks for a correction |
| A well-formed number while VIES is down | Removed and checked later, or charged, as you chose |
| A UK (GB), Swiss, Norwegian or other non-EU number | Charged. The number is still saved on the order. |
| No number | Charged |
VAT comes off through EDD’s own tax rate: the buyer’s rate becomes zero, so EDD’s totals, receipts and reports stay right. With VIES check turned off, a well-formed number for the billing country removes VAT without a check, so leave it on unless you check numbers another way.
When VIES Is Down
With the default fallback, an order taken during an outage is checked again an hour later, then every six hours, up to four times. Totals never change after the order. The order gets a note with the result:
- “VIES confirmed VAT number” and the number, when it turns out valid.
- A note that VIES doesn’t recognize the number, flagging the order for review, when it turns out invalid.
- “VIES stayed unavailable, so the VAT number on this order was never confirmed. Check it before you file the return.” after the last try.
Caching and Lookups
- VIES answers are cached: a valid result for a week, an invalid one for a day and an outage for ten minutes. Checkout refreshes never ask twice for the same number.
- A visitor can look up 12 new numbers per hour. Cached and malformed numbers don’t count, and shop managers have no cap. Past that, a new number is treated as if VIES were down.
What the Order Keeps
The order keeps the number, the VIES result, the business name and address VIES returned, the request date, the consultation number and the check time. A reverse charge is recorded only when the order really has no tax.
- The order screen gets a box, titled with your field label, in the sidebar. It shows the number, the result and check time, the consultation number, the business name and address, “Reverse charge applied (no VAT).” and “Needs review: the number was not confirmed after checkout.” when that applies.
- The receipt shows the number, and “Reverse charge: VAT to be accounted for by the recipient.” when VAT was removed.
- The
{vat_number}email tag prints the same. EDD’s purchase receipt and admin order notification include it automatically unless their text already places the tag.
An order without a number shows nothing, never the number saved on the account.
Invoices and the Customer’s Account
When a signed-in buyer’s number is valid, not checked (such as a UK number) or entered during an outage, it’s saved on their account. Invalid and wrongly formatted numbers aren’t. At the next checkout the field starts with what the visitor last entered, or else the number on their own account.
Custom Invoices reads the same account number, so invoices for that customer fill it in. Customers change their saved number by entering a new one at checkout, because EDD’s profile editor has no VAT field.
Subscriptions
Renewal orders bill the tax stored when the subscription started. Each renewal copies the first order’s number and proof, plus the reverse charge note when the renewal is untaxed too. Renewals aren’t checked with VIES again.
Northern Ireland, Greece and Other Countries
- Northern Ireland: VIES covers it with the XI prefix. With a UK billing address, type the number with XI to have it checked. A number without a prefix is read as a GB number.
- Greece: VIES uses EL. A number typed with GR is changed to EL.
- UK (GB), Swiss, Norwegian and other non-EU numbers: saved on the order and the account, but not checked or zero-rated.
Privacy
The VAT number, and your own number when set, go to the European Commission’s VIES service when a buyer enters a number and when an outage order is checked again. Answers are cached on your site, as stackless_edd_vat_numbers_ transients.
- Tools → Export Personal Data lists the number saved on the account. EDD’s own Customer Orders export carries each order’s number, check result, consultation number and VIES business details. It also says when the reverse charge applied.
- Tools → Erase Personal Data always removes the account’s number and its cached VIES answer.
- Order numbers follow EDD’s own order privacy settings under Downloads → Settings → Policies → Export & Erase. When EDD anonymizes an order, its number becomes [deleted], and the proof keeps only the result, country, source, check time and request date. The reverse charge and review flags stay, so the order still shows why no VAT was charged. Orders EDD deletes lose their VAT data with them.
- A privacy policy suggestion is added under Settings → Privacy.
Limits
- VIES covers EU countries and Northern Ireland only. Other numbers are stored but never checked or zero-rated.
- The field shows only when EDD’s checkout asks for a billing address. Without a country field, the country EDD taxes with is used: the customer’s saved address, then your shop country.
- With prices entered inclusive of tax, the buyer pays the same total with no VAT line. Stores selling to EU businesses should enter prices exclusive of tax.
- Express wallet buttons on a download page skip the purchase form, so they carry no VAT number and VAT is charged.
- Guests’ numbers stay on their orders only. Custom Invoices fills in the number only for customers with an account.
For Developers
stackless_edd_vat_numbers_pre_check lets you answer a check yourself, for tests or another lookup service. Return an array in the shape of Vies::parseResponse(), or null to ask VIES:
add_filter('stackless_edd_vat_numbers_pre_check', function ($result, $prefix, $number) {
if ($prefix === 'DE' && $number === '123456789') {
return [
'status' => 'valid',
'name' => 'Example GmbH',
'address' => 'Berlin',
'request_date' => gmdate('Y-m-d'),
'request_identifier' => '',
'error' => '',
];
}
return $result;
}, 10, 3);
To change the field’s markup, copy templates/vat_numbers/checkout-field.php to stackless-edd/vat_numbers/checkout-field.php in your theme. Keep the input’s id and name and the status element, because the checkout script reads them.