Tax Basics

xTuple offers both manual and automated tax solutions, depending on the needs of your business. In this article, we will explore the manual solution which is native to xTuple.


xTuple ERP offers two different options when it comes to handling taxes:

  1. A native xTuple solution, requiring manual updates and maintenance
  2. A fully-automated integration with AvaTax, a tax calculation service provided by Avalara

In this article, we will explore the native tax solution provided by xTuple. To learn more about the xTuple-Avalara integration, please see the Avalara Tax Service Integration article.

Note: 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.

Getting Started

The native xTuple tax solution offers a comprehensive and flexible design for taxation intended to address the unique requirements for sales tax around the world. In this article, we will show how this capability can be adapted to wide-ranging requirements.

In this scenario, we will show the setup for and operation of a tax scenario in which there are two tax zones. Two tax types will also be defined — one for normal products (Tax Type 1) and one for educational products (Tax Type 2). The same customer will ship to two different stores, each of which will fall under a different tax jurisdiction. In one case, educational products are taxed at 1% and normal products at 5%. In the other, both are taxed at 5%. We will demonstrate how xTuple ERP applies the appropriate tax to each sales order line item depending on the item ordered and the ship-to address selected. Tax codes have been established to determine the tax rate to apply (5% or 1% in this example) and the appropriate general ledger (G/L) account to use.

Creating G/L Accounts for Taxation

xTuple ERP gives you the ability to collect taxes on sales orders. There are generally two methods for recording the collection of sales tax in the general ledger (G/L):

  • Tax Liability: Taxes collected from customers are recorded as a liability on the balance sheet. When the tax is paid, the liability is reduced based on the amount of the payment. In this section, we will create two expense categories—one for each of the customer scenarios. Each expense category is linked not to a G/L expense account (as the name implies) but rather to a liability account corresponding to the type of tax being paid. When a voucher for a tax payment is posted, the liability account linked to the expense category is cleared and the cash account on which the check is drawn is charged.
  • Tax Revenue: Using the method described above assumes that tax collected from a customer is revenue and as such is posted to a revenue account in the G/L. Expense categories are established that charge G/L expense accounts when the tax is paid to the tax authority thereby offsetting tax revenues and tax expenses on the income statement.

These two methods are not mutually exclusive, but the relationships between tax codes, expense categories, and corresponding G/L accounts and tax zones must be carefully thought out.

You will setup your G/L accounts with the level of detail necessary to provide the insight and reporting you require for your situation. The following screenshot shows the account detail for a tax liability account. To open the "Chart of Accounts" follow these steps:

  • Locate the "Accounting" module from the top menu
  • Select the "Ledger Accounts" submenu
  • Choose the "Chart of Accounts" option
  • The "Chart of Accounts" window will open
  • Click the NEW button to open the "Ledger Account Number" window
  • Create ledger account numbers (as highlighted below).


G/L Account Definitions

In this example we have created accounts that relate to tax types and tax zones. This may be desirable if you plan to use the financial reporting engine (FRE) to perform financial analysis or to generate supporting documents for tax returns that require this level of detail.

Tax Controls

The following tax-related windows are grouped together in the "Tax" section of the "Accounting" module:

  • Tax Authorities
  • Tax Codes
  • Tax Types
  • Tax Assignments
  • Tax Registrations

We will look at each of these master information categories—with the exception of tax registrations, which are used (optionally) to store tax account numbers by tax authority.

Creating Tax Authorities

Tax authorities are defined as CRM accounts in xTuple ERP, as shown in the following screenshot. To see the full list of CRM accounts, follow these steps:

  • Choose the "CRM" module from the top menu
  • Select the "Account" submenu
  • Choose "List" to open the "Accounts" window:


Tax Authority CRM Account Definition

Info: If you need to generate a check to pay taxes to a tax authority, the parent CRM account should also be defined as a vendor in order to facilitate the payment process.

The detail under a tax authority provides a place to store account information, contacts, and addresses.

