Connect Tax Engines

Last updated
Save as PDF

Zuora provides Connect Tax Engines for integration with tax vendors through Configurable tax apps. You can easily set up and configure multiple Connect Tax Engines based on your business needs. This feature is beneficial when you start selling in new markets out of your home country, which requires compliance with international tax rules and regulations.

The Connect Tax Engines feature is in Limited Availability. If you wish to have access to the feature, submit a request at Zuora Global Support.

Use cases

Use case 1: Entering a new market organically

You are doing well in the U.S. and want to sell the same product in Brazil. The Connect Tax Engine you have been using in Zuora can only handle tax calculation and compliance requirements for the U.S. market. It does not work for Brazil, which has very different tax types, rates, and regulations.

In this case, you can create a new Connect Tax Engine for Brazil and configure the tax code associated with the product you sell in both countries to select different tax engines for different countries. You can achieve this flexibility by setting up a mapping formula based on country names, a standard field on the customer accounts.

Without having to duplicate your whole product catalog for Brazil, you can quickly handle tax issues in the new market and speed up your expansion.

Use Case 2: Entering new markets through acquisition

You acquired three companies as dealers to help you sell the same product in North America, Europe (116 countries), and LATAM (20 countries). Each of the acquired companies has a separate contract with their regional tax vendors.

In this case, you can create three Connect Tax Engines and configure the tax code associated with the product to select different tax engines for different dealers. You can achieve this flexibility by creating a “dealer” custom field on the customer accounts and setting up a mapping formula based on this custom field.

Without having to change the existing tax practices of the acquired companies, you can quickly leverage the acquisition to achieve business results in the new markets.

Set up Connect Tax Engines

Prerequisite: Before setting up Connect Tax Engines, you need to purchase the tax app you want to use from the Marketplace and install it in your Zuora tenant. See Configurable tax app for information about purchasing an app and installing it in Zuora Billing.

To set up a Connect Tax Engine:

In your Zuora tenant, click your username at the top right and navigate to Settings > Billing.
Click Setup Tax Engine and Tax Date.
Select Connect Tax Engine from the list, and click setup new tax engine. Note that you can create at most 10 Connect Tax Engines.
In the Basic Information area on the Setup Tax Engine page, specify the basic information for the new tax engine:

Name: Name the Connect Tax Engine you would like to use in Zuora. For example, Avalara Brazil, India Local Tax, Avalara Telco, etc.
Connect Token: Enter the unique 32-character API Token of the Tax app. To obtain your API Token:

Access the app through Setup Tax Engine and Tax Date under Billing settings.
Navigate to the APP INFORMATION tab, the API token is listed near the top of the tab.

In the Custom Fields sent to Open Tax Connector area, select all the custom fields that you want to use in the tax request for tax calculation. You can select both Legacy Custom Fields and Advanced Custom Fields.

Failure to select them will result in that blank values are used in the corresponding Liquid objects. See Manage custom fields for more information.
The maximum number of custom fields you can select varies depending on your Zuora edition or Zuora modules. For more information, see Zuora Editions and Zuora Modules.
Click save to save the configurations.
In the Company Information area, add at least one Company Code to activate a tax code.

After completing the previous steps, you can click back to Tax Engine list to view the Connect Tax Engine you just created. If you want to modify it, click Edit. If you want to remove it, click Delete.

If you want to remove an existing Connect Tax Engine referred by a tax code, you need to first remove the tax code before removing the Connect Tax Engine.

You can also set up and configure Connect Tax Engines through the Settings API. The following operations are supported:

Operation	HTTP Method	HTTP URL	Note
Create a Connect Tax Engine	`POST`	https://rest.zuora.com/settings/tax-engines/connector	You can create at most 10 Connect Tax Engines for your Zuora tenant.
Retrieve a Connect Tax Engine	`GET`	https://rest.zuora.com/settings/tax-engines/connector/{id }
Update a Connect Tax Engine	`PUT`	https://rest.zuora.com/settings/tax-engines/connector/{id}
Delete a Connect Tax Engine	`DELETE`	https://rest.zuora.com/settings/tax-engines/connector/{id}

See Connect Tax Engines Settings for request/response samples.

Work with Connect Tax Engines

You can use one or multiple Connect Tax Engines by setting up a tax code, then associate the tax code to the taxable product rate plan charge.

If you are using one Connect Tax Engine and have duplicated the same product rate plan charge for different markets, you might want to switch to multiple Connect Tax Engines to simplify your product catalog, adapt to taxability changes, and pave the way for future expansions.

Let us use the following example to explain the steps and impacts when switching to multiple Connect Tax Engines.

Your existing system setups:

Tax Code 1: Use ConnectTaxEngineUS to calculate tax for U.S. customers.
Product Rate Plan Charge 1 (for U.S. customers): Taxable and is associated with Tax Code 1
Product Rate Plan Charge 2 (for Brazilian customers): Duplicate of Charge 1. Not taxable.

Later, you decide to use multiple Connect Tax Engines as the product will become taxable in Brazil. You make the following changes to system setups:

Set up a new Connect Tax Engine called ConnectTaxEngineBrazil to calculate tax for Brazilian customers.
Tax Code 1: Select Use Multiple Connect Tax Engines and define a mapping formula based on the country of Sold To Contact:

{% if account.soldToContact.country == `United States` %}
   ConnectTaxEngineUS | USCompanyCode
{% elsif account.soldToContact.country == `Brazil` %}
   ConnectTaxEngineBrazil | BrazilCompanyCode
{% endif %}

Expire Product Rate Plan Charge 2.
Amend subscriptions of Brazilian customers to remove Product Rate Plan Charge 2 and add Product Rate Plan Charge 1.

Impact on credit memos

Credit memos are only available if you have enabled Invoice Settlement.

After you switch to Use Multiple Connect Tax Engines for an existing tax code, if you need to create credit memos for invoices before the switch, you need to create the credit memo from invoices or by bill run. Creating the credit memo from charges will use the latest tax engine selected by the mapping formula.

To explain the impact, let us build on the previous example. Suppose you switch to multiple Connect Tax Engines to handle taxes for Brazilian customers on 2022-01-01.

Scenario 1	Scenario 2
You need to issue a credit memo on 2022-01-15 to settle a service dispute from last October. You can create this credit memo from the related invoice for the period from 2021-10-01 to 2021-10-31. This credit memo will not have tax.	You need to refund a customer who cancels his subscription for the month of last December. You can create this credit memo from a bill run on 2022-01-15 to refund the customer for the period from 2021-12-01 to 2021-12-31. This credit memo will not have tax.
Note: if you create the credit memo in both scenarios from Product Rate Plan Charge 1, the credit memo will have a tax based on the latest tax code configuration.

Notes and limitations

You can create at most 10 Connect Tax Engines for your Zuora tenant.
You can use at most 40 company codes for integration with a tax vendor through a configurable tax app.
You can only use one Connect Tax Engine for tax calculation and compliance requirements within the same account. Multiple Connect Tax Engines for the same account, invoice, or memo are not supported at this time.