Avalara Tax Service Integration

Tired of maintaining tax codes and tax assignments by hand? Learn how xTuple's integration with the Avalara tax service can handle your tax calculations for you automatically.


Beginning with xTuple ERP version 5.0.0, xTuple is pleased to offer a full integration with Avalara's AvaTax tax calculation service. To participate, you will first need to purchase an AvaTax subscription from Avalara. Once that's done, you're only a few configuration steps away from being ready to use the service.

To sign up with Avalara—or to learn more about AvaTax and the other tax services offered by Avalara—please fill out their online contact form to engage with them directly.

In this article, we will explain how to configure the xTuple-Avalara integration. We will also provide examples showing how taxes are calculated for you automatically by the Avalara tax service.

All About Addresses

With the xTuple-Avalara integration, you will no longer need to manually maintain tax codes and other tax tables. All you need to do is supply valid addresses (along with updated tax types, which we'll discuss later), and Avalara takes care of the rest.

Take a typical sales order, for example. You have the ship-to address, which is where line items are being shipped to. You also have the from address—that is, the address of the site you are shipping the line items from. As long as you supply these two addresses (which are standard with every xTuple sales order), Avalara's automated tax system will calculate the correct tax for you. Shipping to a state with an origin-based tax law? No problem. Avalara handles every tax complexity like this, all based on the addresses you supply.

NOTE: xTuple ERP provides address validation support with its Address Verification package. The package supports validation of United States Postal Service (USPS) addresses.

Configuring the Integration

When you sign up for Avalara's AvaTax service, you will be given some information that you will need to configure the integration between xTuple and Avalara. Don't worry, the configuration steps are easy to complete. You just need to make sure to collect all the required information.

To configure the xTuple-Avalara integration, go to System > Setup > Tax Integration. The following screen will appear:


Entering Avalara account information

When configuring the xTuple-Avalara integration, you are presented with the following options:

  • Tax Service: Select the "Avalara" option from the drop-down menu. To revert to the native xTuple tax system, choose the "None" option. You can toggle back and forth between tax systems without losing data.
  • Account #: Enter your Avalara account number.
  • License Key: Enter the license key provided to you by Avalara.
  • Service URL: Enter the URL for the tax-calculation service, as supplied to you by Avalara.
  • Company Code: Avalara will provide you with an appropriate company code to enter in this field.
  • Enable AvaTax UPC: Select if you have purchased this optional add-on feature. When enabled, xTuple will pass an Item's UPC code (i.e., bar code) to Avalara.
  • Disable Document Recording: If selected, the tax service will calculate taxes for you but won't report the tax and document information to Avalara.
  • Enable Logging: Select to enable the logging feature to write log information to a local text file. This feature can prove invaluable when troubleshooting issues related to the integration. Specify where you would like the log file to be saved to.
  • Sales Tax Liability Account: Specify the ledger account you want to use for sales tax liablity reporting.
  • Use Tax Liability Account: Specify the ledger account you want to use for use tax liablity reporting.
  • Purchase Tax Exempt Category: If applicable, select from one of the available tax exempt categories. This option refers to your company's own tax exempt status
  • TEST CONNECTION: Select to verify that the xTuple-Avalara integration is configured correctly.
  • Avalara Admin Console: Select to reach the log in screen for Avalara's admin panel, where you can view account-related information.

The next step after confirming your connection is to link your xTuple tax types to the external, Avalara-provided tax codes. We will describe this process in the next section.

Tax Types

Once you've established the connection between xTuple and Avalara, the next step is to link your xTuple tax types to Avarala's tax codes. The list of available tax types can be found under Accounting > Tax > Tax Types. Here's the Tax Types screen after the Avalara connection has been made:


Tax type with corresponding tax codes from Avalara

To link existing (or new) xTuple tax types with Avalara tax codes, follow these steps:

  1. Enter a name and description for the tax type (if one doesn't already exist).
  2. Scroll through the list of available external tax codes to find the Avalara tax code you want to link to the tax type. You can also locate a tax code using the search box.
  3. Once you've found the tax code, select it. This will add the code to the External Tax Code field.
  4. The tax code and the tax type are now linked as one.

The final step is to ensure your tax types (i.e., Avalara tax codes) are associated with the items you buy and sell. This association between items and tax types is made on the Item master screen. The following screenshot shows a sample item record, with the Tax Types tab selected:


Detail from Tax Types tab of Item master screen

As you can see in this example, the tax type is flagged as the default tax type for the item. Having a default tax type for each item is essential to the xTuple-Avalara integration. While you may link multiple tax types to an item, only the default tax type will be recognized by Avalara.

Once you are done assigning tax types to your items, the connection between items and the Avalara tax system is complete. You are now ready to enter orders and have the taxes handled automatically by Avalara.

Sales Tax Calculated Automatically

Assuming you have all the configuration pieces in place, Avalara will calculate the correct sales tax for you on the fly. To reiterate, here are the key elements you need:

  • An active connection to your Avalara account
  • Valid addresses
  • Tax types associated with items

To illustrate how these elements come together in practice, let's take a look at the following sample sales order:


Sales Order header information

As you can see in the screenshot, there are three pieces of information found in a sales order which AvaTax needs to do its calculations:

  • Order date: This acts as the effective date for the tax calculation.
  • Site: The site's address is considered to be the from or origin address.
  • Ship-to: This is the destination address. Notice that xTuple provides a validation feature with every address cluster. To validate an address, simply select the CHECK button. If the button changes to GOOD, then you know you have a valid address. If you get a different result, that means your address is invalid for some reason. Fix the problem and then try validating the address again.

TIP: You can configure address validation under CRM > Setup > Configure > Address Validation. To learn more, please see our article on address validation.

Also on the header, you may notice the "Tax Exempt Category" option. This information is pulled from the related customer record and flows through to the sales order line item level. In this example, the customer is not tax-exempt.

IMPORTANT: If you purchased and are using Avalara's CertCapture feature to manage your customer's tax exemption certificates, then you need to read our article on updating Avalara's default exempt override code.

When entering line items, you will see the tax type associated with each item. The following screenshot shows a sample sales order line item:


Sales order line item tax detail

Select the Detail tab to see the item's tax type. This tax type is pulled from the Item master. Because we linked our tax types to Avalara's tax codes, the AvaTax system will know what type of tax to apply to this item. In this example, the tax amount is displaying on the screen. That is because this line item was saved prior to taking the screenshot. Line item tax amounts will not be displayed until the order is saved or the tax is manually recalculated at the header level.

Once you've entered a line item, you can view the line item on the Line Items tab of the sales order:


Tax calculation and breakdown information on Line Items tab

Sales tax will always be calculated when a sales order is saved. As you can see in the screenshot, you may also manually recalculate the tax by clicking on the blue gear icon in the Tax field. Using the manual calculation option is helpful if you need to verify or quote the tax on the fly. Again, there is no need to use the manual option. Taxes will be calculated when an order is saved, and the tax will display when you open a saved order.

The Tax Breakdown option will show the underlying detail used by Avalara to perform the tax calculation. The following screenshot shows the tax breakdown for our sample sales order:


Tax breakdown showing detail behind tax calculation

As you can see in the example, both state and county tax for the state of Virginia are required. Because freight is included in the order, tax is charged on that, as well. Of course, the sales tax is only an estimate at the sales order stage. Not until the sales order is shipped and converted to a posted invoice will the sales tax be officially charged.

To view the current status of invoices, credits or any tax-related documents, log into your AvaTax dashboard. The following screenshot shows the dashboard with the invoice resulting from our example sales order:


View of AvaTax dashboard showing posted invoice with committed status

The AvaTax dashboard contains a multitude of features. Documenting all of them falls outside the scope of this article. However, you are encouraged to explore your AvaTax dashboard on your own, as well as utilitze Avalara's training and support services.

Use Tax Calculated on Purchases

The AvaTax system will calculate sales tax for you on purchase orders. However, it's important to note that purchase order sales taxes are estimates only. Ultimately, you need the vendor invoice to know how much tax the vendor has actually charged you. During vouchering, you will enter the amount of vendor-charged tax, if any. At this stage, you will also learn whether any use tax is owed for the purchase.

The following screenshot shows a sample voucher, with both vendor-charged and use tax amounts included:


Voucher detail showing use tax balance owed

As you can see in the screenshot, the vendor in this example charged us $10.19 in sales tax. According to the Avalara tax calculation, the amount of sales tax we are liable for is $15.31. That leaves a use tax balance of $5.12, as shown in the example. As part of the AvaTax solution, Avalara will maintain a running total of your use tax commitment throughout the course of the year. That way, you can be sure to pay the correct use tax amount at tax time.

Again, you can check the status of vouchers and use tax and a whole host of other information on the AvaTax dashboard. While there, you can also learn more about the add-on services offered by Avalara—including their optional tax filing service.