EU VAT Validation (VIES) user manual – PrestaShop module

Module page: EU VAT Validation (VIES) PDF · 172 KB

1. What this module does

When you sell to a business in another EU country whose VAT number is active, you do not charge it VAT: the customer accounts for it (reverse charge). Consumers, businesses without a valid number and customers from your own country pay VAT as usual. PrestaShop cannot tell these customers apart, because it never checks VAT numbers.

The module checks the VAT number of the customer's address in VIES, the European Commission's register of VAT numbers, and passes the result to PrestaShop's tax calculation. A verified business from another EU country sees prices, shipping and the order total without VAT; everyone else pays VAT by your tax rules. Each answer of VIES is saved, so a number is asked about at most once per check interval. Timeouts, VIES failures and request limits are handled and logged. Each order keeps the result, and its invoice can carry a reverse charge note.

Works with PrestaShop 1.7.8, 8.x and 9.x (PHP 7.2.5 or newer), with the Classic and Hummingbird themes and with multistore.

2. Installation

  1. Download the module from My account → Order history at addonspresta.com.
  2. In your Back Office, open Modules → Module Manager and click Upload a module.
  3. Drop the ap_vies_v1.1.0.zip file and wait for the confirmation.
  4. Click Configure on the module card and check the Status box at the top.

Right after installation the module is on and Your country is the default country of your shop. Before you rely on it:

  • the address layout of every EU country you sell to must contain the VAT number field (International → Locations → Countries → Edit → Address format, field vat_number). The Status box lists the active EU countries without it;
  • if the Status box reports PrestaShop's old setting VATNUMBER_MANAGEMENT, click Turn off the old setting. That setting comes from the former "vatnumber" module and removes VAT from any foreign VAT number without checking it.

3. How it works

When VIES is asked. The module checks a VAT number when a customer saves an address in the shop (account or checkout), when an address is saved in the Back Office or by another module, and when the customer opens the order page and the saved answer for the tax address of the cart is older than the check interval. Only numbers of EU countries are checked. Before asking, the module removes spaces, dots and dashes, accepts the number with or without its country prefix (GR is accepted for Greece, whose VIES code is EL) and checks the format used in that country, so obvious typing mistakes never reach VIES.

When VAT is removed. All of these must be true:

  • the module is on and taxes are on in your shop;
  • the address has a VAT number and its country is an EU member other than Your country;
  • the number belongs to the country of the address;
  • VIES confirmed the number, and the confirmation is younger than the check interval, or younger than the check interval plus the grace period when VIES could not confirm it again. An employee's mark (Mark as valid / Mark as invalid) overrides VIES.

PrestaShop then applies 0 % to the products, shipping and gift wrapping of the order. In every other case your tax rules apply unchanged. The address used is the one your shop uses for taxes: the delivery address, or the invoice address when International → Taxes → Based on says so.

Speed. The tax calculation only reads the saved answers from the database; it never waits for VIES. A customer waits for VIES only when saving an address or opening the order page with an outdated answer, at most for the Timeout.

Errors and limits. When VIES or the system of a member state does not answer, the module keeps the last answer, logs the error and sends no new request during the Pause after a VIES error (an overloaded VIES gets the same request once more after a second first): to that country after an error of its system or an answer that did not come in time, to VIES as a whole after an error of the service or of the connection. Above Requests per minute or Requests per hour checks wait. Every check that is held back is logged as "Not sent". A VIES failure never blocks a customer.

Orders and invoices. When an order is placed with a VAT number, the module keeps what VIES said (number, decision, consultation number, company, date). The order page in the Back Office shows it in the EU VAT (VIES) box, and the invoice and credit slip of an order without VAT carry your note.

Network and privacy. The module connects only to the VIES service of the European Commission (ec.europa.eu), only to check a number. It sends the VAT number and, if you enter it, your own VAT number. It does not connect to addonspresta.com, does not change PrestaShop tables and adds no file to your storefront.

4. Features and settings

Open Modules → Module Manager → EU VAT Validation (VIES) → Configure. The Help box at the top links to this manual and to the module page at addonspresta.com, in the language of your Back Office.

Status

Shows problems that stop the module from working as expected (taxes turned off, the old VATNUMBER_MANAGEMENT setting, EU countries without the VAT number field, your country outside the EU), the number of requests sent in the last hour, the current pauses and the test mode.

Tax settings

These settings follow the shop selected in the Back Office header.

  • Remove VAT for verified EU businesses — turn off to charge VAT to everyone and stop the storefront checks.
  • Your country — customers from this country always pay VAT, even with a valid number.
  • Your VAT number — optional. When filled in, VIES returns a consultation number with each check, a proof you can show to the tax office. It is shown in the log and on the order.
  • When VIES says the number is not valid — save the address, charge VAT and warn the customer (default), or refuse the address until the number is corrected or removed. The same applies to a number in the wrong format. When VIES does not answer, the address is always saved.
  • Keep a confirmed number verified when VIES does not answer — the grace period in hours (0 to 720, default 72), counted after the check interval.
  • Accept a correct number when VIES does not answer — off by default. When on and VIES gives no answer about a number (VIES or the system of the country is down, overloaded or too slow), a number in the right format for the country of the address is accepted: VAT is removed, the customer is told the number will be checked again, and the order page marks the order "Accepted without an answer from VIES — check the number". A number VIES has said is not valid, or a check held back by your limits, is never accepted. Check such orders before you issue the invoice.
  • Note on invoices and credit slips — one text per language, up to 500 characters, printed in the language of the order. The default says "Reverse charge: VAT to be accounted for by the customer." Adapt it to your situation and your tax adviser's wording, for example with the article of the VAT directive (196 for services, 138 for an intra-Community supply of goods). Leave it empty for no note.