Customer Ship-To Tax Definitions

In this scenario, we will use one customer who ships to stores that fall under different tax jurisdictions, each with different tax rates on different types of products. For this example, let's look at the TTOYS customer account:

  • Go to the "Sales" module from the top menu
  • Select the "Customer" submenu
  • Select "List" to open the list of customers
  • Open TTOYS from the list to view the "Customer" window for TTOYS
  • In the "Addresses" tab choose the SHIP-TO radio button
  • From the list, choose both the "STORE1" and "STORE2" options:


Customer Ship-To Tax Definition

The critical field to notice here is the "Tax Zone" field. In this case we see that "STORE1" falls under the tax jurisdiction of TAXZONE1 and "STORE2" falls under TAXZONE2.

Tax Code Definitions

Tax codes hold both the rate(s) at which tax is calculated and the G/L account(s) tax transactions are posted to. To see a sample tax code definition, open the "Tax Code" window using the following steps:

  • Go to the "Accounting" module from the top menu
  • Select the "Tax" submenu
  • Choose the "Tax Codes" option
  • The "List Tax Codes" window will open
  • Click the NEW button to open the "Tax Code" window for creating a new tax code:


Sample Tax Code Detail

You may define up to three tax rates; each is calculated independently. Notice that G/L accounts are also linked to each tax rate. The same account may be used for all three tax rates—or a different account may be used for each to capture more detail for G/L and tax reporting purposes.

Tax Type Definitions

Tax types are linked to items and tax zones on an item's product record. You should think carefully about how to approach tax types. For example, you may consider creating tax types that relate to different tax zones. In this case, you might have tax TYPE10 and tax TYPE15. A single item could be linked to each—TYPE10 for each tax zone that taxes it at 10% and TYPE15 for each that taxes it at 15%.

A sample tax types list is shown below. To open the list of tax types follow these steps:

  • Go to the "Accounting" module from the top menu
  • Select the "Tax" submenu
  • Choose the "Tax Types" option
  • The "List Tax Types" window will open:


Tax Types

Another strategy is to relate the tax type to product categories. In our scenario, we have normal products and educational products. The relationship between item, tax type, and tax zone is then established based on how each tax zone treats that type of product.

Info: When considering your "Tax Types" setup, the following example may prove useful. It illustrates a case where if tax types are defined effectively, you can get away with only one tax reference on affected item masters.


In some places ice cream is considered a non-essential item, and it is taxed at the standard tax rate. In other places, the same ice cream is considered a food item and so is taxed at an intermediate rate. And in yet other places, ice cream is classified as a dairy item, meaning it is "essential" and so is not taxed at all. This handling of ice cream is unique. Other edibles sold and bought in the same places are not handled in exactly the same way. Milk, for example, is always considered essential and so it is never taxed. The result is that anyone who sells ice cream items in areas with different tax structures needs to create a specific tax type ICECREAM to be able to enter just one item tax record for each ice cream item in the system. A tax type of FOOD would be insufficient, since ice cream and milk are both foods—but they are not taxed the same in all places.

Some tax zones charge tax on freight. A reserved tax type called freight is pre-populated in the xTuple ERP database specifically for this purpose. On the tax selection screen (see below), the freight tax type is then linked to:

  • Tax zones that charge tax on freight
  • Tax codes that contain the appropriate rate

Tax Assignments Matrix

Before we look at an item and its relationship to tax types, let's take a look at tax assignments. The "Tax Assignments" screen creates a matrix combining the tax type (linked to the item), the tax class (also linked to the item), and the tax code.

The following screenshot shows a sample tax assignments master list. To open the "List Tax Assignments" window, follow these steps:

  • Go to the "Accounting" module from the top menu
  • Select the "Tax" submenu
  • Choose "Tax Assignments" from the submenu
  • The "List Tax Assignments" window will open:


Tax Assignments

