VAT for EU Countries (VAT4EU) for Zen Cart® 1.5.8a and 2.0.0

Version 3.2.0 by lat9 and webchills. Copyright © 2017-2024, Vinos de Frutas Tropicales.

Current Support Thread on the Zen Cart forums: https://www.zen-cart.com/showthread.php?223003-VAT4EU-Support-Thread

Usage Notes:

  1. A working copy of Zen Cart (v1.5.8a or v2.0.0) must be previously installed.
  2. Integration with Edit Orders requires EO version 4.7.0 or later. See the Interaction with Other Plugins tab for more information.
  3. Integration with One-Page Checkout requires OPC version 2.4.6 or later.
  4. Integration with the Bootstrap template requires v3.6.3 or later.
  5. If you require the automatic VAT validation service (via VIES) to operate properly, you'll need to ensure that the SOAP service is enabled in your site's PHP. To check, navigate to your Zen Cart admin's Tools :: Server/Version Info and search that page for Soap Client. If that setting is not found or is not set to enabled, then the VIES service cannot be used.
  Important: If your site is using v1.5.8a, you'll need to update
  1. admin/customers.php to include these updates that were applied after v1.5.8a's release. Without those changes, you will not be able to successfully update a customer's record if the VAT Number was found to be invalid!
  2. includes/classes/Customer.php to include this change; otherwise, a customer's entered VAT Number won't be added to various pages' formatted-address(es) displays.
  3. includes/functions/functions_addresses.php, to include this change; otherwise, formatted addresses that should contain a VAT Number might not.

VAT for EU Countries (VAT4EU) updates your store to gather, display and validate an EU "VAT Number". Once the plugin is installed, configured and enabled on your store:

  1. The address-gathering forms on the storefront and the admin's Customers :: Customers tool include an input field for a VAT Number.
  2. Billing-address blocks within the various checkout- and account-related pages and order-confirmation emails have the associated "VAT Number" appended.
  3. Your admin's invoices' and packingslips' billing-address displays with any "VAT Number" associated with the associated order.
  4. If an order qualifies for a VAT Refund, order-total modules display the refunded VAT value, deducting that value from the order's total, and include a "VAT reverse-charge" statement for the order.
    • A qualified order:
      1. Includes a validated (either via VIES, see below, or via admin-override) VAT Number for the billing address.
      2. Is to be shipped to an EU country other than the country in which the store resides (unless otherwise configured).
    • Unlike the previous (see below) version of this processing, no alteration is made to product prices; your store will continue to display prices inclusive of VAT (if so configured). The VAT Refund processing simply inserts an order-total element that backs-out any tax charged for qualified orders.
  5. The plugin's processing makes use of the VIES (VAT Information Exchange System) on-line validation service to automatically validate any VAT Number entered — either by the customer or an admin. Admin processing includes a validation-override.

Note: This plugin is derived from the similarly-named plugin VAT-mod for European companies, but its processing is quite different!

This section identifies the processes you'll use to install VAT for EU Countries or uninstall VAT4EU entirely.

There are template-overrides required by this plugin; you should always backup your cart's database and files prior to making any changes. All template-overrides use the like-named files in the Zen Cart 1.5.8a distribution as their change-basis. Template-file changes are based on those present in that release's template_default directories.

