Skip to main content

Tax Engine Mapping Formula

Zuora

Tax Engine Mapping Formula

This function currently only applies to Connect Tax Engines. We will expand its support for other tax engines later.

Overview

When you set up tax codes and choose to use Multiple Connect Tax Engines, you have the flexibility to select Connect 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/ELSEIF/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.
state Valid Canadian province names and U.S. state names in Zuora.

When you define the mapping formula, both the Connect Tax Engine name and the company code associated with that Connect Tax Engine are required.

Example

Below is an example of the mapping formula.

{% if account.soldToContact.country == `Brazil` %}
  AvalaraBrazil | BrazilCompanyCode
{% else if account.soldToContact.country == `India` %}
  IndiaLocalTax | IndiaCompanyCode
{% else %}
  AvalaraTelco | AvalaraCompanyCode
{% endif %}

It defines how to select the three Connect 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 Brazil, select the Connect Tax Engine called AvalaraBrazil for tax calculation.
  • When the country of the Sold To Contact of the customer account is India, select the Connect Tax Engine called IndiaLocalTax for tax calculation.
  • When none of the conditions are met, select the Connect Tax Engine called AvalaraTelco for tax calculation.

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
{% else if account.batch == 'Batch2' %}
    ConnectTaxEngine1 | CompanyCode1
{% endif %}