Tax engine mapping formula

Last updated
Save as PDF

Overview

When you set up tax codes and choose to use Multiple Tax Engines, you have the flexibility to select Multiple Tax Engines based on the mapping formula you have set up. For example, you can define a mapping formula where the Connect Tax Engine for the U.S. will handle tax calculations for your customers in the U.S., and the Connect Tax Engine for India will handle tax calculations for your customers in India.

Define the mapping formula

The mapping formula is constructed using the Liquid control flow tags (IF/ELSIF/ELSE/ENDIF). To define a mapping formula, you can use the following standard fields and custom fields on the account and soldToContact objects.

account
Field name	Notes
batch	Any system-defined batch (`Batch1` - `Batch50`) or customized batch name.
billCycleDay	Any activated system-defined bill cycle day (`1` - `31`).
currency	3-letter currency codes.
companyCode	A unique code that identifies a company account in a tax vendor, such as Avalara.
Custom fields	See Manage custom fields for details.

soldToContact
Field name	Notes
country	Valid country names in Zuora. For a complete list of supported country names, see View countries or regions.
state	Valid subregion names in Zuora. For a complete list of subregions of a specific country or region, see View subregions.
city	Specifies the city in the contact's address.

When you define the mapping formula, both the Multiple Tax Engines' names and the company codes associated with the Connect Tax Engines are required. To get the tax engine names and use the names in the formula, see the following examples. Note that Zuora Tax does not need a company code associated with it.
When the invoice owner and subscription owner are different for an invoice item, Multiple Tax Engines use the invoice owner's Account and Sold-to Contact information.

Examples

Example 1

Assuming that you use Zuora Tax in Japan, and use Direct Avalara Integration Tax Engine in the US and other countries. Create a new tax code for Zuora Tax first and then edit it in the tax code details page. For more information about how to add a tax code for Multiple Tax Engines, see Set up tax codes.

An example of the mapping formula is as follows. You can click Edit in the Basic Information panel, and fill in the Mapping formula tab with the following example:

{% if account.soldToContact.country == 'Japan' %}
    Zuora Tax
{% elsif account.soldToContact.country == 'United States' %}
    Avalara Direct Integration Tax Engine | Company_Code
{% else %}
    Avalara Direct Integration Tax Engine | Company_Code
{% endif %}

The Avalara Direct Integration Tax Engine in the formula is the tax engine name that you fill in the Name field when you first set up the engine for direct Avalara integration. The Zuora Tax in the formula is the tax engine name for Zuora Tax.

Note that the Company_Code in the example is the code that is configured when you use Direct Avalara Integration Tax Engine.

The formula defines how to select Multiple Tax Engines based on the country name of the Sold To Contact, a key contact for customer accounts:

When the country of the Sold To Contact of the customer account is Japan, select Zuora Tax for tax calculation.
When the country of the Sold To Contact of the customer account is the US, select Avalara Direct Integration Tax Engine for tax calculation.
By default, select Avalara Direct Integration Tax Engine for tax calculation.

Example 2

Based on Example 1, assuming that you use Direct Avalara Integration Tax Engine in the US and use Zuora tax in Japan, Germany, Austria, Switzerland, or other countries.

An example of the mapping formula is as follows. You can click Edit in Basic Information panel, and fill in the Mapping formula tab with the following example:

{% if account.soldToContact.country == 'United States' %}
    Avalara Direct Integration Tax Engine | Company_Code | External_Tax_Code
{% else %}
    Zuora Tax
{% endif %}

The Avalara Direct Integration Tax Engine in the formula is the tax engine name that you fill in the Name field when you first set up the engine for the corresponding tax apps, in this case it is Vertex. The Zuora Tax in the formula is the tax engine name for Zuora Tax.

Note that the External_Tax_Code in the example is the Avalara Tax Code that is configured in Zuora Billing, whose value is expected to match with that defined in Avalara systems.

The formula defines how to select Multiple Tax Engines based on the country name of the Sold To Contact, a key contact for customer accounts:

When the country of the Sold To Contact of the customer account is the US, select the Avalara Direct Integration Tax Engine for tax calculation.
By default, select Zuora Tax for tax calculation.

Example 3

Assuming that you use the Vertex O Series tax connector app in the US and use Zuora tax in Japan, Germany, Austria, Switzerland, or other countries. Create a new tax code for Zuora Tax first and then edit it in the tax code details page. For more information about how to add a tax code for Multiple Tax Engines, see Set up tax codes.

An example of the mapping formula is as follows. You can click Edit in Basic Information panel, and fill in the Mapping formula tab with the following example:

{% if account.soldToContact.country == 'United States' %}
    Vertex_TaxConnector_engine_name | Company_Code    
{% else %}
    Zuora Tax
{% endif %}

The Vertex_TaxConnector_engine_name in the formula is the tax engine name that you fill in the Name field when you first set up the engine for the corresponding tax apps, in this case it is Vertex. The Zuora Tax in the formula is the tax engine name for Zuora Tax.

Note that the Company_Code in the example is the code that is configured when you set up Connect Tax Engines.

