Skip to main content

Set up tax codes

Zuora

Set up tax codes

  1. Last updated
  2. Save as PDF

You can configure tax codes for multiple tax engines (Zuora Tax, Avalara tax engine, and Connect Tax Engines) based on mapping rules.

You must configure the Accounting Code after activating the Tax Code. For more information on configuring the Accounting Code, see Configure Accounting Codes.
You need not configure the Accounting Code upon activation of an existing tax code if the Accounting Code is already configured.

Ensure that each invoice is associated with only one tax engine when configuring tax codes and subscriptions.

Add a tax code for Zuora Tax

To set up a tax code that uses Zuora Tax:

  1. Click your username at the top right and navigate to Settings > Billing.
  2. Click Setup Taxation Codes.
  3. Click add new tax code.
  4. Enter the following information in the Basic Information panel: 
    1. Specify a name in the Tax Code Name field to identify the tax code. This field is used to map to the product charge. 
    2. Select Zuora Tax from the Tax Engine list. This field selects which of your configured tax engines will be used to calculate tax rates for this tax code.
    3. Specify the tax code description in the Description field. This field is available in the following documents:
      • 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.)
    4. Click save.
  5. Import tax rates to Zuora:
    1. Click Choose File in the Zuora Tax Engine: Tax Rates panel to locate the CSV file to import, and then click import tax rates. You can download the tax rate import file template in CSV format by clicking the here link. Refer to this sample file and see Load Tax Rates for the definition of the CSV file fields.
    2. ​Click Ok when Zuora confirms that the tax rates have been uploaded.  

If you have successfully uploaded the CSV file, the tax code is now activated.

Add a tax code for Avalara

This feature is in Controlled Release. Submit a request at Zuora Global Support to get this feature enabled for your tenant.

To set up a tax code that uses the Avalara tax engine:

  1. Click your username at the top right and navigate to Settings > Billing.
  2. Click Setup Taxation Codes.
  3. Click add new tax code.
  4. Enter the following information in the Basic Information panel:
    1. Specify a name in the Tax Code Name field to identify the tax code. This field is used to map to the product charge, for example, Freight service.
    2. Select the name of the Avalara tax engine from the Tax Engine list, for example,  Zuora SE. This field selects which of your configured tax engines will be used to calculate tax rates for this tax code. See Set Up Connections to Avalara for how to set up an Avalara tax engine.
    3. Select the Avalara Company Code from the list. This is the unique code that identifies the company in the AvaTax account. See Set Up Connections to Avalara for more information.
    4. Specify the Avalara Tax Code in this field. This field is a unique label to group Items (products, services, or charges) together, as defined in your Avalara Tax account. See Configure Tax Codes in Zuora Billing for Avalara for more information.
    5. Specify the tax code description in the Description field. This field is available in the following documents:
      • Invoice PDF
      • 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.)
    6. Click save.

The new Tax Code is in active status. 

Set up tax codes for multiple Avalara Company Code and Tax Codes

When you have multiple Avalara Tax Codes, you can set up matching Zuora Tax Codes in Zuora Billing. To do so:

  1. Click your username at the top right and navigate to Settings > Billing.
  2. Click Setup Tax Engine and Tax Date.
  3. Select the Avalara tax engine and click Edit. 
  4. Add two Avalara Company Codes for Direct Avalara Integration tax engine in the Company Information section. For example:
    • Company Code: SETC —Avalara Tax Code: 228327
    • Company Code: NODE —Avalara Tax Code: 228333
      clipboard_e184d5acc913b757fae38c339b2c65605.png
  5. Define the corresponding Zuora Tax Codes to map to the Avalara Tax Codes. For example:
  • Zuora Tax Code: ZuoraTaxCode001 — associates with Avalara Tax Code: 228327
    clipboard_e4302808627a605a20e60ea2bc7762e50.png
  • Zuora Tax Code: ZuoraTaxCode002 — associates with Avalara Tax Code: 228333
    clipboard_edf927f91fa74c9ee83424aea9e96cf30.png
  1. After completing the configuration, click Save.

Add a tax code for Connect Tax Engine

