One Pica AvaTax Connector – A Magento Extension

Instructions and documentation for the One Pica AvaTax Connector

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
  3. Technical Details
  4. Important Notes
  5. Common Problems

Overview

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.

Support

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

Prerequisites

Versions

The latest version is 2.4.3.1 (May 16, 2013). It can be obtained via Magento Connect or downloaded directly from our website.

The extension supports all current versions of Magento Community after 1.2 and current versions of Magento Enterprise after 1.5. 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 1.4.1.0 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 http://connect20.magentocommerce.com/community/OnePica_AvaTax 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.

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

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

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 magentocommerce.com.
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 One Pica 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 onepica.com/magento-extensions/avatax.
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"