Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Optimizely <<product-name>>'s integration with the Avalara Tax Calculator places the power of the Avalara Tax Calculator on your site. Avalara Tax Calculator includes the following features:

  • Identifies product taxability

  • Applies current, most up-to-date tax rules and regulations

  • Verifies tax holiday status

  • Applies sourcing rules (where taxable)

See [Calculate sales tax, VAT, and GST across industries, borders, and tax types](🔗).


<<product-name>> 4.4 includes updates to Avalara settings and code. See Setting Up Avalara as the Tax Calculator article to review the setting changes, and also review the Critical Considerations when Upgrading to 4.4.0 article for information on code changes.


To successfully implement the Avalara Tax Calculator for a <<product-name>> website, an Avalara AvaTax API account needs to be set up and configured. See Tax compliance done right with [Avalara's API](🔗).

## Enable and configure Avalara as the tax calculator

  1. Go to **Admin Console** \> **Administration** \> **System** \> **Settings**.

  2. Search for **Tax Calculator**.

  3. Select **Avalara** from the menu.

  4. After selecting **Avalara**, a list of additional fields, under the heading of **Avalara Tax Calculator**, will display. These settings are described both below and within Admin Console.

<table class="TableStyle-Borders" style="width: 100%; margin-left: 0; margin-right: auto;" data-cellspacing="0"> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <thead> <tr class="header TableStyle-Borders-Head-Header1"> <th class="TableStyle-Borders-HeadE-Regular-Header1">Setting Name</th> <th class="TableStyle-Borders-HeadD-Regular-Header1"><p>Description/Notes</p></th> </tr> </thead> <tbody> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Company Code</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1">The Company Code is created when creating an Organization within the Avalara account. This Code is used by <<product-name>> when calling the Avalara Api to point to a particular organization.</td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Discount Freight On Order</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1">If True, the freight discount will be added to the total order discount for tax calculations. Freight charges should be taxable based on configuration settings in Avalara. The freight discount will only have a value when a promotion with result type "Discount Amount Off Shipping" or "Discount Percent Off Shipping" is applied.</td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Freight Tax Code</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1">The setting value in this field is added to the freight line in taxRequest as TaxCode. Based on Avalara, the Tax Code is a unique identifier associated with items or tax rules to create custom taxing situations.</td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Account</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>The account number for your Avalara account. This will be a ten digit number.</p> <p>This information is provided by Avalara</p></td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>License Key</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>The license key required to connect to Avalara. This is a 16 character string provided by Avalara</p></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Send Live Transactions</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>Determines if tax will be calculated using the development server or the live server. Default value: No</p></td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Post Taxes on Order Submit</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>If <strong>Yes</strong>, taxes will be posted to Avalara on order submit. Default value: <strong>No</strong></p></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1">Log Transactions</td> <td class="TableStyle-Borders-BodyD-Regular-Row1">If enabled, transaction logs will be saved to the application log to assist with troubleshooting. To prevent large numbers of application logs this should only be used for debugging purposes. It will capture the call context, time of the request and the response. Default is value is <strong>No</strong></td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td colspan="2" class="TableStyle-Borders-BodyD-Regular-Row1">The following are general tax settings found under the <strong>Taxes</strong> section heading:</td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><strong>Setting</strong></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><strong>Description</strong></td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1">Ship Code for Store Pickup Calculations</td> <td class="TableStyle-Borders-BodyD-Regular-Row1">The ship via code defined here will determine if the order is a store pickup. If it is, taxes will be based on the store's address rather than the ship to address.</td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1">State for Store Pickup Calculations</td> <td class="TableStyle-Borders-BodyD-Regular-Row1">If the order is being picked up at a store, as defined by the ship via code, this is used to determine which state that will be used to calculate state tax.</td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1">Store Pickup Postal Code</td> <td class="TableStyle-Borders-BodyD-Regular-Row1">If the order is being picked up at a store, as defined by the ship via code, this is used to determine which tax locality to use to calculate local tax.</td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>Use Order Warehouse for Tax Origin Address</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1">If <strong>Yes</strong>, the address of the default warehouse will be used to determine the tax rate for the order. If <strong>No</strong>, the website's company address will be used. Default is <strong>No</strong>.</td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1">Non-Exempt Customer Tax Code</td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>If a value is given for this setting, only customers with this value as their tax code will have taxes calculated.</p> <div class="note"> <strong>IMPORTANT:</strong> This setting was deprecated as of version 4.4. Review the related article on upgrading to version 4.4, as adjustments to the settings and code are required. </div></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td colspan="2" class="TableStyle-Borders-BodyD-Regular-Row1">The following settings are no longer applicable, as Avalara does not require them.</td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><strong>Setting</strong></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><strong>Description</strong></td> </tr> <tr class="even TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyE-Regular-Row1"><p>UserName</p></td> <td class="TableStyle-Borders-BodyD-Regular-Row1"><p>The field is no longer used by Avalara and was removed from the Admin Console in version 4.4.</p></td> </tr> <tr class="odd TableStyle-Borders-Body-Row1"> <td class="TableStyle-Borders-BodyB-Regular-Row1"><p>Password</p></td> <td class="TableStyle-Borders-BodyA-Regular-Row1"><p>The field is no longer used by Avalara and was removed from the Admin Console in version 4.4.</p></td> </tr> </tbody> </table>

## Final steps

  1. After all the settings have been properly configured and before you test, clear both the Cache and Local Storage, which found within the **Debug** menu.

  2. The last step in the setup is to validate the connection using **Test Connection**:


    If the connection test fails, validate your **Company Code**, **Account**, and **License Key** have been entered correctly and retry. If the connection still fails, connect with Avalara's support to validate your account information.

## View taxes

There is an optional Setting that can be configured to display the Tax within the Cart during the check out process: **Show Tax &'shipping Amount in Cart**.

There is an optional Website Setting that can be configured to display the Tax within the Cart during the check out process: **ShowTaxAndShippingInCart**.

  1. Go to **Admin Console** \> **Administration** \> **System** \> **Settings**.

  2. Search for **Show Tax &'shipping Amount in Cart**.

  3. Change the value to display **YES**. The default is **NO**.

After enabling the setting, to see the tax on a product, a customer needs to be signed into the website, as Avalara requires customer Billing and Shipping information to correctly calculate the tax amount. This calculation is based on configurations made within Avalara.

## Add tax codes to customers or products

Tax codes can be assigned to customers and/or products. There are numerous business and legal reasons to apply tax codes, so we will leave making those decisions up to you. Avalara does provide a default set of specific tax codes (<>) that can be used or you can simply use the NT (non-taxable) tax code indicate a customer or product is not taxable. Once the tax codes have been identified, use the following steps to apply the codes to the relevant customers or products. This can be done manually, as shown below, as a part of a customer or product import, or the codes are assigned within your ERP and would be brought in as a part of a product integration job.


Avalara calculates taxes for the customer based on the Ship To customer record (not the Bill To). To use the NT (non-taxable) code, it must be entered into the **Tax Code** field of the Ship To record.

### Enter the tax code for products

  1. **Admin Console** \> **Catalog** \> **Products**.

  2. Click **Edit** for the desired product.

  3. Click the **Details** finger tab.

  4. Scroll down to the **Tax Information** section.

  5. Enter the tax code in the **Tax Code 1** field (the **Tax Code 2** field is only used in association with the Dual Tax Calculator).

  6. Click **Save.**

### Enter the tax code for customers

  1. **Admin Console** \> **Catalog** \> **Customers**.

  2. Click **Edit** for the desired customer.

  3. Click the **Details** finger tab.

  4. Scroll down to the **Billing** section.

  5. Enter the tax code in the **Tax Code** field.

  6. Click **Save**.

## Access the Avalara website for admin functions

Below are the URLs for manually accessing the Avalara website for Admin Functions:

  • **Test**``

  • **Production**``