Skip to main content
Zuora Logo

Get started with Sovos Tax Connector app

Zuora

Get started with Sovos Tax Connector app

  1. Last updated
  2. Save as PDF

To get started with Sovos Tax Connector app, go through the following procedure.

  1. Submit a request at Zuora Global Support to enable the Connect Tax Engines feature in your Zuora tenant.
  2. Install the Sovos Tax Connector app.
  3. Configure the Sovos Tax Connector app.
  4. Test the Sovos Tax Connector app.

Install the Sovos Tax Connector app

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

  • Run mode - Select the tax provider you want to use.
  • Tax - Select the desired credentials to the selected tax provider. If no desired credential can be found, click New to create the credentials for the new Tax instance.
    • Username and Password - The credentials for your tax provider account. 
    • Security Token - The security token for your tax provider account. If you have specified the username and password for your tax provider account, this field is not required.
    • URL - The endpoint of your tax provider account. Contact your Tax Provider for the specific URL endpoint required in this field.

Configure the Sovos Tax Connector app

After installing the Sovos Tax Connector app, perform the following tasks to set up the app in your Connect tenant:

  1. Configure templates
  2. Configure request settings

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.

Perform the following steps to configure a dynamic request template:

  1. Launch the created Tax instance and click the Template Configuration tab. 
    tax_templates_config.png
  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 called Standard template and 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 provider’s API documentation or contact their support to learn more about how their fields are formatted. 
  4. Add a new template or modify the default template in the text box.
    Note that the Vertex Tax Engine app now supports Vertex flexible fields using defined custom fields in your Zuora tenant.
    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:
      • Customer
      • Seller
      • Document
      • Document Item
  5. When you complete the configuration, click  and then select Preview Template to preview the configured template. If you want to start over, you can click  and select Revert Template to Default.
  6. Click Save Both Template below the text box to save the template configurations.

Configure engine settings

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

  1. Click the Engine Settings tab.
    tax_engine_settings.png
  2. Click the  icon for the tax engine that you want to configure. The tax engine details window is displayed.
     tax_engine_settings_headers.png
  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 provider. 
  4. Click the System Configuration tab and complete the system configuration. 
    • Select an authentication type in the Authentication Type dropdown list. Consult your tax provider for further information regarding your specific authentication type and credentials. 
      • None - No authentication required.
      • Basic-Auth - Will require Username and Password to be entered.
      • BearedId - Will require Token to be entered.
      • HMAC-SovosTaxware - This option is only available if you selected the SovosTaxware run mode when installing the Tax app.
    • 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.
    • 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 provider for details.
     
  6. Click Save Engine Settings to save the configuration.

Configure rate plans in Zuora

After the Tax app is installed and configured in Marketplace, perform the following tasks before using the configured tax instance:

  1. Set up the external tax engine
  2. Set up taxation codes
  3. Activate configurable tax rode in product rate plans

Set up the external tax engine

Perform the following steps to set up the external tax engine:

  1. In your Zuora tenant, navigate to Settings > Billing > Setup External Tax Engine.
  2. If no Connect tax engine is available on the list of tax engines, select Connect Tax Engine from the dropdown list and click setup new tax engine. If a Connect tax engine is available in the list, you cannot create a new Connect tax engine. You have to edit an existing Connect tax engine.
  3. Complete the Tax Engine configurations. 
    • Name - Name the tax engine you would like to use in Zuora.
    • Connect Token - Enter the unique 32-character API Token of the Tax app. To obtain your API Token, go the Sovos App link from the left-hand navigation menu and navigate to the App Information tab where the API token is listed near the top of the page. 
    • Company Information - You must add at least one Company Code in this section to activate a Tax Code.
  4. Set up custom fields that will be used in the request. see Manage custom fields for more information.
  5. Select all the custom fields you want to use in the tax request. Failure to select them will result in that blank values are used in the corresponding Liquid objects. Up to 50 custom fields are allowed.
  6. Click Save.

Note: If you modify any of the Tax Engine details after the initial configuration, the Zuora token must be entered again. 

Set up taxation codes

After setting up the external tax engine, perform the following steps to set up taxation codes:

  1. In your Zuora tenant, navigate to Settings > Billing > Setup Taxation Codes. 
  2. Select Add New Tax Code.
  3. Complete the Tax Code details.
    • Name - Name of the tax code to be selected in the product catalog when discerning which tax engine the charges will be calculated from.
    • 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 external tax engine.
    • Active - Select No.
    • (Optional) Description - Enter the description of the tax codes being used and the tax engine that will be sent for future reference.
  4. Click Save.
  5. Click Activate to ensure the tax codes are present in the product catalog.

Activate configurable tax code in product rate plans

After setting up taxation codes, perform the following steps to activate configurable tax code in product rate plans:

  1. In your Zuora tenant, click Product Catalog in the UI.
  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 app. See the following articles for more information:
  4. Hover over the title and click Edit to edit the rate plan. Note that only the rate plans in the One-Time Charges and Recurring Charges / Period columns can use the Tax app.
  5. Complete the details in the Taxation section of the selected rate plan:
    • Taxable - Select this check box to enable 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.
  6. Click Save.

Test the Sovos Tax Connector app

After the Sovos Tax Connector app is configured, perform the following steps to test the app:

  1. Configure Debug Logging.
    1. Log in to your Connect tenant, navigate to Marketplace > Sovos Connector in the left-hand column navigation menu.
    2. In the Testing tab, select the number of hours to capture logs in the dropdown list next to the Start Logging button.
    3. Click Start Logging.
  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 Creating 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. 
  7. If no tax is displayed on the invoice, perform the following steps to troubleshoot:
    1. Navigate back to the Sovos Tax Connector app.
    2. In the Testing tab, click the  icon to enable the columns to be displayed. It is good practice to enable the Exception and Status columns. Test Tax.png

      Each request should contain two lines: the request and the response. If no return payload is contained in the response, check the API transaction for the corresponding request. The error message might provide additional information.  

    3. If both the request and response are present, check the values in the Status column. 
      • If the value is Success, review the transaction response of the Tax instance and check for the error in the response. Use the error message as a guide in your tax template and resubmit the request after resolving the issue. 
      • If the value is Error, review the message in the Exception column. Common causes of the errors include the incorrect selection of your authentication type and invalid credentials. 

Alternatively, you can use the CURL requests to test your configurations.