Skip to main content

Avalara AvaTax for Sales app

Zuora

Avalara AvaTax for Sales app

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.

Prerequisites

Install the app

Follow the instructions in Install an App to install the app. Specific to the Tax app: 

  • Run mode - Select the tax vendor you want to use.
  • Tax - Select the desired credentials to the selected tax vendor. If no desired credential can be found, click New to create the credentials for the new Tax instance.

Access the app

To access the app: 

  1. Go to the Billing Settings page in your Zuora tenant. Click the Setup Tax Engine and Tax Date box. Under the Tax Engines section, you will find the Configurable Tax Apps section with links to the apps you have installed. 
  2. Click the name of the app to launch it.

Configure the app

1. Configure templates

The Dynamic Request Template is the body of the request where Zuora populates invoice information that can be configured based on your needs. Templates are dynamically rendered using the Liquid Template Language and are provided in the Text/XML or Application/JSON format.

To configure a dynamic request template:

  1. Launch the created Tax instance and click the TEMPLATE CONFIGURATION tab. 
  2. Select the tax engine for which you want to configure templates from the Tax Engine dropdown list.
  3. Select the tab for the template (Standard or taxVoid) you want to configure.
    Zuora provides you with two templates, the Standard template and the taxVoid template; but only the Standard template is required to be completed. Tax systems have many configuration options. The template does not have to use all the options and must be configured based on the required information of the request. Templates can include more fields than the required set of fields in the request. Refer to your tax vendor’s API documentation or contact their support to learn more about how their fields are formatted. 
    In the case of a failed payment where rollback of the Subscribe call and deleting the invoice is desired, a taxVoid template is necessary to send a request to the tax vendor to also void the invoice and subsequent tax records from their system. For more information, see Configure the taxVoid template.
  4. Add a new template or modify the default template in the text box.
    To view all available fields and corresponding values that can be used in the template:
    1. Click Show Liquid Examples.
    2. Select the desired field in the Example Field dropdown list, the corresponding value you can copy and paste in the template is displayed under Example Value. The fields in the following objects are available for selection. See Context object for rendering tax app templates for more information.
      • customer
      • seller
      • document
      • document_item
  5. When you complete the configuration, click configure_icon.png and then select Preview Template to preview the configured template. If you want to start over, you can click configure_icon.png and select Revert Template to Default.
  6. Click Save Both Template below the text box to save the template configurations.

Configure the taxVoid template

If the taxVoid Call Handling option is set to Enable, Zuora uses the taxVoid template when sending a request to the tax vendor to void billing documents and subsequent tax records. The supported document types are Invoice, Credit Memo, and Debit Memo. 

In the taxVoid template, setcode toDocVoided. For example:

{
  "code": "DocVoided"
}

Tax vendor requirements for voiding tax calls vary. Contact your tax vendor to determine whether additional information needs to be included to void the document. Note that the taxVoid template currently only supports theidtransactionId, taxCompanyCode and invoiceNumber fields on the document object

2. Configure engine settings

After configuring the template, take the following steps to configure engine settings:

  1. Click the ENGINE SETTINGS tab.
  2. Click edit_icon.png for the tax engine that you want to configure. The tax engine details window is displayed.
  3. In the Headers tab, select the value forContent-Typein the Value dropdown list. You can click Add Header to add additional headers that will be added to the tax requests that are sent to your tax vendor. 
  4. Click the System Configuration tab and complete the system configuration. 
    • Select an authentication type in the Authentication Type dropdown list. Consult your tax vendor for further information regarding your specific authentication type and credentials. 
    • Select an option from the taxVoid Call Handling dropdown list:
      • Pass Through - Allows the call to process without any issue, but tax will not be processed.
      • Block - Does not allow the call to process and will generate an error message.
      • Enable - Allows the call to pass and will either process tax or generate an error message. For more information, see Configure the taxVoid template.
    • Optionally, you can select Skip Taxation on External Failure. When this option is selected, taxation will be skipped in the case of external failures such as network issues or error responses from the vendor side.
  5. Complete the information in the Seller Information tab. The information that is required to be completed varies depending on the selected tax engine requirements. Check with your tax engine vendor for details. 
  6. Click UPDATE to save the configuration for each tab.

