Aimy Geo Tax for J2Store is a plugin that improves usability and tax compliance of your J2Store shop. It automatically detects the customer's country based on his IP address and selects the tax rate accordingly.

English German Dutch Dari (Afghanistan)

Features

  • Automatically select visitor's country & tax rate by IP address
  • Use default country as a fallback if country is not detected (optional)
  • Show country flags (241 country flags included) (optional)
  • Show country name (optional)
  • Easy to customize and style using CSS
  • Updates on new releases (per domain(s) for one year - 15 months on renewal)
  • Support of Aimy Geo Tax for J2Store's further development
14.28€
(Incl. 19% tax)
Germany
* Unlimited installs - updates for number of domains:

Aimy Geo Tax

How does it work?

With this plugin you can show tax values and rates according to the country your visitor comes from. This may be necessary to be compliant with tax laws - for example EU VAT.

With the help of MaxMind's GeoIP (via the MaxMind DB Reader PHP API, PHP GeoIP extension or the obsolete Akeeba GeoIP Provider plugin), the country is detected based on the visitor's IP address. If the IP address cannot be detected or belongs to a country that you did not add in your shop configuration, a default can be used as a fallback.

Your customers may change the country during the checkout process if necessary.

Tax rates, tax rules, supported countries and similar options are all set as usual in your J2Store configuration.

Screenshots

  • Automatically Selected Tax Rate
  • J2Store Configuration

Documentation

User Manual

PDF

Introduction

Aimy Geo Tax for J2Store adds one useful feature to your shop: the detection of the geographic region each customer is coming from, based on his IP address.

This information is used to internally set the user's country (billing address) before a cart checkout. Besides that the tax and tax rate displayed by J2Store is customized to fit the user's location automatically and right away.

Aimy Geo Tax for J2Store comes with a set of 241 country flags and allows both country flags and country names to be shown next to the tax rate.

This manual guides you through all steps necessary to install and use the plugin.

Requirements

In order to use Aimy Geo Tax for J2Store, you have to meet the following technical requirements:

  1. Joomla! (version 3.x or version 4.x (recommended))
  2. J2Store (version 3.1.7 or up or version 4.x (recommended))
  3. one of the following:
    1. PHP MaxMind-DB extension (1.11.0 or up recommended) and either

      MaxMind's GeoIP2 "Country" or GeoLite2 "Country" database

      or

      DB-IP's "IP to Country" or "IP to Country Lite" database in MMDB format

    2. PHP GeoIP extension (version 1.x.y, 1.1.y or up recommended) and

      MaxMind's GeoIP "Country" or "Country Lite" database (legacy format)

To find out whether your PHP setup already includes the PHP GeoIP extension, log in to your Joomla! backend and click "System" → "System Information" → "PHP Information". Have a look for a "geoip" or "maxminddb" heading - if present, the PHP extension is already installed and ready for use.

We recommend using the PHP MaxMind-DB extension.

NOTE: The legacy Akeeba GeoIP Provider Plugin (Joomla! system plugin) is still supported by Aimy Geo Tax for J2Store but its usage is not recommended as it is not maintained anymore.

Installation

The installation of the extension follows the common Joomla! procedures.

In case you are not familiar with these procedures, proceed as follows:

  1. Download the extension's ZIP archive
  2. Log into your Joomla! backend as "Super User"
  3. From the menu, choose "Extensions" → "Manage" → "Install"
  4. Click on the "Or browse for file" button and select the ZIP archive

The extension's archive will be uploaded and installed afterwards.

For further information, please have a look at the Joomla! documentation "Installing an Extension".

NOTE: All plugins are disabled by Joomla! when installed for the first time. To enable Aimy Geo Tax for J2Store, proceed and configure the plugin.

Configuration

After a fresh installation, click on the "Configure plugin now" button on the installation report page.

At any time, you can configure the Aimy Geo Tax for J2Store plugin using J2Store's Applications Manager ("Apps" menu item). Click the "Open" button to load Aimy Geo Tax for J2Store's configuration dialog.

Enabling the Plugin

In order to use the plugin's functionality, you have to enable it first.

Go to J2Store's Applications Manager and click the "Enable" button in Geo Tax for J2Store's box.

Plugin Options

Aimy Geo Tax for J2Store's functionality can be suited to your needs using the following configuration options:

Configuration
Show Country Flags

If enabled, a flag of the user's originating country will be shown near the tax information.

Show Country Names

If enabled, the name of the user's originating country will be shown near the tax information.

Default Country

If set to "Shop's Country" the country your shop is located in will be used as a fallback. This information is retrieved from the setting you did in J2Store's configuration.

To disable setting a fallback country, choose "None".

We recommend keeping the default setting as is, that is, using the shop's country as a fallback.

Custom GeoIP Path

This option is only evaluated if the PHP GeoIP or PHP MaxMind-DB extension is used as a GeoIP provider.

If the PHP GeoIP extension is used as a GeoIP provider, the GeoIP database ("GeoIP.dat") is usually installed in a default directory and picked up from there by the libraries which use the database automatically.

If you did install your database into a custom directory and have the geoip PHP extension in a version above or equal to 1.1.0 installed, enter your custom path in the input field.