Unzip the plugin's package file and then:

  1. Rename the YOUR_ADMIN folder to match your custom admin folder's name.
  2. If you are using a template based on Zen-Cart's built-in responsive_classic or template_default templates:
    1. Rename the YOUR_TEMPLATE sub-directory to match your current template's name:
      1. /includes/templates/YOUR_TEMPLATE
    2. Merge any pre-existing template-file changes with the changes required by VAT4EU:
      1. /includes/templates/YOUR_TEMPLATE/templates/tpl_modules_address_book_details.php (1 marked change-section)
      2. /includes/templates/YOUR_TEMPLATE/templates/tpl_modules_checkout_new_address.php (1 marked change-section)
      3. /includes/templates/YOUR_TEMPLATE/templates/tpl_modules_create_account.php (1 marked change-section)
  3. If you are using a template based on the Bootstrap template:
    1. Rename the bootstrap sub-directory to match your current Bootstrap template's name:
      1. /includes/templates/bootstrap
    2. Merge any pre-existing template-file changes with the changes required by VAT4EU:
      1. /includes/templates/bootstrap/templates/tpl_modules_common_address_format.php (1 marked change-section)
      2. /includes/templates/bootstrap/templates/tpl_modules_create_account.php (1 marked change-section)
      3. /includes/templates/bootstrap/templates/tpl_modules_opc_address_block.php (1 marked change-section)
  4. Sign into your Zen Cart's admin panel.
  5. Copy the plugin's files (including those possibly modified above) to your store's directory structure:
    1. /includes/classes/VatValidation.php
    2. /includes/classes/observers/auto.vat_for_eu_countries.php
    3. /includes/extra_datafiles/vat4eu_filenames.php
    4. /includes/languages/english/extra_definitions/lang.vat4eu_extra_definitions.php
    5. /includes/languages/english/html_includes/define_popup_vat4eu_formats.php
    6. /includes/languages/english/modules/order_total/lang.ot_vat_refund.php
    7. /includes/languages/english/modules/order_total/lang.ot_vat_reverse_charges.php
    8. /includes/modules/order_total/ot_vat_refund.php
    9. /includes/modules/order_total/ot_vat_reverse_charges.php
    10. /includes/modules/pages/popup_vat4eu_formats/header_php.php
    11. /includes/modules/pages/popup_vat4eu_formats/jscript_main.php
    12. /includes/templates/bootstrap/css/popup_vat4eu_formats.css1
    13. /includes/templates/bootstrap/templates/tpl_modules_common_address_format.php1
    14. /includes/templates/bootstrap/templates/tpl_modules_create_account.php1
    15. /includes/templates/bootstrap/templates/tpl_modules_opc_address_block.php1
    16. /includes/templates/template_default/css/popup_vat4eu_formats.css
    17. /includes/templates/template_default/popup_vat4eu_formats/tpl_main_page.php
    18. /includes/templates/template_default/templates/tpl_modules_vat4eu_display.php
    19. /includes/templates/YOUR_TEMPLATE/css/popup_vat4eu_formats.css2
    20. /includes/templates/YOUR_TEMPLATE/templates/tpl_modules_address_book_details.php2
    21. /includes/templates/YOUR_TEMPLATE/templates/tpl_modules_checkout_new_address.php2
    22. /includes/templates/YOUR_TEMPLATE/templates/tpl_modules_create_account.php2
    23. /YOUR_ADMIN/includes/auto_loaders/config.vat4eu_admin.php
    24. /YOUR_ADMIN/includes/classes/Vat4EuAdminObserver.php
    25. /YOUR_ADMIN/includes/init_includes/init_vat4eu_admin.php
    26. /YOUR_ADMIN/includes/languages/english/extra_definitions/lang.vat4eu_admin_definitions.php
  6. Click the "Admin Home" link in your Zen Cart's top admin menu. This action will cause the plugin's installation script to run.
  7. Next step … Configuration!

Notes:

  1. bootstrap possibly renamed in step C, above.
  2. YOUR_TEMPLATE possibly renamed in step B, above.

First, delete the files that were copied to your Zen Cart's file-system during the installation process, then copy the contents of the plugin's /docs/vat4eu/uninstall/uninstall_vat4eu.sql to your clipboard and paste into your admin's Tools :: Install SQL Patches to complete the uninstall process.

Once you've performed the initial Installation steps, a new configuration group is available in your admin's menu: Configuration :: VAT for EU Countries. The following settings are provided:

Setting Name Description Default
Plugin Version and Release Date Displays the plugin's currently installed version and release date. Varies
European Union Countries List Contains a comma-separated list of the ISO-code-2 values, e.g. DE for Germany, of the countries currently in the European Union — with intervening blanks allowed. The list is updateable since countries can move in and out of the EU!