Process large billing documents

Zuora's Avalara AvaTax for Sales app can support a maximum of 15,000 taxable line items in a single invoice, credit memo, or debit memo. To process a large billing document in a single tax calculation request: 

  1. Go to ENGINE SETTINGS > Click edit_icon.png > System Configuration tab.
  2. In the NETREAD TIMEOUT(SECONDS) field, increase the timeout seconds up to 600. (Default is 60.)
  3. Click UPDATE to save the change.

On the tax vendor side, the Avalara AvaTax for Sales can support a maximum of 15,000 taxable line items in a single tax call. If you have confirmed with the tax vendor that a higher number of items can be processed in a timely manner (within 120 seconds), submit a request at Zuora Global Support and ask to test a higher limit. 

Tips: We suggest that you post invoices and calculate tax via bill runs, as the asynchronous operations are not limited by the designated network timeout in Zuora Billing. If you use Zuora UI or synchronous API calls, it is better to check the result back in about 5 to 10 minutes, depending on the size of the invoice.

Configure rate plans

After the tax app is installed and configured, take the following tasks before using the configured tax instance:

1. Set up Connect Tax Engine

To set up a Connect Tax Engine:

  1. In your Zuora tenant, click your username at the top right and navigate to Settings > Billing.
  2. Click Setup Tax Engine and Tax Date.
  3. Select Connect Tax Engine from the list, and click Set up new tax engine. You can create a maximum of 10 Connect Tax Engines.
  4. 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:
      1. Access the app through Setup Tax Engine and Tax Date under Billing settings.
      2. Navigate to the APP INFORMATION tab, the API token is listed near the top of the tab. 
  5. In the Custom Fields sent to the Open Tax Connector area, select all the custom fields that you want to use in the tax request for tax calculation. Failure to select them will result in blank values being used in the corresponding Liquid objects. See Manage Custom fields for more information.
    Note: 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.
  6. Click Save to save the configurations.
  7. 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 the Tax Engine list to view the Connect Tax Engine you just created. 

  • If you want to remove an existing Connect Tax Engine referred to by a tax code, you must first remove the tax code before removing the Connect Tax Engine. 
  • When setting up a new tax engine, you will encounter the old user interface (UI). However, to access advanced settings such as Tax Void Call Handling, Custom Fields, Seller Information, request templates, preview a rendered request, and much more, you must utilize the new UI. This new UI is accessible only when editing an existing tax engine that you have created. Ensure to use the Edit function to access the new UI for configuring advanced settings and making modifications to your tax engine setup. 

Edit existing Connect Tax Engine

It is highly recommended that you utilize the New Tax UI for editing, as it provides a convenient way to modify all Connect Tax Engine settings in a centralized location. The old UI can still be used to modify important details such as name, connect token, and custom fields sent to the Connect Tax App. But you’ll have to access the Connect UI to modify credentials and configure the templates.

When editing an existing Connect Tax Engine, access the advanced settings available exclusively in the new UI. To modify a previously created tax engine, follow these steps:

  1. In your Zuora tenant, navigate to Settings > Billing by clicking your username at the top right.
  2. Click Setup Tax Engine and Tax Date.
  3. From the Tax Engines list, click Edit next to the tax engine you want to modify.
  4. The tax engine details will open with the new UI containing the Engine Name, Vendor, Environment, and Authentication details that you created.
  5. You can now create advanced settings as listed here:

Field

Description

Engine Name

The name of the engine you wish to use. 

Vendor

The name of the third-party vendor.

Environment

The environment where the tax engine will be applied.

Authentication Type

For Basic Auth, your tax vendor account credentials are your username and password.

If Avalara Brazil is selected as the vendor, OAuth 2.0 is the default authentication type. Enter the client ID and client secret from your tax vendor. Refer to Avalara Brazil's documentation for authentication setup.

