Skip to main content
Avalara Help Center

Add or Import Custom Tax Rules

This article applies to:Avalara AvaTax Update

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. You must add where you collect tax, tax codes, and items before you add a tax rule. 

Add tax rules one at a time or import multiple tax rules at once. Go to Settings > Manage Advanced Company Settings > Manage Custom Tax Rules to add, edit, or export custom tax rules.

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 Update 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.

Import tax rules

Add custom tax rules to AvaTax Update by importing them all at once, using an .xls, .xlsx, or .csv (comma-separated values) file. For best results, use the template from AvaTax Update to create this file. 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

Use a valid Jurisdiction code.

Exception:

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.

For a state-level rule, the state JurisCode is required and applies to all 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 type 1.

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 Update Pro and SST accounts.

0 = Non-AvaTax Update Pro (default)

1 = AvaTax Update 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 your custom tax rules

To import your custom tax rules:

  1. Go to Settings > Manage Advanced Company Settings > Manage Custom Tax Rules
  2. Click Import Your Tax Rules on the Your Custom Tax Rules page
  3. Download the tax rule import toolkit
  4. Create the import file using the import tax rules template from the toolkit
  5. Go back to the Import Your Tax Rules page in AvaTax Update
  6. Drag and drop the import file into the import area or click Browse Instead to select the file
  7. The tax rules are uploaded and appear on the Your Custom Tax Rules page. If you get any errors, use the error file to troubleshoot, and then try again

Troubleshoot file imports

To troubleshoot file imports:

  1. Go to Settings > Manage advanced company settings > Manage custom tax rules and click View tax rule import history.
  2. Click the Download icon in the Errors column of the import that you want to troubleshoot. The Error.csv file downloads.
  3. Open Error.csv and view the error message in the last column for each record that failed to import.
  4. Make the necessary corrections to the records, and then delete the last column (the one with error messages).
  5. Save the file with a new name and import it.
  • Was this article helpful?