To set up a tax code that uses the Connect Tax Engine:

  1. Click your username at the top right and navigate to Settings > Billing.
  2. Click Setup Taxation Codes.
  3. Click add new tax code.
  4. In the Basic Information area, complete the tax code details:
  • Tax Code Name: Enter the name of the tax code to be selected in the product catalog when discerning which Connect Tax Engine the charges will use to calculate tax.
  • Use Multiple Connect Tax Engines: Select this checkbox if you want to use multiple Connect Tax Engines.
    Selected Not selected
    Tax Engines: Fill in the Mapping Formula tab with mapping rules which define how to select different Connect Tax Engines to handle tax calculation for various customer accounts. Refer to the Example tab to copy and customize pre-defined mapping formulas. See Tax Engine Mapping Formula for more information. Tax Engine: Select the name that you have specified for the Connect Tax Engine.
    External Company Code: Select the company code created when setting up the Connect Tax Engine.
  • Active: This is No by default. You will activate it later.
  • Description (Optional): Describe the tax code and the tax app that will be used for future reference.
  1. Click save.
  2. Click Activate to ensure the tax code is present in the product catalog.

Add a tax code for multiple tax engines

To set up a tax code that uses Multiple Tax Engines:

  1. Click your username at the top right and navigate to Settings > Billing.
  2. Click Setup Taxation Codes.
  3. Click Add new tax code.
  4. Enter the following information in the Basic Information panel:
  • Specify a name in the Tax Code Name field to identify the tax code. This field is used to map the product charge.
  • Select the Use Multiple Connect Tax Engines checkbox.
  • Fill in the Mapping Formula tab with mapping rules that define how to select Multiple Tax Engines to handle tax calculation for various customer accounts. Refer to the Example tab to copy and customize pre-defined mapping formulas. For more information, see Tax Engine Mapping Formula.
  • Click Save.

Note that if you want to configure Multiple Tax Engines that include Zuora Tax, you need to add a tax code for Zuora Tax first, and then click Edit in the upper right of the panel. Fill in the Mapping Formula tab with mapping rules that define how to select Multiple Tax Engines to handle tax calculation for various customer accounts, and click Save.

The table of tax rate details will display only if you add a tax code for Zuora Tax before you configure Multiple Tax Engines by setting up the mapping formula. The tax rate must be configured using the same tax code.

Configure tax codes through settings API

Besides configuring tax codes through the Zuora UI as described above, you can also configure tax codes through the settings API.

Setting Key Context Http Method  Http URL  Parameter description  Setting description
AllTaxCode Entity GET /settings/tax-codes   Retrieve all tax codes
CreateZuoraTaxCode Entity POST /settings/tax-codes/ztax   Create tax code under Zuora Tax Engine
ZuoraTaxCode Entity GET /settings/tax-codes/ztax/{id} id = Unique Id of the tax code Retrieve tax code under Zuora Tax Engine
ZuoraTaxCode Entity PUT /settings/tax-codes/ztax/{id} id = Unique Id of the tax code Update tax code under Zuora Tax Engine
ZuoraTaxCode Entity DELETE /settings/tax-codes/ztax/{id} id = Unique Id of the tax code Delete tax code under Zuora Tax Engine
CreateAvalaraTaxCode Entity POST /settings/tax-codes/avalara   Create tax code under Avalara Tax Engine
AvalaraTaxCode Entity GET /settings/tax-codes/avalara/{id} id = Unique Id of the tax code Retrieve tax code under Avalara Tax Engine
AvalaraTaxCode Entity PUT /settings/tax-codes/avalara/{id} id = Unique Id of the tax code Update tax code under Avalara Tax Engine
AvalaraTaxCode Entity DELETE /settings/tax-codes/avalara/{id} id = Unique Id of the tax code Delete tax code under Avalara Tax Engine
CreateConnectorTaxCode Entity POST /settings/tax-codes/connector   Create tax code under Connect Tax Engine
ConnectorTaxCode Entity GET /settings/tax-codes/connector/{id} id = Unique Id of the tax code Retrieve tax code under Connect Tax Engine
ConnectorTaxCode Entity PUT /settings/tax-codes/connector/{id} id = Unique Id of the tax code Update tax code under Connect Tax Engine
ConnectorTaxCode Entity DELETE /settings/tax-codes/connector/{id} id = Unique Id of the tax code Delete tax code under Connect Tax Engine