VIES connection (all shops)

These settings are shared by every shop of the installation, because VIES sees one server. Only an employee who manages all shops can change them.

  • Check a number again after — 5 to 43,200 minutes, default 60. Until then the saved answer is used.
  • Timeout — 1 to 30 seconds, default 10 (some countries, such as France, answer in about 4 seconds).
  • Requests per minute and Requests per hour — default 30 and 500.
  • Requests per visitor and hour — default 10: checks caused by one storefront visitor (a logged-in customer, or a guest by IP address; all visitors from one IP address together may send five times as many), so that nobody can use up the limits of your shop with made-up numbers. The Back Office is not limited by it. The module keeps only a coded fingerprint of the IP address, never the address itself.
  • Pause after a VIES error — 0 to 1,440 minutes, default 5; 0 turns pauses off.
  • Keep the log for — 1 to 365 days, default 30.
  • Test mode — uses the VIES test service instead of the real one: number 100 is valid, 200 is not valid, 300 to 601 return VIES errors (for example 301 "system of the country unavailable", 500 "VIES overloaded"). Real numbers get no answer in test mode. Turn it off and delete the test numbers from the list before you sell.

Check a VAT number

Choose an EU country, enter a number and click Check. VIES is asked at once, even when the number was checked recently; the limits and pauses still apply. Use it to test the connection or to answer a customer.

VAT numbers

Every number checked so far, with its status, the company name and address from VIES, the last check, the last confirmation, the last error and the number of errors in a row. Search by number or company and filter by status. Each row has:

  • Check now — asks VIES again;
  • Mark as valid / Mark as invalid — your decision overrides VIES until you click Remove mark, for example when the system of a country is down for days and you checked the company yourself;
  • Delete — forgets the number; it is checked again the next time a customer uses it.

A number applies to every shop, so the marks and Delete are available only to an employee who manages all shops.

Log

Every request sent to VIES, every check held back by the limits or pauses, and every mark, with the date, the shop, the source (address form, address saved, checkout, Back Office), the result with its VIES code, the time in milliseconds and details. Tick Errors only to see the problems. Clear the log deletes the entries of the shops selected in the header; older entries are deleted automatically after the number of days you set.

5. Multistore

The tax settings follow the shop or shop group selected in the Back Office header, so each shop can have its own country, VAT number, invoice note and behaviour. The VIES connection settings, the list of VAT numbers and the limits are shared by all shops: a number is valid or not regardless of the shop. The log shows the shops selected in the header, with a Shop column. An employee who does not manage every shop can change the tax settings only with one of their shops selected and cannot change the connection settings. One licence covers every shop of the installation.

6. Uninstall

Module Manager → EU VAT Validation (VIES) → Uninstall deletes the settings, the list of VAT numbers, the log and the VIES results kept with orders; from then on PrestaShop charges VAT by your tax rules again. Invoices already generated are not changed. Use Disable instead to keep the data.

7. FAQ and troubleshooting

A customer with a valid VAT number still pays VAT. Check, in this order: the customer's country is not Your country; the number is in the address used for taxes (delivery or invoice address, see International → Taxes); the number appears as Valid in the list (click Check now if not); the Status box reports no problem. Prices without VAT appear once the address is selected in the cart, which happens at checkout.

The customer cannot enter a VAT number. The VAT number field is missing from the address layout of their country. Add vat_number in International → Locations → Countries → Edit → Address format.

German numbers return an error at night. The German system is often unavailable in VIES for several hours at night ("System of the country unavailable"). Numbers confirmed earlier keep prices without VAT during the grace period. New numbers pay VAT until VIES answers — or, with Accept a correct number when VIES does not answer, get prices without VAT at once and are checked again later.

The log shows "System of the country unavailable". The VAT system of that member state is down, which happens regularly for maintenance. Customers already confirmed keep their prices without VAT during the grace period; new numbers are checked again after the pause. If a system stays down for days, check the company in another way and use Mark as valid.

The log shows "VIES overloaded" or "Your server is blocked by VIES". VIES limits the number of requests. Lower Requests per minute and Requests per hour and raise Check a number again after. A block usually ends after a while.

Can a customer enter another company's VAT number? VIES confirms that a number is active, not who typed it. The order keeps the company name and address that VIES returned, shown in the EU VAT (VIES) box of the order: compare them with the customer's address before you ship a large order.

Does the module change my tax rules or prices? No. It only tells PrestaShop to apply 0 % for a verified business from another EU country. Your tax rules, prices and customer groups stay as they are.

Customers say their number "could not be checked" although VIES works. Look for "Not sent: limit per visitor reached" in the log. Logged-in customers are counted by their account, guests by their IP address, and all visitors of one address together up to five times the limit. If your shop runs behind a CDN or proxy that hides the visitors' addresses, all guests share one address: make the server see the real address (for example Cloudflare's "real IP" setting of your host) or raise Requests per visitor and hour.

What should the invoice note say? Ask your accountant. For services the usual mention is "Reverse charge" (article 196 of Directive 2006/112/EC), for goods sent to another EU country "Exempt intra-Community supply" (article 138).

8. Updates and support

Updates are free for life: download new versions from My account → Order history at addonspresta.com and upload them like a new module. Your settings, VAT numbers, log and order data are kept.

Support is included for 12 months from your order: write to mail@addonspresta.com or use the contact form at addonspresta.com (Monday to Friday, 10:00–16:00 CET; we usually answer within 2 business days). Please include your PrestaShop version, the module version and the steps that lead to the problem.

Back to User manuals

Back to top