Here we see that the tax zone TAXZONE1 links two different tax types (one for normal products and one for educational products) to two distinct tax codes. Tax code ZONE1-TYPE1 will calculate the tax at 5% and post it through to a special G/L account. Tax code ZONE1-TYPE2 will calculate the tax at 1% and post it through to a different G/L account. Any tax type linked to TAXZONE2 will result in a 5% tax calculation defined in the tax code ZONE2-TYPE1. A distinct tax code was defined ONLY because this tax code links a G/L account specifically defined to hold tax zone TAXZONE2 balances. Were this not desired, a single 5% tax code could have been used for both TAXZONE1 and TAXZONE2.

Item Tax Type Assignments

The item master record contains a tab called "Tax Types." This tab is used to associate an item with a tax type and corresponding tax zone.

Info: The same tax type may be taxed differently by different tax zones. This is controlled on the tax selections window, where tax zones/tax types are linked to tax codes (which determine tax rates).

The following screenshot shows the "Tax Types" tab on a sample item master. To open the "Item" window, follow these steps:

  • Locate the "Products" module from the top menu
  • Select the "Item" submenu
  • Choose the "List" option to open the "Items" window
  • Choose the YTRUCK1 item number from the list
  • The "Item" window for YTRUCK1 will open, select the "Tax Types" tab:


Item Tax Types Assignments

By default, an item is not taxed if no relationship has been created to link it to a tax type and tax zone. However, it may be desirable in some cases to intentionally indicate that an item is not taxed for a specific tax zone. If so, you would set this up by creating an appropriate tax type/tax zone relationship on the item master. You would then link this relationship to a tax selection record pointing to a tax code having a 0% tax rate. Again, this is optional and may or may not be desirable.

Clearing Tax Liability with Expense Categories

Since we are charging customers tax that we must ultimately pay to tax authorities, it is important to have a mechanism for making payments to tax authorities. Sales tax is a liability that must be settled. As we saw previously, our sample tax code references a liability account. By creating an expense category that links to the same liability account, we can clear our tax liability when we post vouchers that pay tax authorities.

The following screenshot shows a sample "Expense Category" detail. To open the "Expense Category" window follow these steps:

  • Open the "Accounting" module from the top menu
  • Select the "Setup" submenu
  • The "Setup" window will open for the "Accounting" module
  • From the left-side menu, choose "Expense Categories" under the "Accounting Mappings" option
  • The "Expense Categories" list will show up in the main window
  • Select one of the expense categories from the list to view it's "Expense Category" screen:


Expense Categories for Tax

Notice how the "Expense" field for the sample expense category is linked to a liability account. When we voucher our payment to the tax authority, we will use this expense category to clear the liability.

Info: An alternate method for clearing tax liability is to book the sales tax collected to a revenue account—and then offset it with an expense category linked to an expense account.

Sample Sales Order

Let's create a sales order for a customer with a ship-to address that taxes educational products at one rate and normal products at another. Additionally, we will use a tax selection record that links the freight tax type to a tax code, thereby causing tax to be calculated on the freight charge.

