Get started with Sovos Tax Connector app
To get started with Sovos Tax Connector app, go through the following procedure.
- Submit a request at Zuora Global Support to enable the Connect Tax Engines feature in your Zuora tenant.
- Install the Sovos Tax Connector app.
- Configure the Sovos Tax Connector app.
- Test the Sovos Tax Connector app.
Install the Sovos Tax Connector app
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:
- Configure templates
- Configure request settings
Configure templates
Configure engine settings
After configuring the template, perform the following steps to configure engine settings:
- Click the Engine Settings tab.
- Click the
icon for the tax engine that you want to configure. The tax engine details window is displayed.
- In the Headers tab, select the value for
Content-Type
in 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. - 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.
- Select an authentication type in the Authentication Type dropdown list. Consult your tax provider for further information regarding your specific authentication type and credentials.
- 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.
- 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:
- Set up the external tax engine
- Set up taxation codes
- 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:
- In your Zuora tenant, navigate to Settings > Billing > Setup External Tax Engine.
- 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.
- 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.
- Set up custom fields that will be used in the request. see Manage custom fields for more information.
- 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.
- 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
Activate configurable tax code in product rate plans
Test the Sovos Tax Connector app
After the Sovos Tax Connector app is configured, perform the following steps to test the app:
- Configure Debug Logging.
- Log in to your Connect tenant, navigate to Marketplace > Sovos Connector in the left-hand column navigation menu.
- In the Testing tab, select the number of hours to capture logs in the dropdown list next to the Start Logging button.
- Click Start Logging.
- Create a test product in your product catalog. See Create a Product in Product Catalog for more information on creating a product.
- Create a subscription on an account with only the test product. See Create Subscriptions for more information.
- Define billing rules. Navigate to Settings > Billing > Define Billing Rules > edit in your Zuora tenant.
- Create a bill run for the test account and generate an invoice. See Creating Bill Runs for more information.
- 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 no tax is displayed on the invoice, perform the following steps to troubleshoot:
- Navigate back to the Sovos Tax Connector app.
- 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.
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.
- 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.