Aimy Extensions
 

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

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
  • Automatic updates on new releases (for one domain and one year)
  • Support of Aimy Geo Tax for J2Store's further development
8.93€
(Incl. 19% tax)
Germany
* Unlimited installs - automatic 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 neccessary to be compliant with tax laws - for example EU VAT.

With the help of MaxMind's GeoIP, 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 neccessary.

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

Screenshots

  • price-tax-country
  • 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.y, 3.4.x recommended)
  2. J2Store (version 3.1.7 or up)
  3. PHP GeoIP extension (version 1.x.y, 1.1.y recommended)
  4. MaxMind's GeoIP "Country" or "Country Lite" database (legacy format)

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

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" → "Extensions Manager"
  4. Click on the "Browse" button and select the ZIP archive
  5. Click on the "Upload & Install" button

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

Usually the GeoIP database ("GeoIP.dat") is 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.

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 Database Information

Aimy Geo Tax for J2Store can use either MaxMind's commercial or lite country database. At the moment, only version 1 ("legacy") of the database format is supported as the support libraries that are commonly in use do not support the new format (version 2) yet.

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

http://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.

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.