Load tax rates
You can upload one tax rate load as a CSV file for each tax code. Most Zuora Billing customers will have a small number of tax codes, and this functionality allows greater flexibility to have specialized taxation where one charge can trigger a state or country specific tax.
To handle large tax rate imports, split the tax rates into smaller files and append them as needed. Due to file size limitations and the UI dependency for tax rate uploads, there is an upper limit for uploads. While this is the current system, future updates will aim to support larger tax-rate imports.
The tax rate Import File has two main sections: matching fields and tax rates.
Matching fields
The matching algorithm considers null values in the matching fields as valid matches. For example, if the zip code in the matching fields is null, the system will consider values in the zip code field of the sold-to contact to determine the match.
For each field, including state, county, city, postal code, and tax region, the system considers a field to match the condition if it has the same value as the input or if the field has a null value. If all the fields match the condition, the system considers it a candidate. It then compares tax orders and returns the one with the smallest tax order.
Zuora recommends entering a country and state entry for each state, with taxation as a "catch all" as the last entry searched for that state, either through sorting or as the last records.
The Zuora Tax mapping process will search for a match only and will not try to identify the closest best match. The country, state, county, city, postal code and tax region are matched between the entry in this file and the sold-to contact address.
If a match is not found, Zuora Billing will write <nomatch> in the Tax Jurisdiction field on the following exports:
- Invoice Details Export
- Credit Taxation Item Details Export (This feature is in Limited Availability.)
- Debit Taxation Item Details Export (This feature is in Limited Availability.)
Additionally, if you want to find the tax rate for a state such as AB, both tax rates with a state value of AB and null values are considered. The system will select the tax rate with the smallest tax order, considering match conditions where the field value is null or matches. To illustrate further, consider the following example with three tax rates:
| Tax Order | Tax Code Name | Country | State | Country | City | Postal Code | Tax Region | Tax Name | Tax Rate |
|---|---|---|---|---|---|---|---|---|---|
| 1 | RD - IVA FULL - B2BG | Spain | Santa Cruz de Tenerife | None | None | None | None | G5 | 0.07 |
| 2 | RD - IVA FULL - B2BG | Spain | None | None | None | None | None | RD | 0.21 |
| 3 | RD - IVA FULL - B2BG | Spain | STA CRUZ DE TENERIFE | None | None | None | None | G5 | 0.07 |
If Spain is selected as the country and Santa Cruz de Tenerife as the state, the system will select the first tax rate as both the first and second tax rates match the condition, and the first tax rate has a smaller tax order. Similarly, Spain is selected as the country and STA CRUZ DE TENERIFE as the state, the system will select the second tax rate based on the same matching conditions.
The following fields are used to match the fields in the Sold To Contact:
| Field | Required? | Description |
|---|---|---|
| Country | Yes |
Country code using the allowable values from Zuora Billing. This field is matched to the Country field in the Sold To Contact. For a complete list of supported countries, see View countries or regions. |
| State/Province | Conditional |
State or province code using the allowable values from Zuora Billing. This field is required if Country is US or Canada. This field is matched to the State/Province field in the Sold To Contact. |
| County | No |
Customer-defined field to aid in taxation. This field is matched to the County field in the Sold To Contact. This field is available for customers using Zuora Tax. |
| City | No | This field is matched to the City field in the Sold To Contact. |
| Postal Code | No | This field is matched to the Postal Code field in the Sold To Contact. |
| Tax Region | No |
Customer-defined field to aid in taxation. This field is matched to the Tax Region field in the Sold To Contact. This field is available for customers using Zuora Tax. |
| Description | No |
Customer-defined field. This field is used for reporting purposes and is available on:
|
Tax rates
Zuora Billing allows up to three independent taxes to apply to a single charge.
Each tax can have a type of FlatFee or Percentage. If you use Percentage, store the tax rate as a decimal value. For example, 7% should be entered as .07.
Percentages are applied to the charge amount. This means that a negative percentage will be created if the charge is negative. However, FlatFee taxes are applied as positive values, regardless of whether the charge is negative or positive.
The tax rates are not compounded. Each tax will be applied independently to the charge. For example, if a charge is $10 and Tax 1 is .07 and Tax 2 is .01, Tax 1 will be calculated to .70 and Tax 2 will be calculated to .10
Tax rate fields
| Field | Required? | Description |
|---|---|---|
| n-Tax Rate | Yes | Any value, including whole numbers and decimal numbers. For Percentage, specify the decimal value. For Flat Fee, you can specify any numeric value. |
| n-Tax Rate Type | Yes | Specify FlatFee or Percentage. |
| n-Tax Name | Yes | Specify any name. The tax rates will be grouped and displayed by name on the invoice. |
| n-Tax Jurisdiction | No | Optional string value to help with reporting. Typically, this value is State, County, City, etc. You can also use this field to segment GL. |
| n-Tax Location Code | No | Optional string value to help with reporting. Typically, this value is a numeric that identifies the specific city. You can also use this field to segment GL. |
| n-Tax Rate Description | No | Optional string value to help with reporting. This can be the breakdown of the components of the tax that can be parsed outside of Zuora Billing or a GL segment value. |
Load rules
The following rules apply when loading tax rates:
-
We recommend that you use the following CSV format variations to import tax rates:
- MS-DOS Comma Separated from Microsoft Excel
- Windows Comma Separated from Microsoft Excel
- Comma Separated Values from Microsoft Excel
- Comma-separated Values from Google Sheets
- If you have specified a value for the Tax Rate field, you must specify values for Tax Rate Type and Tax Name.
- Blank records will be skipped.
- If there is an error in the file, the entire file will be rejected.
- Matching fields are not case-sensitive.
- There are three tax rates. When a blank tax rate is reached, no further loading of tax rates for that row will be performed.
- If Tax Rate 1 is empty and there are values in Tax Rate 2, Tax Rate 2 will not be loaded.
- Zuora recommends that you always begin with Tax Rate 1, then add taxes to Tax Rate 2 and then Tax Rate 3, as required.
The status of the load process will be displayed on the screen. This process will periodically write status to the screen when loading large files.
If an error is encountered, Zuora Tax will not load the file. The load process has an error buffer so that it will continue to load the file until the buffer max of 20 is reached or the process reads through the entire file. This will help identify all errors so that you can fix them in one step, or stop the process if Zuora Tax encounters a large number of errors.
Tax periods
When the first tax rate is loaded, the effective period is created with a default start date of the current date, and with no end date.
You can edit the periods by selecting More > Edit Periods.
If tax rates change, please click New Period to create a new tax period, and upload the appropriate tax rates to be used for that period.
Update the tax period effective dates
When you update a tax rate and set a new period, Zuora will display a confirmation of the change. For example, if your previous tax rate had an effective period starting on 03/01/2012, with no end date, and you upload a rate with an effective period starting on 03/01/2012 and ending on 08/31/2012, Zuora will display the following message:
The Effective End Date of the Current period will be changed. Old value: 03/01/2012 - No End Date New Value: 03/01/2012 - 08/31/2012
In this example, based on the previous tax rate, all of the subscription rate plan charges that were created with a product which is taxed with this tax rate will be computed with the said tax given that the invoice date is starting from 03/01/2012. This tax rate also does not have an end date, so the subscription rate plan charges will be generated with invoices which are applied with the tax rate until this subscription's term has ended.
However, when updating the tax rate, the Effective Period will be modified with an End Date of 08/31/2012. New invoices with an invoice date starting from 09/01/2012 will not use this tax rate.
The Tax Rate will only be applied to invoices with an invoice date from 03/01/2012 - 08/31/2012. This tax rate will not be applied to invoices created outside of this time frame.