The following screenshot shows the line item tax detail for the sample sales order we will be using. To open this window use the following steps:

  • Locate the "Sales" module from the top menu
  • Go to the "Sales Order" submenu
  • Select the "New" option to open the "Sales Order" window
  • In the "Customer #" box, enter in "TTOYS"
  • Select the "Line Items" tab and click the NEW button
  • The "Sales Order Item" screen will open, enter in a sample item number (for this example, let's use YTRUCK1)
  • Go to the "Detail" tab and click the "Tax" option
  • The "Tax Detail" will open for the sample sales order:


Sales Order Line Showing Tax Detail

Info: To view line item tax detail, simply click on the "Tax" hyperlink found on the "Sales Order Item" window.

While tax is calculated at the line item level, we can see the tax impact for an entire sales order from the "Line Items" tab. To open the "Tax Breakdown" window, follow these steps:

  • Navigate back to the "Sales Order" window
  • Select the "Line Items" tab
  • Click the "Tax" option near the bottom of the window
  • The "Tax Breakdown" window will open for the sales order:


Sales Order Line Items Showing Tax Breakdown

From the "Line Items" tab window, click on the "Tax" hyperlink to see an overview of the tax calculation for the entire order. In this case, the total tax resulted from the educational item taxed at 1%, a normal item taxed at 5%, and freight taxed at 5%.

When the product is shipped and the corresponding invoice is posted, the appropriate tax accounts will be reflected in the G/L.

G/L Transactions After Invoice Posting

You will recall that in this scenario we are posting sales tax to a liability account; and, even though it is not necessary to do so, our example uses a different G/L account for each different tax type/tax zone combination we are using. This varied approach enables us to better demonstrate how the "Financial Reporting Engine" (FRE) can be used as a tax reporting tool.

The following screenshot shows a summary of the G/L transactions recorded after we posted the invoice corresponding to our initial sales order. To open this summary, follow these steps:

  • Go to the "Accounting" module from the top menu
  • Locate the "General Ledger" submenu
  • Select the "Reports" submenu
  • Choose the "Summarized Transactions" option to open the "Summarized General Ledger Transactions" window
  • Choose a "Start Date" and an "End Date" and click the QUERY button:


Summarized G/L Transactions for Sales Tax on an Invoice

Now that we have accrued the liability for the sales tax, next we must pay the tax authority.

Tax Payment at Vouchering

While a miscellaneous check could be used to pay the sales tax we have collected, a voucher provides an additional level of control—and also give us the ability to define amounts specific to the different types of tax being paid. A miscellaneous check may only be linked to a single expense category; whereas, a voucher can have an unlimited number of distributions to different expense categories.

The following screenshot shows a sample miscellaneous voucher distribution. To open the "Miscellaneous Voucher" window, follow these steps:

  • Go to the "Accounting" module from the top menu
  • Select the "Accounts Payable" submenu
  • Choose the "Voucher" submenu
  • Select the "New Miscellaneous" option
  • The "Miscellaneous Voucher" window will open
  • Fill in the "Vendor #" box and click the NEW button in the "Misc. Distributions" tab
  • The "Miscellaneous Voucher Distribution" window will open:


Voucher for Tax Payment

  • Once filled in, click SAVE to save the miscellaneous voucher distribution value.

Miscellaneous distributions on a miscellaneous voucher enable us to select the appropriate expense category for each type of tax being paid on a single payment. You may recall that our scenario links an expense category to the same G/L account used for accruing sales tax liability. Paying taxes in this way enables us to clear the appropriate liability account when we post miscellaneous vouchers.

On the following screenshot you can see a summary of the G/L transactions which resulted from the out posting of the miscellaneous voucher:


G/L Postings After Voucher Posting

Posting the voucher cleared the liability accounts associated with the expense categories used on the voucher. The A/P liability will subsequently be cleared when a check paying the voucher is posted.

Taxes on Purchases

Just as we calculated sales tax for our customers, our vendors will do the same for us. Tax on purchases appears on the vendor's invoice—and should be recorded during the vouchering process. Again, when vouchering we can use miscellaneous distributions along with expense categories to record purchasing tax.

The following screenshot shows a sample expense category we have established to record tax on purchases:


Expense Category for Taxes on Purchased Items

We will use the expense category during a vouchering scenario. In our example, the vendor is charging us tax on one or more items of "Type1." The following screenshot shows the voucher for this purchase, as well as the miscellaneous distribution for tax purposes:


Miscellaneous Distribution of Voucher to Pay Tax

The purchase order we are vouchering is for a vendor invoice totaling $220.00. Of this amount, $200.00 is for the product and $20.00 is for tax. The tax is accounted for using the expense category corresponding to the type of tax being paid. Since expense categories are linked to G/L accounts, the tax amount will be posted to the appropriate account.

Info: If multiple types of taxes are identified on a vendor invoice, multiple expense categories pointing to different tax accounts may be used.