Skip to main content
Avalara Help Center

Add or Import Custom Tax Rules

This article applies to:Avalara AvaTax

Add custom tax rules to determine how items with custom tax codes are taxed or to override tax rules for Avalara tax codes. Use them for broader objectives too, like overriding (or eliminating) tax rates for specific jurisdictions or applying special requirements related to customer use. Before you add a tax ruleHoverTT.png, you must add jurisdictions, tax codes, and items. Add one at a time or import multiple tax rules at once. The steps you take vary by the type of tax rule you're adding. The available types are:

  • Taxability: Identifies a tax code as either taxable or non-taxable in a specified taxing jurisdiction
  • Exempt entity: Indicates how to handle an entity use code’s taxability in a particular jurisdiction (entity use codes are generally associated with customers, not items). An entity use tax rule can be applied only to an entity use code or a combination of entity use code and tax code.
  • Base override: Identifies the percentage of the base (sale) amount that's considered taxable
  • Rate override: Overrides a standard tax rate returned by AvaTax and, instead, uses a specified tax rate for a particular taxing jurisdiction. You may need to adjust transactions processed using rate override tax rules. For tax return purposes, transactions must conform to the established rates for the jurisdictions involved in the transactions.

To learn more before you add them, read about managing tax rules.

Add a taxability tax rule

Add a taxability tax rule to identify a tax code as non-taxable for a particular taxing jurisdiction.

  1. On the Organization tab, click the Custom Tax Rules button for a company.
    AvaTaxCalc-Organization-TaxProfile-SelectTaxRules.png
  2. On the Tax Rules screen, click New.
  3. On the New: Tax Rule screen, Step 1: Jurisdiction Selection, complete the required fields:
    • Country
    • Level
    • Region
    • County
    • City
    • Special Tax Jurisdiction
  4. Click Next.
  5. On the New: Tax Rule screen, Step 2: Details, complete the fields common to all tax rule types:
    Name: The name of the tax rule for display purposes on the Tax Rule List
    Tax Type: The type of tax to which the tax rule applies.
    1. For United States jurisdictions, select from:
      • Sales and Sellers Use – the tax rule applies to both sales and sellers use tax
      • Sales – the tax rule only applies to sales tax
      • Sellers Use – the tax rule only applies to sellers use tax
    2. For Canada or other country jurisdictions, select from:
      • Input and Output Tax – the tax rule applies to both input and output tax
      • Input Tax – the tax rule only applies to input tax
      • Output Tax – the tax rule only applies to output tax
        AvaTaxCalc-Organization-TaxProfile-CompleteTaxRuleStep2CommonFields.png
  6. Select Taxability as the Rule Type.
  7. Choose a Taxable option (United States only) or select a Rate Type (non-US countries).
    • Taxable
      • Yes – makes the tax code taxable for the jurisdiction
      • No – makes the tax code nontaxable for the jurisdiction
    • Rate Type
      • Increased Standard - An increased value added tax (VAT) rate is applied to the product

      • Parking - The VAT rate for parking is applied to the product

      • Reduced A - A reduced VAT rate is applied to the product

      • Reduced B - A reduced VAT rate is applied to the product

      • Reduced R - A reduced VAT rate is applied to the product

      • Standard (default) - The standard VAT rate is applied to the product

      • Super Reduced - A reduced VAT rate is applied to the product

      • Zero - A VAT rate of zero is applied to the product

  8. Click Finish. The tax rule appears on the Tax Rule List. A message indicating "The operation completed successfully" displays above the Tax Rule List.

Add an exempt entity tax rule

Add an exempt entity tax rule to indicate how to handle an entity use code’s taxability in a particular jurisdiction (entity use codes are generally associated with customers, not items). An entity use tax rule can be applied only to an entity use code or a combination of entity use code and tax code.

