Astound Commerce AvaTax Connector – A Magento Extension

Instructions and documentation for the Astound Commerce AvaTax Connector

Avatax 15

Table of Contents

  1. Overview
    1. Support
    2. Prerequisites
    3. Versions
  2. Getting Started Guide
    1. Installation
    2. Configuration
    3. Product Setup
    4. Customer Setup
    5. Additional information
  3. Technical Details
  4. Important Notes
  5. Common Problems


In Magento, tax calculation typically occurs during checkout but may also happen at other times as well (e.g., shopping cart). When the order is placed, it is not immediately recorded in AvaTax. Since Magento supports multiple invoicing and multiple credit memos for the same order, orders are not recorded as a whole in AvaTax. Tax amounts are calculated for the order when the customer places the order, but nothing is recorded in Avalara until a new invoice or credit memo is created.

A cron task is run every hour to send pending invoices and credit memos to AvaTax. The status of each pending item can be found in the AvaTax Order Sync Queue in Sales > Tax > AvaTax Order Sync Queue. The Magento cron task must be running at least every 15 minutes for the extension — and Magento — to work properly.


For support with your AvaTax account, please visit This software will not work unless you have a valid AvaTax account. To obtain the required account information, please contact your Avalara representative.



The latest version is 3.5.7 (February 07, 2018). It can be obtained via Magento Marketplace, Github or downloaded directly from our website.

The extension supports all current versions of Magento Community starting from 1.4 and Magento Enterprise starting from 1.12 There are also no known issues for all versions of Magento Professional.

Getting Started Guide

Step 1: Installation

In addition to the instructions below, you can watch this installation walkthrough video that show the complete installation on a Magento Community website.

Typical Installation Process
  1. If applicable, disable caching (System > Cache Management) and disable compilation (System > Tools > Compilation)
  2. Download the extension via Magento Connect
    1. Browse to System > Magento Connect > Magento Connect Manager and Log in
    2. Change to the Settings tab and set Preferred State to "Beta," then click Save Settings
    3. Change to the Extensions tab, paste in the Extension Key (magento-community/OnePica_AvaTax or depending on your Magento version), click Install, and confirm that you are shown a success message.
    4. Click Refresh to see the package successfully installed
    5. Click Return to Admin in the upper right
  3. Flush permissions: Log out of the admin and log back in
  4. Enable the cache, turn compilation back on, and recompile if you were previously using those features
Installation Process for Legacy Versions of Magento Professional & Magento Enterprise
  1. If applicable, disable caching (System > Cache Management) and disable compilation (System > Tools > Compilation)
  2. Download the latest version (see versions above)
  3. Extract the contents: Confirm the creation of:
    1. /app/etc/modules/OnePica_AvaTax.xml
    2. /app/code/community/OnePica/AvaTax/
  4. Enable the cache, turn compilation back on, and recompile if you were previously using those features

Step 2: Configuration

Within the Magento Admin, browse to System > Configuration > Sales/Tax. Click on AvaTax, the first item in the accordion menu. Screenshot | Video.

Connection Settings
Log & Queue Settings
Data Mapping
Shipping Address Options
Additional Magento Configurations

Step 3: Product Setup (optional)

Step 4: Customer Setup (optional)

Many store owners will not need to use this feature. Unless you have customers with special tax excemptions, you most likely do not need to set this up. If you are unsure, contact your AvaTax support representative for more information about how to use customer usage types.

Additional information

For more information download user guide.

Technical Details

There are three major functionalities with the AvaTax extension: address validation/normalization, tax rate lookups, and sending invoice/credit memo info to AvaTax.

Address validation/normalization

During checkout, shipping addresses are always sent to AvaTax for validation. The response returns a Boolean value to say if the address is valid, a Boolean value to say if enough of the address is valid to calculate tax (even if not all of it is), a normalized form of the address, and any possible error messages.

If address validation is enabled in the admin, the customer must provide a valid address before continuing. If address validation is turned off, the address validation call is still made to ensure the address is valid enough for AvaTax to calculate tax later. Typically, this just means the state and zip code match. There is no way to disable this basic validation check.

If address normalization is enabled in the admin, the normalized address that is returned from the validation check replaces the address provided by the customer.

See: OnePica_AvaTax_Model_Avatax_Address

Tax rate lookup

When a sales quote wants to calculate rate, the quote items are sent to AvaTax to get tax rates. These rates are cache in the customer’s sessions, but if anything in the quote changes, the rates are refreshed. Nothing in AvaTax is recorded at this point.

See: OnePica_AvaTax_Model_Avatax_Estimate

Tax calculation settings

For more information download Tax Calculation settings information.

Sending order info to AvaTax

Whenever an invoice or credit memo is created, the data is added to the AvaTax Sync Queue. Every hour, on the hour, all pending data is passed to the AvaTax system to record purchases and returns. This is the only time order data is saved to AvaTax and will appear in the store owner’s dashboard.

See: OnePica_AvaTax_Model_Avatax_Invoice

List of hidden and overriden settings (actual for 3.2.1 and higher)

Sales > Tax > Tax Classes section
Sales > Tax > Calculation Settings section
Sales > Tax > Price Display Settings section
Sales > Tax > Orders, Invoices, Credit Memos Display Settings

Important Notes

Common Problems

Q: I can see tax rates during checkout, but nothing shows up in my AvaTax dashboard.
A: Most likely this is because the Magento cron is not running. For details on how to set up the cron, please see
Q: When am getting a "Doc status invalid" error message when creating a new invoice or credit memo.
A: Usually this is a problem when a system is attempting to commit to AvaTax a document with an ID that conflicts with one that's already there. Most of this time, this occurs when more than one installation of Magento with the AvaTax extension is communicating with a single "company" in the AvaTax account. This almost always happens in the build up to launch of a site as multiple systems are connecting to the same AvaTax "company" for testing.
Q: I think I have an old version of the Astound Commerce AvaTax Magento Extension. What is the current version and how can I upgrade mine?
A: The current version can be found on Magento Connect. You can upgrade the extension via Magento Connect within your installation. If you have a legacy versions of Magento Professional or Magento Enterprise without Magento Connect, you can download the latest version of the extension from our website at
Q: I am getting tax rates in the cart and orders are showing up in the AvaTax Dashboard, but they are always in an uncommitted state.
A: There is an option in the admin config section that would (correctly) make this happen. Check to see if admin condiguration option Action (detailed here) is set to "Enable: calculate tax, sumit data" instead of "Endable: calculate tax, submit data, and commit"
Q: When AvaTax extension is enabled, Manage tax zones and Rates options from Sales > Taxes, some Calculation Settings and Tax Classes from System > Configuration > Sales > Tax disappear from Magento admin.
A: AvaTax extension hides these options "by design" as far as all tax calculation goes through AvaTax service rather than Magento. AvaTax extension overrides some default Magento functionality and requires certain values to be set in tax settings. Thus these options should be hidden to avoid confusing customer, when he tries to change settings but there is no effect on tax calculation results. If AvaTax extension is disabled for at least one store/website, then these options are available for this particular store/website. See more in List of hidden and overriden settings