Note: Versions of VAT4EU prior to v2.0.4 improperly used the country code EL in this setting instead of the correct GR for Greece. On installation of v2.0.4 or later, any reference to EL will be automatically changed to GR … unless the GR country-code is already present in this setting.		 AT,BE,BG,CY,CZ,DE, DK,EE,GR,ES,FI,FR, GB,HR,HU,IE,IT,LT, LU,LV,MT,NL,PL, PT,RO,SE,SI,SK
Enable storefront processing? The VAT4EU processing is enabled when this setting is "true" and you have also set Configuration :: Customer Details :: Company to true. false
VAT Number required? Identify whether (true) or not (false) customers' addresses in your store require a VAT Number entry. false
Minimum VAT Number Length Identify the minimum length of an entered VAT Number, used as a pre-check for any input value. Set the value to 0 to disable this check. The "VIES" validation service will be the final arbitrator of the number's validity! 10
Enable VAT Refund for in-country purchasers? Identify whether or not billing addresses within your store's country with a validated VAT Number qualify for a VAT refund. false
VAT Number Validation Identify the method to use when validating a VAT Number, either:
  1. Admin. All VAT Number validation is performed under admin-control. When a customer adds or updates the VAT Number associated with one of their addresses, that address does not qualify for any VAT Refund until the admin takes action.
  2. Customer. When a customer enters or updates a VAT Number, the plugin uses the VIES validation service to immediately see if that value is valid. If valid and the customer uses that address as an order's billing-address, they receive a VAT Refund on qualifying orders. Otherwise, admin-validation is required prior to any refund.
 Admin
VAT Number: Unvalidated Indicator Identify the character(s) to be appended to any VAT Number display when that number has not been validated and, thus, cannot be used to receive any VAT Refund. *
Enable debug? Choose whether the plugin's debug is enabled. When enabled, each:
  • VAT-validation request/response is logged in /logs/VatValidate.log.
  • Admin action is logged in /logs/vat4eu_adm_xxx.log, where xxx is the admin's ID value.
  • Customer action is logged in /logs/vat4eu_xxx.log, where xxx is the customer's ID value.
 false
Sample order-total display

VAT4EU provides two (2) order-total modules that activate when an order qualifies for a VAT Refund; use your admin's Modules :: Order Total tool to "Install" each of these modules:

  1. ot_vat_refund. This order-total negates any tax associated with the order. Its Sort Order must be after that associated with your store's ot_tax for proper operation.
  2. ot_vat_reverse_charges. This order-total adds a disclaimer to the order, indicating that "VAT reverse charges" are in effect. Its Sort Order must be after that associated with your store's ot_total for proper operation.

The image illustrates a sample order-total block for an order that qualifies the purchaser for a VAT Refund, essentially backing-out any tax-related charges for the order and adding the "reverse charge" disclaimer.

The following configuration settings are also required for full VAT4EU customization:

  1. Configuration :: My Store :: Store Address and Phone. Update this value to include your store's VAT Number for display on invoices and packing-slips.
  2. Configuration :: Customer Details :: Company. Ensure that this value is set to true. VAT4EU inserts its "VAT Number" fields within the Company block of any entered address. If not set to true, a VAT Number will never be entered!

If you haven't already set up the taxes for your store, now is the time!.

Note: I am neither an accountant nor a tax attorney; the configuration suggested here is, I believe, the minimum required for the EU MOSS Scheme. Please consult your tax authority for verification!

Configure Your Store

First, you'll need to configure your store's base settings using your admin's Configuration :: My Store:

  1. Country. Choose your EU-based country from the drop-down list.
  2. Basis of Product Tax. Set this value to Shipping.
  3. Basis of Shipping Tax. Set this value to Shipping.
  4. Display Prices with Tax. Set this value to true.
  5. Display Prices with Tax in Admin. Set this value to true.

Define Tax Zones

