Context

Zuora plans to upgrade to a REST API-based integration as today's Direct Avalara Integration currently uses a SOAP API-based setup

The REST API-based integration will allow customers to manage tax changes more efficiently, such as updates to tax policies in Chicago. For example:

• The Chicago Personal Property Lease Transaction Tax applies to transactions dated July 1, 2024, and later. Effective January 1, 2025, the Personal Property Lease Transaction Tax on certain rental and leasing categories is increasing from 9% to 11%. See details in Avalara website: Chicago Personal Property Lease Transaction Tax.

• Effective Jan 1, 2025, Chicago, IL is increasing the tax on streaming amusements from 9% to 10.25%. See details in Avalara website: Change to Chicago Amusement Tax.

Today, AvaTax still supports the SOAP API, but new features and enhancements will be developed on the REST API. AvaTax has been encouraging customers to migrate to the REST API given greater enhancements in performance and scalability.

Zuora will help migrate all customers from SOAP API to REST API integration with minimal disruption to every day business processes..

Who Should be Aware?

If you're using Zuora's Direct Avalara Integration, you'll want to be aware of the upcoming upgrade.

To check if you're using Zuora's Direct Avalara Integration, log in to Zuora, go to Settings -> Billing -> Setup Tax Engine and Tax Date. If you see "Avalara" listed under the Tax Engine column in the Tax Engines section, then you're using Direct Avalara Integration.

How to Upgrade?

Our goal is to ensure a smooth migration and maintain all existing functionality during the transition. Zuora will seamlessly upgrade customers, there is no action needed from your team as part of this upgrade.

To minimize disruption and ensure consistency, Zuora will be shadow testing both connections. While Zuora is testing in your Sandbox environment, it's crucial to confirm that your AvaTax configuration is fully prepared for the switch from SOAP to REST. Shadow testing allows us to make real API calls in both Sandbox and Production environments, comparing the results with your live configuration to identify any potential issues. Since each customer has unique configurations, shadow testing must be done individually to ensure everything works as expected.

During Shadow Testing, Zuora will select a few transactions to call the REST-based Tax Preview API (without saving the transactions) and compare the results with the SOAP-based API. This will help us verify that both APIs calculate tax consistently. Once we confirm there are no discrepancies, we'll be ready to switch to the REST API for your account. Since each customer may have unique configurations, we'll run Shadow Testing for each customer before upgrading to REST. You can find more details about Shadow Testing in the Q&A section.

Steps to Switch to REST Integration for Each Customer. These steps apply to both Sandbox and Production:

1. Enable Shadow Testing

2. Monitor for at least 31 days to cover a full month-end cycle and ensure thorough testing.

3. Switch to REST Integration if no issues are found. If any issues arise, we'll work with you to resolve them before proceeding.

When to Upgrade?

Zuora has completed extensive shadow testing in the Sandbox environment. Our plan is to roll out the REST API-based integration to Zuora Sandbox first, followed by Zuora Production. Here's a quick look at the timeline:

• Upgrade API Integration in Zuora Sandbox:
  Start Date: February 1st, 2025
  End Date: March 31, 2025

• Upgrade API Integration in Zuora Production:
  Start Date: April 1, 2025
  End Date: September 30, 2025

Please note that the timeline is tentative and may change.

Who Should You Contact?

As a Zuora customer, you can reach out to either Zuora Support or Avalara Support if you have any questions or run into any issues.

Q&A: Upgrading from SOAP API to REST API for Direct Avalara Integration

What's Shadow Testing?

We plan to conduct shadow testing in both the Sandbox and Production environments for each customer. Here's how it works:

• Select a portion of API calls: For each customer, we'll choose a sample of transactions and call the REST-based Tax Preview API (without saving any transactions) alongside the existing SOAP-based API.

• Comparison: We'll verify that both APIs return the same tax calculations.

• Customer-Specific Testing: Since every customer has unique configurations, shadow testing will be done individually for each one.

• No Transaction Impact: Zuora will only call the REST-based Tax Preview API, and no transactions will be saved on AvaTax's side during testing.

• Little to No Impact on Billing: Avalara has confirmed that API calls in the Sandbox won't affect your billing. For Production, as per Avalara's recommendation, we will minimize the number of calls to avoid any impact on customer usage, ensuring that the testing process has little to no impact on billing.

This is a general introduction on Shadow Testing. See the diagram below.

Why is shadow testing required on Production?

Zuora has completed comprehensive testing, including unit, functional, regression, and performance tests in the Sandbox environment. We'll be using a testing approach called "Shadow Testing" in both Sandbox and Production to ensure your AvaTax configuration is ready for the switch from SOAP to REST.

Shadow testing is necessary because it lets us make real API calls and compare the results with your live Production configuration. This helps identify potential issues before transitioning from SOAP to REST API.

Since every customer has unique configurations, shadow testing needs to be done individually for each customer to ensure everything works smoothly.

Are There Any Extra Charges for Zuora Customers Due to Shadow Testing?

For sandbox shadow testing, there are no additional charges, regardless of the number of shadow API calls.

For production shadow testing, Zuora follows Avalara's recommendation, which has little to no impact on billing.

Avalara suggests conducting tests in a customer's production account with minimal API calls to avoid affecting usage. Transaction volume is tracked in multiple ways, including committed Documents (1:1 ratio with saved transactions using the SalesInvoice flag) and non-Address Validation API calls (the "non-Address Validation API" is called for the Tax Preview API which is 10:1 ratio with the SalesOrder flag). At the end of each day, the higher number between the various measurements is counted as the customer's daily Transaction volume. Since minimal testing using non-Address Validation API calls typically doesn't exceed the committed Document count, the impact on customer usage and billing is low.

