X-Cart:AvaTax

Overview

X-Cart's AvaTax module allows you to integrate your X-Cart based store with AvaTax, the market leading sales tax automation service by Avalara. It is a built-in module available in all X-Cart editions starting from X-Cart version 4.6.

Avalara's AvaTax is a SaaS offering that can simplify your tax compliance process. Doing sales tax right is not an easy task, and here Avalara takes much of the burden off your shoulders. AvaTax calculates sales tax accurately to the rooftop level and supports varying tax rules for thousands of products and services. It easily accomodates changes in the taxing system, so you can be sure you are up-to-date with the most recent tax rates and rules at all times. Address validation service is included, so you always get the most accurate tax calculation results.

Here's what it looks like in X-Cart:

At checkout, tax calculation results delivered by AvaTax appear in the Order summary section:

Address validation is available for addresses entered in the store's Customer area. On the one hand, address validation can be performed on addresses that are entered initially or updated when a customer adds or updates address information in their profile. If the address entered contains ambiguous data and cannot be resolved by AvaTax as is, an error message indicating the problem is returned:

On the other hand, address validation occurs implicitly when a customer goes to checkout and AvaTax service is called upon to calculate sales tax. If the address cannot be resolved in this case, the respective error message appears at the top right of the page:

Video

US Sales Tax webinar with Avalara - July 23rd 2013

System requirements

PHP SOAP extension is required.

Quick Start

To enable AvaTax at your X-Cart store, follow these steps:

1. Get an account with Avalara and activate it: log in to the Admin Console at https://admin-development.avalara.net (for Development Accounts) or https://admin-avatax.avalara.net (for Production Accounts) using your user id and password. After successful account activation you will be provided with your account number and license key. Please be sure to record them for future use: the account number and license key are needed for API access, and you will need to enter them on the AvaTax module configuration page in your X-Cart store.
2. In the Avalara Admin Console, configure your company settings and tax profile:
   
   Note: You can get started by clicking Get Started on the navigation bar when the Home tab is selected. Detailed information on configuring your Avalara account can be found in AvaTax WebHelp (available via a link in the Avalara Admin Console). Avalara self learning course for the Admin Console can be found at http://www.avalara.com/avauniversity/avalarauniversity.
   1. Specify your company details (This includes setting a "Company Code" for your X-Cart store - you will need to enter it on the AvaTax module configuration page in X-Cart).
   2. Select Nexus Jurisdictions (where your company needs to calculate sales and use tax due to "substantial physical presence" in a taxing jurisdiction).
   3. Create tax codes and specify distinctive tax rules as needed for your store. For example, if certain products at your store need to be listed as non-taxable, or if you need to have specific rates for different products, this needs to be configured in your Avalara account.
      
      Note: Avalara provides hundreds of pre-defined tax codes (AvaTax System Tax Codes) and thousands of pre-configured related tax rules for AvaTax Pro subscribers. Instead of creating custom tax codes and tax rules, AvaTax Pro subscribers can take advantage of these tax codes and rules.
3. Enable AvaTax in your X-Cart store:
   1. Enable X-Cart's AvaTax module (See Enabling X-Cart's AvaTax module).
   2. Configure the module (See Configuring X-Cart's AvaTax module).
   3. Test that the module can connect to Avalara's service (See Testing AvaTax connection).
   4. Map the products in your store's catalog to specific AvaTax tax codes (See Mapping products to tax codes).

Enabling X-Cart's AvaTax module

To enable the module, follow these steps:

1. In Admin area, go to the Modules section (Settings menu->Modules).
2. Locate the entry for 'AvaTax' module.
   
   Note: In X-Cart versions 4.6 and later, the AvaTax module would be found on the 'Built-in and installed modules' tab under the 'Taxes' tag.
3. Select the Enable check box to the left of the module name.
   The module will be activated.
   
   

Configuring X-Cart's AvaTax module

After the AvaTax module has been enabled in your store, you should check and adjust its configuration:

1. In the Modules section (Settings menu->Modules), click the Configure link opposite the module name ('AvaTax').
   The module configuration page (titled by the name of the module) opens.
   
2. Adjust the settings on the module configuration page. Detailed information regarding the AvaTax module configuration settings is available below.
3. Click the Apply changes button to save the changes.

AvaTax module configuration settings

Here is an explanation of the AvaTax module configuration settings:

• Account number: The account number given to you from your Avalara Admin Console. This is a ten-digit number (e.g. 1100012345) which is used to authenticate your API call.
• License Key: The license key given to you from your Avalara Admin Console. This is a 13-character string (e.g. 1A2BC3D4E5F6G7).
• Company code: The company code you specified for the store in the Avalara Admin Console.
• Enable tax calculation: This setting allows you to enable/disable the use of Avalara's tax calculation services for your store.
• Enable address validation: This setting allows you to enable/disable the use of explicit address validations via AvaTax web service. When in use, explicit address validations are performed as stand-alone address validation calls to validate addresses that are entered initially or edited (for example, when a customer creates or edits their profile). Use of explicit validations is not required, but recommended. Disabling the option 'Enable address validation' does not disable the implicit address validatations that occur during a tax calculation - these take place in any case, regardless of whether the 'Enable address validation' option is enabled or not.
• Development mode: If you have a development account, you can enable this option to test the integration. For testing, be sure to use your development account number and license key in the 'Account number' and 'License Key' fields above. Note that in development mode tax calls will be made to https://development.avalara.net - as opposed to the production mode, where the URL https://avatax.avalara.net is used.
• Calculate taxes for US and Canada only: If you need taxes to be calculated only for the U.S. and/or Canada, it is recommended to keep this option enabled so as not to make unnecessary calls to Avalara's servers for addresses in other countries.
• Calculate taxes for US in designated states only: If you need taxes to be calculated only for a few specific states in the U.S., it is recommended to list these states here. Simply add the two-letter state codes for the states you require, one per row.
  For example:
  CA
  CT
  This will prevent calling Avalara for addresses in other states.
• Only validate addresses in: Use this setting to specify the locations for which you will use Avalara's address validation service. Avalara currently supports address validation only for the United States and Canada, so you can select United States, Canada or Both.

Testing AvaTax connection

After adjusting the configuration settings for AvaTax module in X-Cart's Admin area, use the button located at the bottom of the AvaTax module configuration settings page in X-Cart to test the connection to the AvaTax service. Provided that the module has been configured corrrectly, you should see the Success message displayed at the top of the screen:

Mapping products to tax codes

To ensure the correct choice of taxing scenario for each transaction in your store, you must map the products in your catalog to the tax codes defined in AvaTax system. The mapping is done individually per SKU. If you open any product for editing in the store's back end, on the 'Product details' page you will find the AvaTax tax code field:

The tax code that has been defined for the respective type of products in Avalara goes into this field.

Note that the Tax exempt field located below the AvaTax tax code field on the 'Product details' page has no connection with AvaTax functionality. If a certain product needs to be tax exempt in a jurisdiction, it is recommended to define it as a tax rule in AvaTax system rather than rely on the Tax exempt field in your X-Cart store.