Next, you'll define the taxable "zones" to be used for your store, using your admin's Locations / Taxes :: Zone Definitions tool. This section identifies the minimum requirements for this setup, assuming that you will be charging the same VAT rate for all taxable products shipped within the European Union, including your store's country.

  1. Click the "Insert" button and …
    1. Set the Zone Name to European Union.
    2. Set the Description to EU Countries.
    3. Click the "Insert" button to save that definition.
  2. Click the "Details" button associated with the European Union zone and for each country currently in the EU…
    1. Click the "Insert" button.
    2. Choose the country name from the Country drop-down.
    3. Leave the Zone selection as All Zones.
    4. Click the "Insert" button to save that zone definition.
    When you have added all the EU countries to the list, click the "Back" button.
  3. Click a "Tax Rates" button, then the "New Tax Rate" button and …
    1. Choose the Tax Class Title, e.g. Taxable Goods, from the drop-down.
    2. Choose European Union from the Zone drop-down.
    3. Identify the associated Tax Rate (%) value; for a 25% tax, you'll enter 25.
    4. Enter the Description of the tax. Remember that this value is displayed to the customer, so enter something like EU VAT (25%), inc (assuming that you're using a 25% rate).
    5. Click the "Insert" button to save that tax-rate definition.

This section identifies the visual changes made to your store (both admin and storefront) once the VAT4EU plugin is installed and configured.

Admin Customers Listing

VAT4EU integrates with your admin's Customers :: Customers listing display, identifying which customers have supplied a VAT Number and the validation-status of each. Clicking on the Asc or Desc links for the "VAT Number" column sorts the display based on the status of the associated VAT Number.

When sorted in Asc order, the customer records are displayed in the following status-order:

  1. Validated via Admin Override, shows
  2. Validated via VIES, shows
  3. Not Validated, shows
  4. Deemed Invalid by VIES, shows
Admin Customers Details

When you click on the "Edit" button associated with a customer, the information-gathering page now includes fields where you can enter (or correct) a customer's VAT Number entry. If that VAT Number can't be automatically verified by the VIES service, there's a VAT Validation Override checkbox; ticking that box will allow the customer to create an order that qualifies for a VAT refund.

Customer Order Display

VAT4EU also updates your admin's Customers :: Orders display (as well as the display for any Invoice or Packing-slip) to include the VAT Number associated with the billing address for the order.

Order-Total Block Display

When a customer places an order with a validated VAT Number, VAT4EU's order-total modules update the order's "order-total" block to identify that the VAT has been removed from the order and includes a "reverse charge" disclaimer. This change is visible both in the storefront and the admin post-order displays.

Sample VAT Number Entry

When VAT4EU is installed, the address-entry form on the following pages is modified, inserting the VAT Number field following the Company Name field as shown in the sample image.

  1. address_book_process
  2. checkout_payment_address
  3. create_account
  4. login

The What's this? link, when clicked, displays a popup window that illustrates the varied VAT formats for the EU countries. That information is a re-formatted version of the information on the VIES website, and is current as of 2024-03-03. The content is provided by /includes/languages/english/html_includes/define_popup_vat4eu_formats.php.

Note: The VAT Number input will be added only if you have set Configuration :: Customer Details :: Company to true!

Sample address blocks

Each customer address-block in the storefront display is also modified, adding any VAT Number associated with a customer's billing address. The sample image shows this rendering for the checkout_confirmation page. The following Zen Cart pages are included in this processing:

  1. address_book
  2. account_history_info
  3. checkout_confirmation
  4. checkout_one (Part of the One-Page Checkout plugin)
  5. checkout_one_confirmation (Part of the One-Page Checkout plugin)
  6. checkout_payment
  7. checkout_payment_address
  8. create_account_success

VAT4EU integrates with Edit Orders, version 4.7.0 or later. That version of EO provides additional notifiers that allow VAT4EU's operations and supports zc158+ installations. You'll need to install EO separately.

If you have additional plugins installed that also "want to" include the VAT Number display in an address block, VAT4EU has you covered! Both the storefront and admin processing issue a notification when a zen_address_format function call is made on a page that isn't in the VAT4EU built-in processing. An observer-class module can "attach" to that notifier and indicate (by setting the 3rd parameter to (boolean)true to indicate that the VAT Number should be included in that address block.

    $this->notify('NOTIFY_VAT4EU_ADDRESS_DEFAULT', $address_elements, $current_address, $show_vat_number);

You can view the details of these changes on the plugin's GitHub repository.

  • v3.2.0, 2024-03-06 (lat9, webchills):
    • BUGFIX: Correct text hidden on VAT4EU help-text pop-up.
    • BUGFIX: Correct PHP Warning (PHP 8.0) on initial installation.
    • BUGFIX: Correct unwanted customer message regarding VAT number validation.
    • BUGFIX: Remove deprecated (and unneeded) notification from admin observer's watch-list.
    • CHANGE: Drop support for Zen Cart versions prior to 1.5.8a.
    • INTROP: Account for zc158a+ changes in address-handling in the Customers :: Customers tool.
    • BUGFIX: Correct missing PHP Warning when editing a customer in the admin.
    • BUGFIX: Pre-define all class properties; PHP 8.2+ requirement.
    • INTROP: Account for zc158a+ changes in storefront notifications.
    • INTROP: Major storefront restructuring, based on a couple of zc200 changes.
    • INTROP: Add full support for One-Page Checkout, v2.4.6 and later.
    • CHANGE: Modify the uninstall-SQL script so that it works when run under the admin's Install SQL Patches tool.
    • BUGFIX: Include any 'VAT Number' entered in the address on the create_account_success page.
    • CHANGE: Limit pages on which the message about an unvalidated VAT Number is displayed.
    • BUGFIX: Invalid characters in a submitted VAT Number aren't flagged as an error.
    • CHANGE: Provide integration with the Bootstrap template, v3.6.3 or later.
    • CHANGE: Drop support for Edit Orders versions prior to 4.7.0.
    • The following files were changed, added, or removed:
      1. /docs/vat4eu/uninstall/uninstall_vat4eu.sql
      2. /includes/classes/VatValidation.php
      3. /includes/classes/observers/auto.vat_for_eu_countries.php
      4. /includes/languages/english/extra_definitions/lang.vat4eu_extra_definitions.php
      5. /includes/languages/english/extra_definitions/vat4eu_extra_definitions.php
      6. /includes/languages/english/html_includes/define_popup_var4eu_formats.php
      7. /includes/languages/english/modules/order_total/lang.ot_vat_refund.php
      8. /includes/languages/english/modules/order_total/lang.ot_vat_reverse_charges.php
      9. /includes/languages/english/modules/order_total/ot_vat_refund.php
      10. /includes/languages/english/modules/order_total/ot_vat_reverse_charges.php
      11. /includes/modules/order_total/ot_vat_refund.php
      12. /includes/modules/order_total/ot_vat_reverse_charges.php
      13. /includes/templates/bootstrap/css/popup_vat4eu_formats.css
      14. /includes/templates/bootstrap/templates/tpl_modules_common_address_format.php
      15. /includes/templates/bootstrap/templates/tpl_modules_create_account.php
      16. /includes/templates/bootstrap/templates/tpl_modules_opc_address_block.php
      17. /includes/templates/template_default/css/popup_vat4eu_formats.css
      18. /includes/templates/template_default/templates/tpl_modules_vat4eu_display.php
      19. /includes/templates/YOUR_TEMPLATE/css/popup_vat4eu_formats.css
      20. /YOUR_ADMIN/includes/classes/observers/Vat4EuAdminObserver.php
      21. /YOUR_ADMIN/includes/init_includes/init_vat4eu_admin.php
      22. /YOUR_ADMIN/includes/languages/english/extra_definitions/lang.vat4eu_extra_definitions_admin.php
      23. /YOUR_ADMIN/includes/languages/english/extra_definitions/vat4eu_extra_definitions_admin.php
  • v3.1.1, 2022-04-28:
    • BUGFIX: Correct integration with "Edit Orders", v4.6.0+ — notifications changed.
    • BUGFIX: Use zen_cfg_read_only so that the plugin's version/release date don't get updated on a configuration update.
    • BUGFIX: Correct incorrect message to customer that indicates that their VAT number requires validation.
    • The following files were changed:
      1. /includes/classes/observers/auto.vat_for_eu_countries.php
      2. /YOUR_ADMIN/includes/classes/observers/Vat4EuAdminObserver.php
      3. /YOUR_ADMIN/includes/functions/extra_functions/zen_cfg_read_only.php (Added)
      4. /YOUR_ADMIN/includes/init_includes/init_vat4eu_admin.php
  • v3.1.0, 2021-11-19:
    • CHANGE: Various refactors; the minimum PHP version supported is now PHP 5.6.0.
    • CHANGE: Since Brexit, 'GB' is no longer a VAT4EU country; it's now auto-removed from configuration.
    • CHANGE: Use zen_is_logged_in() and zen_is_guest_checkout() to determine logged-in status; only logged-in customers can have validated VAT numbers.
    • The following files were changed:
      1. /includes/classes/VatValidation.php
      2. /includes/classes/observers/auto.vat_for_eu_countries.php
      3. /includes/languages/english/html_includes/define_popup_vat4eu_formats.php
      4. /YOUR_ADMIN/includes/languages/extra_definitions/vat4eu_extra_definitions_admin.php
      5. /YOUR_ADMIN/includes/init_includes/init_vat4eu_admin.php
  • v3.0.1, 2020-07-24:
    • BUGFIX: Access VIES WSDL via https protocol.
    • The following files were changed:
      1. /includes/classes/VatValidation.php
      2. /YOUR_ADMIN/includes/init_includes/init_vat4eu_admin.php
  • v3.0.0, 2020-07-14:
    • BUGFIX: Correct PHP notice during account-creation.
    • BUGFIX: Apply numeric defaults to added numeric fields (strict MySQL).
    • CHANGE: The minimum Zen Cart version for an initial install is now zc156b as the non-template overwrites are now 'baked into' that release.
    • The following files were changed:
      1. /includes/templates/template_default/templates/tpl_modules_vat4eu_display.php
      2. /YOUR_ADMIN/includes/init_includes/init_vat4eu_admin.php
    • The following files were removed from this plugin's distribution, but shouldn't be removed from your store if you are upgrading from a previous version of VAT4EU:
      1. /includes/functions/functions_customers.php
      2. /includes/modules/pages/address_book_process/header_php.php
      3. /includes/modules/YOUR_TEMPLATE/checkout_address_book.php
  • v2.0.4, 2020-03-14:
    • BUGFIX: Correct checks for Greek VAT numbers.
    • BUGFIX: Correct PHP notice when VAT number shouldn't be added to an address.
    • The following files were changed:
      1. /includes/classes/VatValidation.php
      2. /YOUR_ADMIN/includes/classes/observers/Vat4EuAdminObserver.php
      3. /YOUR_ADMIN/includes/init_includes/init_vat4eu_admin.php
  • v2.0.3, 2020-03-02:
    • BUGFIX: Correct use of undefined function zen_html_quotes.
    • The following files were changed:
      1. /YOUR_ADMIN/includes/classes/observers/Vat4EuAdminObserver.php
      2. /YOUR_ADMIN/includes/init_includes/init_vat4eu_admin.php
  • v2.0.2, 2020-02-12:
    • BUGFIX: Correct PHP Warning when the VAT4EU order-totals are present, but not installed.
    • The following files were changed:
      1. /includes/modules/order_total/ot_vat_refund.php
      2. /includes/modules/order_total/ot_vat_reverse_charges.php
      3. /YOUR_ADMIN/includes/init_includes/init_vat4eu_admin.php
  • v2.0.1, 2020-01-09:
    • BUGFIX: Correct PHP Warning when One-Page Checkout is not also installed.
    • The following files were changed:
      1. /includes/classes/observers/auto.vat_for_eu_countries.php
      2. /YOUR_ADMIN/includes/init_includes/init_vat4eu_admin.php
  • v2.0.0, 2019-01-06: This version contains changes for the following issues:
    • CHANGE: Use zc156a as the basis for all changes.
    • The following files were changed or removed:
      1. /includes/functions/functions_customers.php
      2. /includes/modules/pages/address_book_process/header_php.php
      3. /includes/modules/YOUR_TEMPLATE/checkout_new_address.php
      4. /includes/templates/YOUR_TEMPLATE/templates/tpl_modules_create_account.php
      5. /YOUR_ADMIN/customers.php (Removed from this distribution; use the as-shipped zc156 version)
      6. /YOUR_ADMIN/includes/functions/functions_customers.php (Removed from this distribution; use the as-shipped zc156 version)
      7. /YOUR_ADMIN/includes/init_includes/init_vat4eu_admin.php
  • v1.0.1, 2018-06-10: This version contains changes for the following issues:
    • BUGFIX: Correct PHP Fatal error thrown when a VAT Number is rejected by the online service.
    • BUGFIX: Correct shipping/billing address additions "don't stick".
    • The following files were changed:
      1. /includes/classes/VatValidation.php
      2. /includes/classes/observers/auto.vat_for_eu_countries.php
      3. /includes/modules/YOUR_TEMPLATE/checkout_new_address.php
      4. /YOUR_ADMIN/includes/init_includes/init_vat4eu_admin.php
  • v1.0.0, 2017-10-23: Initial release.