To add an exempt entity tax rule:

  1. On the Organization tab, click the Custom Tax Rules button Picture of the Tax Rules button for a company.
  2. On the Tax Rules screen, click New.
  3. On the New: Tax Rule screen, Step 1: Jurisdiction Selection, complete the required fields:
    • Country
    • Level
    • Region
    • County
    • City
    • Special Tax Jurisdiction
  4. Click Next.
  5. On the New: Tax Rule screen, Step 2: Details, complete the fields common to all tax rule types:

    Name: The name of the tax rule for display purposes on the Tax Rule List

    Tax Type: The type of tax to which the tax rule applies.

    Tax Code: The tax code that applies to the tax rule. You can browse custom tax codes and Avalara tax codes with the tax code picker.

    Start Date: The date the tax rule goes into effect.

    End Date: The date on which the tax rule expires

    1. For United States jurisdictions, select from:​
      • Sales and Sellers Use ? the tax rule applies to both sales and sellers use tax
      • Sales ? the tax rule only applies to sales tax
      • Sellers Use ? the tax rule only applies to sellers use tax
    2. For Canada or other country jurisdictions, select from:
      • Input and Output Tax ? the tax rule applies to both input and output tax
      • Input Tax ? the tax rule only applies to input tax
      • Output Tax ? the tax rule only applies to output tax
  6. Select Exempt Entity as the Rule Type.
  7. Choose an Exempt option.
  8. Select or type an Entity Use Code to group like kinds of customers for exemption purposes.
  9. Click Finish. The tax rule appears on the Tax Rule List. A success message displays above the Tax Rule List.

Add a base override tax rule

Add a base override tax rule to identify the percentage of the base (sale) amount that's considered taxable.

To add a base override tax rule:

  1. On the Organization tab, click the Custom Tax Rules button Picture of the Tax Rules button for a company.
  2. On the Tax Rules screen, click New.
  3. On the New: Tax Rule screen, Step 1: Jurisdiction Selection, complete the required fields:
    • Country
    • Level
    • Region
    • County
    • City
    • Special Tax Jurisdiction
  4. Click Next.
  5. On the New: Tax Rule screen, Step 2: Details, complete the fields common to all tax rule types:
    Name: The name of the tax rule for display purposes on the Tax Rule List
    Tax Type: The type of tax to which the tax rule applies.
    1. For United States jurisdictions, select from:
      • Sales and Sellers Use -- the tax rule applies to both sales and sellers use tax
      • Sales -- the tax rule only applies to sales tax
      • Sellers Use -- the tax rule only applies to sellers use tax
    2. For Canada or other country jurisdictions, select from:
      • Input and Output Tax -- the tax rule applies to both input and output tax
      • Input Tax -- the tax rule only applies to input tax
      • Output Tax -- the tax rule only applies to output tax

        Tax Code: The tax code that applies to the tax rule. You can browse custom tax codes and Avalara tax codes with the tax code picker.
        Start Date: The date the tax rule goes into effect.
        End Date: The date on which the tax rule expires
  6. Select Base Override as the Rule Type.
  7. Select or type an Entity Use Code to group like kinds of customers for exemption purposes, if desired.
  8. Type a Base Override %.
  9. Click Finish. The tax rule appears on the Tax Rule List. A success message displays above the Tax Rule List.

Add a rate override tax rule

Add a rate override tax rule to override a standard tax rate returned by AvaTax and, instead, use a specified tax rate for a particular taxing jurisdiction. You may need to adjust transactions processed using rate override tax rules. For tax return purposes, transactions must conform to the established rates for the jurisdictions involved in the transactions.