Advanced Settings

Tax Void Call Handling

The option to determine whether the external Vendor must be voided. The available options are:

  • PassThrough - No call will be made to the vendor; however, the Invoice  Cancel Post will be successful (as it says Pass Through)

  • Enable - A call will be made to the vendor.

  • Block -  No call will be made to the vendor, and it will return blocked (i.e., Invoice Cancel Post wouldn't be successful).

Netread Timeout

The duration of time is minutes before the timeout occurs.

Request Headers

The option to add additional headers to your tax requests.  While custom headers may not be frequently necessary, they prove beneficial in situations where authentication is required through firewalls or in other specific scenarios.

Field Mappings

The option to retrieve data from the tax engine response and store it on the Taxation Item object. For more information on Flexible Field Mapping, see Flexible Tax Mapping.

Custom Fields

The option to select existing custom fields for the tax engine.

Company and Seller Information

The option to add company code, name, and address.

  1. In the Request Template section, configure the template as required. Click Use Default Template to use the preconfigured template. The Request Template, in Text/XML or Application/JSON format, is where Zuora populates invoice information based on your configuration.
  2. Click Save after updating the settings to ensure the changes are saved.

2. Set up taxation code

To set up a tax code that uses the Connect Tax Engine:

  1. Click your username at the top right and navigate to Settings > Billing.
  2. Click Setup Taxation Codes.
  3. Click add new tax code.
  4. In the Basic Information area, complete the tax code details:
  • Tax Code Name: Enter the name of the tax code to be selected in the product catalog when discerning which Connect Tax Engine the charges will use to calculate tax.
  • Use Multiple Connect Tax Engines: Select this checkbox if you want to use multiple Connect Tax Engines.
    Selected Not selected
    Tax Engines: Fill in the Mapping Formula tab with mapping rules which define how to select different Connect Tax Engines to handle tax calculation for various customer accounts. Refer to the Example tab to copy and customize pre-defined mapping formulas. See Tax Engine Mapping Formula for more information. Tax Engine: Select the name that you have specified for the Connect Tax Engine.
    External Company Code: Select the company code created when setting up the Connect Tax Engine.
  • Active: This is No by default. You will activate it later.
  • Description (Optional): Describe the tax code and the tax app that will be used for future reference.
  1. Click save.
  2. Click Activate to ensure the tax code is present in the product catalog.

3. Activate tax code in product rate plans

To activate the tax code in your product rate plans:

  1. From the left-hand navigation of the Zuora UI, click Product Catalog.
  2. Click the name of the product where you want to change its rate plan.
  3. Select an existing rate plan or create a new rate plan to use the tax code. See the following articles for more information:
  1. Hover over the title and click Edit to edit the rate plan. 
  2. Complete the details in the Taxation section of the selected rate plan:
  • Taxable: Select this check box to enable the rate plan to be taxable.
  • Tax Mode: Select the desired tax mode:
    • Tax Exclusive: Tax is excluded from the charges.
    • Tax Inclusive: Tax is included in the charges.
  • Tax Code - Select the desired tax code in the dropdown list.
  1. Click save.

Test the app

After the Avalara AvaTax for Sales app is configured, take the following steps to test the app:

  1. Access the app by navigating to Billing Settings > Setup Tax Engine and Tax Date.
  2. Create a test product in your product catalog. See Create a product in product catalog for more information on creating a product. 
  3. Create a subscription on an account with only the test product. See Create subscriptions for more information.
  4. Define billing rules. Navigate to Settings > Billing > Define Billing Rules > edit in your Zuora tenant. 
  5. Create a bill run for the test account and generate an invoice. See Create bill runs for more information.
  6. Post the invoice. If the tax value is displayed on your invoice, your template was configured correctly and can be used for future bill runs. If you don't see any tax displayed on the invoice, troubleshoot and test your configurations using CURL requests. For more information see, System Health for tax log monitoring.