The formula defines how to select Multiple Tax Engines based on the country name of the Sold To Contact, a key contact for customer accounts:

When the country of the Sold To Contact of the customer account is the US, select the Vertex_TaxConnector_engine_name for tax calculation.
By default, select Zuora Tax for tax calculation.

Example 4

Based on Example 3, assuming that you have two company codes separately for the UK and the US.

An example of the mapping formula is as follows. You can click Edit in Basic Information panel, and fill in the Mapping formula tab with the following example:

{% if account.soldToContact.country == 'United States' %}
    Vertex_TaxConnector_engine_name | Company_Code_US
{% elsif account.soldToContact.country == 'United Kingdom' %}
    Vertex_TaxConnector_engine_name | Company_Code_UK
{% else %}
    Zuora Tax
{% endif %}

The formula defines how to select Multiple Tax Engines based on the country name of the Sold To Contact, a key contact for customer accounts:

When the country of the Sold To Contact of the customer account is the UK or the US, select the corresponding Vertex_TaxConnector_engine_name with different company codes for tax calculation.
By default, select Zuora Tax for tax calculation.

Example 5

Assuming that you have business in multiple countries and regions, and you use multiple tax engines that integrate with tax vendors through Configurable tax apps. For example, you have acquired three companies in the supported regions, and those companies have separate contracts with Vertex.

Create a new tax code for Connect Tax Engine with the Use Multiple Connect Tax Engines checkbox selected. Alternatively, if you have an existing tax code for Connect Tax Engine, enable Use Multiple Connect Tax Engines. For more information about how to add a tax code for Multiple Tax Engines, see Set up tax codes.

You can fill in the Mapping formula tab with the following example of the mapping formula:

{% if account.region__c == 'North America' %}
    Vertex_TaxConnect_Engine_1 | Company_Code_1
{% elsif account.region__c == 'EMEA' %}
    Vertex_TaxConnect_Engine_2 | Company_Code_2
{% elsif account.region__c == 'LATAM' %}
    Vertex_TaxConnect_Engine_3 | Company_Code_3
{% else %}
    TaxConnect_Engine_Default | Company_Code_Default
{% endif %}

The Vertex_TaxConnect_Engine_1 in the formula is the tax engine name that you fill in the Name field when you first set up the engine for the corresponding tax apps, in this case it is Vertex. Likewise, Vertex_TaxConnect_Engine_2,Vertex_TaxConnect_Engine_3, and TaxConnect_Engine_Default in the formula are the tax engine names that you fill in the Name field when you first set up the engine for the corresponding tax apps.

The preceding example illustrates that you can select Connect Tax Engines based on custom fields on Account.

Zuora provides more examples for you to copy and customize. To use these examples, refer to the Example tab after selecting the Use Multiple Connect Tax Engines checkbox when setting up tax codes.

Use the mapping formula

After setting up the tax formula, you need to associate the tax code to a product rate plan charge and set the tax mode. The system looks for tax engines through the tax code associated to the taxable product when calculating the tax amount on a billing document, such as invoice, credit memo, or debit memo.

Troubleshoot: no tax engine is populated

During tax calculation, there might be situations where no tax engine is populated based on the mapping formula. For example, imagine a scenario where:

You divide your customers into Batch 1 and Batch 2. You offer two product rate plan charges, where Charge 1 is taxable and Charge 2 is not taxable. Customers in both Batch 1 and Batch 2 all have Charge 1 and Charge 2 in their subscriptions.

Customers	Batch 1	Batch 2
Subscriptions	Charge 1 & Charge 2	Charge 1 & Charge 2

You set up Tax Code 1 and provide a mapping formula as below. It defines that for customers in Batch 1, use ConnectTaxEngine1 to calculate taxes on their billing documents, such as invoices.

{% if account.batch == 'Batch1' %}
  ConnectTaxEngine1 | CompanyCode1
{% endif %}

When you create a bill run to generate invoices for those customers:

For Batch 1 customers, the invoice item for Charge 1 will have a tax item. Based on the mapping formula in Tax Code 1, ConnectTaxEngine1 will be selected to calculate the taxes.

Customers	Batch 1
Invoice item	Charge 1 (taxable)	Charge 2 (not taxable)
Tax	Tax Code 1 > ConnectTaxEngine1	No tax code

For Batch 2 customers, though Charge 1 also needs to be taxed, no tax engine will be selected based on the mapping formula, and the error message “No tax engine is populated, check your mapping formula in Tax Code 1.” will appear.

Customers	Batch 2
Invoice item	Charge 1 (taxable)	Charge 2 (not taxable)
Tax	Tax Code 1 > No tax engine is returned > Error	No tax code

In this case, you need to refine the mapping formula to make sure it covers all customers who subscribe to the product rate plan charge associated with the tax code. To solve the issue, you could move the customers from Batch 2 into Batch 1 if you need to charge tax for those customers or update the mapping formula to cover Batch 2, such as:

{% if account.batch == 'Batch1' %}
    ConnectTaxEngine1 | CompanyCode1
{% elsif account.batch == 'Batch2' %}
    ConnectTaxEngine1 | CompanyCode1
{% endif %}