If you use a version lower than 1.1.0. edit your php.ini and set the configuration directive "geoip.custom_directory" to point to your directory.

If the PHP MaxMin-DB extension is used as a GeoIP provider, entering the path of the directory that holds the MMDB databases is required. Aimy Geo Tax for J2Store will then try to locate the correct file automatically. However, you can enter the complete path of a MMDB file as well.

Test IP

For testing purposes you can enter an arbitrary IP address that will be passed to the GeoIP provider instead of the real visitor's IP address.

Make sure to disable this option after testing and delete your frontend session cookie afterwards.

After setting up these options to suite your shop's and setup's needs, Aimy Geo Tax for J2Store is ready for use.

Shop Settings

Aimy Geo Tax uses the settings and data you configured in J2Store itself, for example: Countries, Geozones, Tax rates or Tax profiles.

You may use the plugin with net or gross prices.

GeoIP Provider

Aimy Geo Tax for J2Store automatically tries to determine which provider to use on your website. First, Aimy Geo Tax for J2Store looks for a usable installation of the PHP MaxMind-DB or GeoIP extensions. If both cannot be found on your webhost, a check for the Akeeba GeoIP provider plugin is done.

GeoIP Database Information

PHP MaxMind-DB extension used

Aimy Geo Tax for J2Store can use MaxMind's or DB-IP's commercial or lite country database in version 2 ("MMDB") database format.

For more information, visit:

https://www.maxmind.com/en/geoip2-country-database

and/or

https://db-ip.com/db/

Linux users may install this database using their distribution's package manager as well. If in doubt, ask your webmaster or system administrator which way fits your setup best.

Keep in mind to update your copy of the GeoIP2 country database regularly.

PHP GeoIP extension used

Aimy Geo Tax for J2Store can use either MaxMind's commercial or lite country database in version 1 ("legacy") database format.

To get more information on the country lite database and download your copy, follow this link:

https://dev.maxmind.com/geoip/legacy/geolite/

Linux users may install this database using their distribution's package manager as well. If in doubt, ask your webmaster or system administrator which way fits your setup best.

Keep in mind to update your copy of the GeoIP country database regularly.

Akeeba GeoIP Provider Plugin used

The GeoIP database bundled with the extension is used.

NOTE: The plugin is obsolete and not maintained anymore.

Country Selection Algorithm

Aimy Geo Tax for J2Store uses the following sequence of checks to set the internally used billing address' country to the one of the user visiting your website:

User set his country already?

If the user is a recurring one and already set his country information before, this authoritative setting will still be present in the user's session. Aimy Geo Tax for J2Store will keep this information as is and just load the matching language name and flag if configured to.

GeoIP lookup?

Otherwise: If the user's IP address has a matching entry in the GeoIP database, the country code is retrieved.

If you did enable the user's country in J2Store, the country information (name & flag) is loaded and the billing address' country is set to the retrieved one.

Fall back to shop's country as a default?

Otherwise: If you did set "Default Country" to "Shop's Country" in Aimy Geo Tax for J2Store's settings, the shop's country will be used to set the billing address' country and country information will be loaded accordingly (name & flag) as a fallback.

The tax and tax rate are then calculated as appropriate by J2Store before being displayed to the user. The country's name and flag will be added if set in Aimy Geo Tax for J2Store's configuration.

Note: In any case, the setting of the user within the checkout process will finally decide on the calculation of the tax rate.

Styling Country Information Using CSS

The following code shows an example HTML snippet of a product's price information including tax rate and country information:

Country name & flag
  <div class="product-price-container-wrapper">
    <div class="product-price-container">
      <div class="sale-price">25.00€</div>
      <div class="tax-text">(Incl. 19% tax)</div>
    </div>
    <div class="tax-country tax-country-de">Germany</div>
  </div>

The class "tax-country-XX" is used to add the country's flag to the div element (as a background image), XX denotes the two letter ISO 3166-1 country code, in this example "de" for Germany. Any code required to handle and place the flags is provided by Aimy Geo Tax for J2Store and loaded automatically if "Show Country Flags" is enabled.

You are free to apply styling as appropriate for your website by extending your template's CSS code.

The default style applied is as follows (excluding the tax-country-XX classes):

  .tax-country
  {
      display:             inline;
      padding-left:        24px;
      background-color:    transparent;
      background-repeat:   no-repeat;
      background-position: center left;
  }

Debugging

Aimy Geo Tax for J2Store does provide a debugging mode that is enabled by setting "Debug System" to "Yes" in Joomla!'s "Global Configuration" ("System" tab).

If enabled, a short notice will be shown about which country has been selected for a request and by which source it has been determined:

Debugging output

We recommend using the debugging output for testing purposes on a staging system only.

The Joomla!® name and logo are trademarks of Open Source Matters, Inc. in the United States and other countries.

MaxMind, GeoIP and related trademarks are the trademarks of MaxMind, Inc.

The included country flags are taken from Mark James' "Flag Icons" icon set kindly made available at http://www.famfamfam.com/lab/icons/flags/.

Mentioned hard- and software as well as companies may be trademarks of their respective owners. Use of a term in this manual should not be regarded as affecting the validity of any trademark or service mark. A missing annotation of the trademark may not lead to the assumption that no trademark is claimed and may thus be used freely.