Shadow testing uses the Tax Preview API for comparison, but it only applies to Committed Transaction API calls. Zuora selects a sample of these calls for each customer, ensuring that the impact on usage and billing remains minimal.

For example, 1000 non-Address Validation API calls per day would equal 100 committed Documents, the equivalent of 100 Transactions. For customers with more than 100 committed Documents per day, this shadow testing using non-Address Validation API calls has no impact. However, for customers with fewer than 100 committed Documents per day, this testing approach may lead to a slight increase in usage. 

Although the likelihood of increased usage and billing is very low, please submit a ticket to the Avalara support team if you notice any unusual increase. Avalara will handle each case individually.

For more information about how Avalara tracks usage, please review the AvaTax Terms.

How will Zuora execute Shadow Testing on Production?

The testing approach for Production is well designed per Avalara's recommendation. See the diagram below.

Here are the details to describe how Zuora selects API calls for shadow testing.

• Shadow testing should be applied only to the Committed Transaction API, not the Tax Preview API.

• The Committed Transaction API is more critical because its tax results are included in legal documents, whereas the Tax Preview API is only used for estimation.

• Ensure this testing approach could cause little to no impact to billing per Avalara's recommendation. See details in the previous section.

• Select a portion of Committed Transaction API calls for each customer, based on their Committed Transaction API and Preview API volumes over the past two months. This will help minimize any impact on customer usage and billing. Zuora will make its best effort to determine the appropriate percentage of APIs for shadow testing. This approach helps us validate the new REST API integration while balancing test coverage and minimizing impact. For larger customers, we'll limit the number of Tax Preview API calls, while for smaller customers, we can run more extensive shadow tests.

• Path to Switching to REST Integration for Each Customer

1. Enable Shadow Testing in Production.

2. Monitor for 31 days to cover a full month-end cycle and ensure thorough observation.

3. Switch to REST Integration if no issues are found. If any issues arise, work with the customer to resolve them before proceeding.

How will Zuora Handle if issues are found during shadow testing?

Typically, the issue is about the configuration per our observation on Sandbox. E.g. If you've set up custom tax rules for Chicago Personal Property Lease Transaction Tax (PPLTT) as Sales tax and also have Nexus for RentalLeasing/Local TaxSubType for Chicago CIT selected, you may experience double taxation when switching to REST API-based Integration. Be sure to remove custom tax rules before switching to REST API-based Integration. Detailed instructions are provided in the next section.

Once Zuora observes any issue during shadow testing on Production, Zuora will reach out to the customer and provide the detailed instructions for the resolution. We'll not switch to the REST API integration for the customer until the issue is resolved.

How to avoid double taxation when switching to REST API-based Integration

For customers using Zuora's Direct Avalara Integration, manual configuration changes are required before switching to the REST API-based integration if they have the following configurations in AvaTax:

• Nexus enabled for either RentalLeasing/Local Tax SubType for Chicago CIT or Amusement/Amusement Tax Sub Type for Chicago CIT.

• Custom rules configured for Chicago Personal Property Lease Transaction Tax (PPLTT) or Chicago Amusement Tax.

Here are the steps:

1. Disable the Nexus for RentalLeasing/Local Tax SubType for Chicago CIT and Amusement/Amusement Tax Sub Type for Chicago CIT in the AvaTax web portal.

2. Enable the Zuora feature: "Direct Avalara REST API-Based Integration". To enable this feature, please submit a request to Zuora Global Support.

3. Delete any custom tax rules for Chicago Personal Property Lease Transaction Tax (PPLTT) and Chicago Amusement Tax. Please note: Step 4 should be completed immediately after Step 3.

4. Re-enable the Nexus for RentalLeasing/Local Tax SubType for Chicago CIT and Amusement/Amusement Tax Sub Type for Chicago CIT in the AvaTax web portal. For more details, refer to Avalara's website: Change to Chicago Personal Property Lease Transaction Tax and Change to Chicago Amusement Tax.

For customers who don't have these specific configurations, no action is needed from their side for this upgrade.

When is the End of Support Date for Direct Avalara SOAP API-Based Integration?

Zuora's Direct Avalara Integration on SOAP API-based integration will enter the end of support on October 1st 2025.

Zuora will no longer actively develop or enhance Direct Avalara Integration on SOAP API. Only critical, revenue-impacting defects with no workarounds or alternatives may be fixed at Zuora's discretion.

Can I stay on SOAP API?

Unfortunately, staying on the SOAP API is not an option moving forward. Zuora is working to migrate all customers to the REST API integration as quickly as possible. This transition ensures that all customers are on a modern architecture and can take advantage of new features and improvements.

Zuora has already announced an End of Support Date for the SOAP API-based Direct Avalara Integration, and eventually, we will also announce an End of Life date for SOAP API.

How to check if I am using REST API integration?

To check if your Direct Avalara Integration is using the REST API, go to the Tax Dashboard under System Health and review the tax request/response for your latest transactions. If the integration is running on REST, the request/response format will be in JSON instead of XML (SOAP API).

Will the REST API for Direct Avalara Integration be reset to SOAP API after the CSBX tenant refresh?

No, the REST API for Direct Avalara Integration will not revert to SOAP API after the CSBX tenant refresh.

The "Direct Avalara REST API-Based Integration" feature will remain unchanged for your CSBX (Central Sandbox) tenant during the refresh process, regardless of whether it's enabled or disabled in the production environment. Even though the feature isn’t enabled in production, your CSBX tenant will retain the feature as long as it was enabled before the refresh.

Who should we contact if we have questions about the upgrade?

Please submit a request at Zuora Global Support, if you have any questions about the upgrade. You can also contact Avalara Support if you have any questions.

------------------------------
Kevin Qu
Product Manager
Zuora
------------------------------