To add a rate override tax rule:

  1. On the Organization tab, click the Custom Tax Rules button Picture of the Tax Rules button for a company.
  2. On the Tax Rules screen, click New.
  3. On the New: Tax Rule screen, Step 1: Jurisdiction Selection, complete the required fields:
    • Country
    • Level
    • Region
    • County
    • City
    • Special Tax Jurisdiction
  4. Click Next.
  5. On the New: Tax Rule screen, Step 2: Details, complete the fields common to all tax rule types:

    Name: The name of the tax rule for display purposes on the Tax Rule List

    Tax Type: The type of tax to which the tax rule applies.
    Tax Code: The tax code that applies to the tax rule. You can browse custom tax codes and Avalara tax codes with the tax code picker (not a required field).

    1. For United States jurisdictions, select from:
      • Sales and Sellers Use -  the tax rule applies to both sales and sellers use tax
      • Sales - the tax rule only applies to sales tax
      • Sellers Use - the tax rule only applies to sellers use tax
    2. For Canada or other country jurisdictions, select from:
      • Input and Output Tax - the tax rule applies to both input and output tax
      • Input Tax - the tax rule only applies to input tax
      • Output Tax - the tax rule only applies to output tax

        Start Date: The date the tax rule goes into effect.

        End Date: The date on which the tax rule expires.

  6. Select Rate Override as the Rule Type.
  7. Select or type an Entity Use Code to group like kinds of customers for exemption purposes, if desired.
  8. Type a Rate Override % to override the tax rate returned from AvaTax and apply the desired tax rate.
  9. Click Finish. The tax rule appears on the Tax Rule List. A success message displays above the Tax Rule List.

Import tax rules

The Import Data tool allows you to easily import a large number of predefined custom tax rules. For related information, read the complete listing of juriscodes, or use the sections that follow to learn how to import multiple tax rules at once.

Import items in one of these file formats: .xls, .xlsx, or .csv (comma-separated value). Use the template in the Tax Rules Toolkit for best results. The maximum number of lines allowed in one import file is 100,000.

Format the tax rule import template

You must use the column heading labels exactly as shown below in the import file. The individual data fields must conform to the type and size restrictions listed in the table. The table below also indicates, in the Use column, whether a column is required in the import file.

Column Column Heading Type (Size) Use Description
A TaxRuleId Integer Required Tax rule record number. This is not imported but is used to identify error records.
B ProcessCode Integer Required

Determines the processing for this rule.

If you're deleting a rule, values in TaxRuleTypeId, Country, State, JurisTypeId, JurisCode, EntityUseCode, TaxCode, TaxTypeId, EffDate, and Threshold must match the current settings of the rule.

0 = Delete rule

1 = Insert/update rule

C TaxRuleTypeId Integer Required

Type of tax rule.

0 = Excise tax

1 = Rate override rule

2 = Base override rule

3 = Entity use rule

4 = Product taxability rule

D TaxRuleSubtypeId Text (1) Optional

Reserved for future use. Column must be left blank.

E Country Text (2) Required

Two digit country code.

  • US = United States
  • CA = Canada
  • AU = Australia
  • NZ = New Zealand
  • TW = Taiwan
F Region Text (3) Required ISO 2 or 3 character state or province code (e.g. AL, AK, AZ, etc.)
G JurisTypeId Text (3) Required

Jurisdiction type identifier.

  • CNT = Country
  • STA = State/Province (Region)
  • CTY = County
  • CIT = City
  • STJ = Special Tax Jurisdiction
H JurisCode Text (10) Required

Jurisdiction code.

An asterisk (*) indicates that it applies to all the jurisdictions of the type specified by JurisTypeId. This asterisk is only applicable for county, city, and special tax jurisdiction.

Example: For a state-level rule, the state JurisCode is required and applies to all the instances of that level in the state.
For a county-level rule, the county JurisCode is required. 

I JurisName Text (200) Optional Name of the jurisdiction. This is for informational purposes only and is replaced by the standard jurisdiction name when imported.
J IsAllJuris Boolean Optional

Whether the tax rule applies to one or all jurisdictions in a tax region.

0 = The tax rule only applies to the identified jurisdiction (column G). This is the default.

1 = The tax rule extends to all jurisdictions in the tax region.

K TaxCode Text (25)

Required for product taxability rules

Optional for other rule types

An Avalara tax code or custom tax code indicating the category of product, service, or charge.
L EntityUseCode Text (25)

Required for entity use rules

Optional for other rule types

System or custom entity use code. Some use codes for the United States and Canada are different, so the applicable country is shown beside the code.

A = Federal government (United States)

B = State government (United States)

C = Tribe / Status Indian / Indian band (both)

D = Foreign diplomat (both)

E = Charitable or benevolent org (both)

F = Religious or educational org (both)

G = Resale (both)

