This guide provides an overview of the configurable Tax app product features and related technologies. In addition, it contains recommendations on best practices, tutorials for getting started, and troubleshooting information for common situations.
Tax app overview
Zuora’s Tax app offers a pre-built integration that can efficiently deal with various tax types and rules. The Tax app connects you to the tax providers that hold the up-to-date tax rate data for numerous sales tax jurisdictions globally and eliminates the need for manual updates. You can use the Liquid Template Language to customize templates. The customization allows the dynamically created requests to be sent to your tax provider in order to automatically calculate the correct tax rates for invoices, with various account tax conditions, customer locations, and tax types and rules taken into consideration. With this app, Zuora makes it easier to integrate your existing tax services with our world-class subscription relationship management solutions.
The Tax app has various integrations corresponding to different tax providers. Only the following integrations of the Tax app can be found in Zuora Marketplace instead of the Tax app itself:
- Ability to generate custom tax requests.
- Automatically process all taxation items for invoices in real time.
- Utilize a variety of external tax providers.
- Use external tax providers of your choice to retrieve the most accurate taxes to date.
- Avoid maintaining tax rates in multiple locations.
- Customize your need to tailor reporting to your business.
- All processes are automated to ensure speed and accuracy.
Notes and limitations
If you use the configurable Tax app, Zuora calculates tax when invoices are posted. Draft invoices generated by bill runs do not contain tax calculations.
If the tax calculation fails for a particular invoice, the invoice will remain in draft status. This behavior is different from the behavior of Zuora's direct Avalara integration. See Direct Avalara integration.
The configurable Tax app does not return tax information for invoice item adjustments. The only method of AR supported by the configurable Tax app is Invoice Settlement (Credit Memos and Debit Memos).
Line item limitations exist with some vendors. Generally, the limitations involve time-outs when the number of Request lines is greater than 1,000. Contact your tax vendor to learn more about their specific timeout limitations.
This is a Zuora-defined limitation to ensure a stable integration across different tax vendors. If you have confirmed with your vendor that a higher number of taxable items can be processed in a timely manner (within 90 seconds), submit a request at Zuora Global Support and ask to test a higher limit.
Usage records (for location-based tax) are not visible to the connector.
You can only use one configurable Tax app in a single tenant.
To get started, you have to purchase an app first and create an OAuth login for your Tax app to connect to Zuora.
Purchase an app
You can purchase apps in the Marketplace that is available in your tenant.
- In the left navigation menu of Zuora, select Marketplace > Marketplace.
The available apps are displayed.
- Find the app that you want to purchase.
- Click Purchase on the overview page of the app.
Zuora will then contact you with information about completing the purchase and setting up the app.
Purchased apps can be used by all Zuora administrators and Zuora standard users in your organization.
To view your purchased apps, navigate to Marketplace->Purchases in your Zuora tenant. Before you can use a purchased app, you must install the app.
Create an OAuth login for your Tax app to connect to Zuora
Some apps use OAuth to authenticate to your Zuora tenant. This article explains how to create a Marketplace login that stores OAuth authentication details for you Zuora tenant. You can then select the Marketplace login when you install an app that uses OAuth.
To create a Marketplace login:
In your Zuora tenant, select Administration > Manage Users from the Profile & Settings menu, then create a user.
Apps that use OAuth to authenticate to your Zuora tenant will perform actions as this user.
Zuora recommends that you create an API user specifically for this purpose. See Create an API User for more information.
On the Users page in your Zuora tenant, select the user you created in the previous step, then create an OAuth client for the user.
See Manage Users for more information.
- Zuora displays the Client ID and Client Secret for the OAuth client. Copy and paste these details in a note when Zuora displays them (this aids in inputting them in the next step). This is the only time you can see the Client Secret.
- If the Client Id and Secret are not saved, or lost, you can simply remove the created OAuth client and create another one for the new Client ID and Client Secret.
In Zuora Connect, navigate to My Connect > Tenants, then select Zuora from the New Login menu:
The New Login dialog box opens.
In the New Login dialog box:
- Select your Zuora tenant's data center and environment type.
- Select OAUTH from the drop-down menu.
- Enter the Client ID and Client Secret for the OAuth client.
A tile for the new login displays on the Tenants page. An OAuth login has the token following the account name in the top of the tile.
When you install an app that uses OAuth, select the OAuth login in the New Configuration dialog box. See Install an App for more information.
The configurable Tax app provides the following customization options:
Dynamic Request Template - You can use the Liquid template language to customize the requests that Zuora sends to your tax provider. To customize the Dynamic Request Template, click the Template Configuration tab.
Headers - You can include custom headers in the requests that Zuora sends to your tax provider. To add a custom header, click the Tax Engines tab, then click the edit icon in the Actions column. The Update Tax Engine Settings dialog box opens with the Headers tab selected.
System Configuration - You can customize how Zuora validates tax credentials, how Zuora handles taxVoid calls, timeout durations, the number of retries, and how Zuora handles external failures. To modify these options, click the Tax Engines tab, then click the edit icon in the Actions column. The Update Tax Engine Settings dialog box opens. Click the System Configuration tab.
The configurable Tax app supports OAuth 2.0 for validating tax credentials.
Seller Information - You can customize the point of origin for taxation. To modify the seller information, click the Tax Engines tab, then click the edit icon in the Actions column. The Update Tax Engine Settings dialog box opens. Click the Seller Information tab.