Aimy Geo Tax for J2Store for Joomla!

You currently have JavaScript disabled.
In order to use all features provided on this website, please enable JavaScript in your browser!

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.

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

9.52€

(Incl. 19% tax)

Germany

* Unlimited installs - updates for number of domains:

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 PHP GeoIP extension or 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

Documentation

User Manual

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:

Joomla! (version 3.x.y, 3.4.x and up recommended)
J2Store (version 3.1.7 or up)
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)
3. Akeeba GeoIP Provider Plugin (version 2.0.0 or up)

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. Otherwise, install the Akeeba GeoIP Provider Plugin (Joomla! system plugin) and make sure to enable it after installation.

We recommend using the PHP MaxMind-DB extension.

Installation

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

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

Download the extension's ZIP archive
Log into your Joomla! backend as "Super User"
From the menu, choose "Extensions" → "Manage" → "Install"
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:

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.

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:

  <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:

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

Copyright & Trademark Notice

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.

Aimy Geo Tax for J2Store