Because Avalara has updated to the Transport Layer Security (TLS) 1.2, the support for the TLS versions 1.0 and 1.1 has been disabled for REST v2 API endpoints in the Sandbox environment on 2/1/2022 and in the Production environment on 3/31/2022. Zuora has made necessary actions to ensure the integration with Avalara supports TLS 1.2. You do not need to take any additional action.
Zuora's direct Avalara integration makes it easy to calculate and report tax when you have nexus in multiple tax jurisdictions. If you want to have access to the Direct Avalara Integration feature, submit a request at Zuora Global Support.
Avalara is a third-party tax engine service that is useful when you have nexus in multiple locations. It holds up-to-the-minute tax rate data for thousands of sales tax jurisdictions around the world. Avalara automatically calculates the correct tax rates for your billing documents (invoices, credit and debit memos) by taking into account a variety of tax conditions including your nexus, the customer's location, tax types and tax rules.
It is particularly useful for customers who:
- Operate in a large number of tax jurisdictions, either across the U.S. or globally.
- Deal with many tax types and complicated tax rules.
- Update thousands of different tax rates every month.
- Submit tax reports for multiple tax jurisdictions with different deadlines and procedures.
The tax engine handles the update process for you, removing the need for you to update new tax rates manually. You may already use Avalara in your business, and by leveraging the integration with Zuora you avoid having to maintain tax rates in multiple locations.
Avalara also helps to manage address changes. For example, if an unincorporated area annexes to a city or county, Avalara is responsible for incorporating these updates. The service can also provide tax advice and value added services such as generating and submitting tax reports.
Secured communication between Zuora and Avalara
The Avalara AvaTax integration is a server-to-server communication between Zuora and Avalara servers. The connection is through the Transport Layer Security (TLS) protocol. All customer credentials are protected and follow industry best practices.
Avalara integration features
Zuora is tightly integrated with the Avalara tax engine, and can calculate real-time tax rates when performing billing operations in bill runs and API calls. By connecting your Avalara account to Zuora you can:
- Calculate tax rates in bill runs.
- Calculate real-time tax rates in all SOAP API calls that generate an invoice; subscribe(), amend() and generate().
- Calculate real-time tax rates in all REST API calls that generate a billing document.
- Preview real-time taxes in subscribe() and amend() SOAP API calls and various REST API calls.
- Calculate tax values for invoice item adjustments (IIA) through the Zuora UI and SOAP API. This is only for the invoice items with the Charge or Discount processing type. See Avalara Taxes in Invoice Item Adjustments for more information.
If required, it is possible to configure Avalara to calculate taxes for some of your rate plan charges, and use Zuora Tax or another third party tax engine for other rate plan charges. A single billing document can contain items taxed by two or more tax engines.
To start using Avalara to calculate your tax rates, see Configure Integration with Avalara.
When integrated with the Avalara real-time tax engine, your company code will be used as the tax code for calculating tax.
Tenants with Avalara enabled can pass a Value Added Tax ID to Avalara. You can use Avalara to calculate taxes according to European Union tax rules.
Tax request mapping between Zuora and Avalara
See Tax request mapping between Zuora and Avalara for details on how data fields in Zuora are used in Avalara for tax calculation when posting billing documents.
Integration ID mapping between Zuora and Avalara
In Zuora's Avalara integration, the integration ID mapping is about which Zuora field is used as
DocCode in the Avalara system. By default,
Number is used as
DocCode in the Avalara system. For example,
If the Sequential Billing Document Number feature is enabled, the integration ID mapping between Zuora and Avalara becomes different.
To enable the Sequential Billing Document Number feature, set the Enable Sequential Billing Document Number? billing rule to Yes.
After the Sequential Billing Document Number feature is enabled, the billing document type and ID is used as
DocCode in the Avalara system. For example,
This behavior change aims to avoid that the billing document number is lost due to tax calculation errors like incomplete addresses.
With the Sequential Billing Document Number feature, when doing the reconciliation between Zuora and Avalara, you have to use
DebitMemoID to map
Document.DocCode on the Avalara side. You can either add the
DM- prefix to the corresponding billing document ID, or remove
The Avalara Connector is a legacy solution that some existing tenants use. The Avalara Connector calculates tax rates in batches during bill runs and invoice item adjustments. This method has a number of limitations, however, and all new Zuora customers are encouraged to use the real-time Avalara integration.
See the Zuora2Avatax Configuration and User's Guide for detailed instructions about using the Zuora2Avatax connector.
If you are currently using the Avalara Connector to calculate tax rates in batches, and would like to migrate to the real-time integration, see Migrate from Avalara Connector to Avalara Integration.
How to use Avalara
Avalara taxes in API calls and bill runs
Tax rates for billing documents created through calls to the Zuora SOAP and REST APIs can be calculated in real-time using the Avalara API. Tax rates for billing documents created through bill runs are calculated asynchronously in batches.
For more information on calculating taxes with Avalara when generating and posting billing documents with API calls and bill runs, see Avalara taxes in API calls and bill runs.
Generate tax reports in Avalara
One of the many benefits of using Avalara to calculate your tax rates is that it provides advanced reporting functionality. To find out how to generate a wide range reports, see Generate tax reports in Avalara.
Notes and limitations
If you use the direct Avalara integration, Zuora calculates tax when invoices are generated.
If the tax calculation fails for a particular invoice, the invoice will be canceled. This behavior is different from the behavior of Zuora's configurable Tax app. See Configurable Tax app.
There are currently some limitations to bear in mind when using the Avalara integration. Some of these are limitations of Avalara's service, and others are gaps in functionality that are currently in development. For more information, see Limitations of Avalara integration.