Skip to main content

Load tax rates

Zuora

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.

The tax rate Import File has two main sections: matching fields and tax rates.

Matching fields

The matching algorithm will ignore blank values in any of the matching fields. For instance, if zip code in the matching fields is blank, values in the zip code field of the sold to contact are not used to determine the match.

The order of the tax rates is important for matching. Zuora Billing will maintain the order and use the tax rates associated with the first match found in 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.)

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:

  • Invoice Template
  • Invoice extract files
  • Credit Taxation Item extract files (This feature is in Limited Availability.)
  • Debit Taxation Item extract files (This feature is in Limited Availability.)

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.