H = Commercial agricultural production (both)

I = Industrial production / manufacturer (both)

J = Direct pay permit (United States)

K = Direct mail (United States)

L = Other (requires Exempt Reason Desc) (both)

N = Local government (United States)

P = Commercial aquaculture (Canada)

Q = Commercial fishery (Canada)

R = Non-resident (Canada)

MED1 = US MDET with exempt Sales Tax

MED2 = US MDET with taxable Sales Tax

M TaxTypeId Text (1) Required The type of tax this rule applies to.

Domestic (US)

B = Both sales and use (default)

E = Excise

S = Sales

U = Use

International (VAT)

B = Both input and output (default)

O = Output

I = Input

N RateTypeId Text Optional For a rate override rule (TaxRuleTypeId 1), this determines what rate type is overridden.

For a product taxability rule (TaxRuleTypeId 4), this determines what rate type is applied to a product.

Domestic (US)

F = Food

G = General (default)

L = Linen rental

M = Medical devices

R = Rental

International (VAT)

A = Reduced Rate A VAT

B = Reduced Rate B VAT

I = Increased Standard VAT

P = Parking VAT

Q = Super Reduced VAT

R = Reduced VAT

S = Standard VAT (default)

Z = Zero Rate VAT

O Value Decimal Required Varies by rule type.

Rate override rule = Override rate. Format as, for example, .05 to indicate 5%. 1 indicates to inherit standard rate

Base override rule = Base rate. Format as, for example, .05 to indicate 5%.

Entity use rule = 0 is exempt. 1 is taxable.

Product taxability rule = 0 is non-taxable. 1 is taxable

For international product taxability rules, use 1 for zero-rate products to indicate the product is taxable at the zero rate.

P Threshold Decimal Optional Minimum amount at which a rate override or product taxability rule applies. Blank or 0 indicates no threshold.
Q Cap Decimal Optional Maximum amount to which a rate override or product taxability rule applies. Blank or 0 indicates no cap.
R Options Text (100) Optional

Document = The cap applies to entire invoice. Applies to rule types 1 or 4.

TaxAll = Entire amount should be taxed if the taxable amount exceeds the threshold. Applies to rule types 1 or 4.

TaxCap = The cap is on the maximum tax rather than the maximum amount. Applies to rule types 1 or 4.

TaxDepends = The taxability of this item depends on the taxability of other physical items. This only applies to product taxability rules (type 4).

RateDepends = The rate of this item is determined as the highest rate from all qualified items, where qualified items are physical items originating in an EU country.

S IsPro Number Optional Indicates whether this rule applies to only AvaTax Pro and SST accounts.

0 = Non-AvaTax Pro (default)

1 = AvaTax Pro and SST accounts only

T EffDate Date (10) Optional Initial effective date for this rule in yyyy-mm-dd or mm/dd/yyyy format. The minimum and default value is 1/1/1900.
U EndDate Date (10) Optional Expiration date for this rule in yyyy-mm-dd or mm/dd/yyyy format. The maximum and default value is 12/31/9999.
V Description Text (255) Optional Description of the tax rule.

Import a file of tax rules

To import a file of tax rules: 

  1. On the Tools tab, click Import Data.
  2. On the New: File Import screen, from the Type list, select Tax Rules.
  3. To use the Import Toolkit, click Download, extract the files, and fill in one of the blank templates.
  4. On the New: File Import screen, click Next, and then select the company the items are for.
  5. Click Choose File, browse to select the file you want to import, and then click Open. Import files with .xls, .xlsx, and .csv extensions only.
  6. In AvaTax, click Upload. The file uploads and the Import Status screen opens, displaying the status of the import.
 

Troubleshoot file imports

If the Status column for the file displays Error, fix any errors  before you try again.

To fix import errors:

  1. On the Import Status screen, in the File column for an imported file, click the Error hyperlink. The Error.csv file downloads.
  2. Open Error.csv and view the error message in the last column for each record that failed to import.
  3. Make the necessary corrections to the records, and then delete the last column (the one with error messages).
  4. Save the file with a new name and import it.