Vertex Advantage Tax app v2

Prerequisites

Before upgrading to Vertex Advantage Tax app v2, ensure the following prerequisites are met:

• Activate the Connect Tax Engine feature before transitioning to v2.

Overview

Refund items are treated differently in the current connector(v1) compared to the updated version(v2). Understand this by reviewing the specifics below.

Set up vertex advantage tax app v2

Follow these steps to streamline your tax compliance process:

1. Configure Vertex Advantage Tax in Zuora Billing:
   1. Navigate to Settings > Billing > Setup Tax Engine and Tax Date. 
   2. Click Setup New Tax Engine and select Vertex Advantage Tax V2 from the dropdown list.
   3. Toggle Use Test Environment if you want Billing to use the test service URL. This enables you to test tax calculations during your Billing setup.
   4. In the Basic Information area, enter the following:
      1. Engine Name - The name of the engine to be used.
      2. Authentication Type - The type of authentication required. To integrate with Vertex Advantage, use your tax vendor account credentials (Username and Password) for Private Token authentication. Access your dashboard and uncover the hidden private token to obtain API tokens.
   5. Enter the following in the Company and Seller Information section:
      1. Company Code - A unique identifier for the company in the AvaTax system, used to link billing information to the appropriate business entity. This field is critical for ensuring the correct company is referenced in tax calculations.
      2. Origin Address - The address where transactions originate from, which is essential for accurate tax calculation. The tax rate can vary depending on the origin location, as different jurisdictions may have different tax rules. This field helps ensure that the correct tax rates are applied based on where the transaction begins.
      3. Add Company - The option to add new company details.
   6. Toggle to enable Advanced Settings and adjust the settings.

      Field	Description
      Request Template	Configure the template as required. Click Use Default Template to use the pre-configured template.  Zuora uses the Request Template in Text/XML or Application/JSON format to populate invoice information according to your setup. Templates are rendered dynamically using the Liquid Template Language, available in Text/XML or Application/JSON format. Ensure the utilization of Context Object information while creating a tax template. Note: transaction_items is no longer supported as a context object for template rendering in V2; instead, the default document_items must be used. In V1, transaction_items were specifically tailored to exclude discount charges from being sent to Taxamo as negative transaction lines. In V2, however, we now manage discount and credit items as negative transaction lines by default, so transaction_items are no longer necessary.
      Custom Fields	Choose from the available custom fields from the tax engine.
      Response Field Mapping: 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.
      Network: Timeout Net Read Timeout	The timeout period for tax requests. The available options are 1 minute, 2 minutes, 5 minutes, and 10 minutes.
      Request Headers	Additional headers to tax requests are beneficial in scenarios requiring authentication through firewalls or other specific cases.

   7. Click Save.
2. Create and Activate Tax Code:
   1. To do this, follow the steps in Set Up Tax Codes - Zuora. 
3. Associate Product Rate Plan Charge with Tax Code
   1. To do this, follow the steps outlined in Avalara AvaTax for Communications App - Zuora.  
4. Generate Invoice
   1. Create a bill run for the test account and generate an invoice. For more information, see See Creating Bill Runs.
   2. Verify whether the tax amount is displayed correctly on the invoice.
5. View Tax Logs on System Health
   1. Navigate to the Tax Dashboard under System Health to review request and response logs from the newly configured tax engine.

Configure tax engine with settings API

The Settings API facilitates the configuration of tax engines, offering CRUD (Create, Read, Update, Delete) operations. You can use the provided API endpoints to manage tax engines, enabling actions such as creation, updating, retrieval, and deletion. For detailed information, refer to the documentation. 

1. Setup Tax Codes with API:
   1. After completing the configuration process, create a tax code with Settings API. For more information, see Set Up Tax Codes - Zuora.

      curl --location 'https://rest.sandbox.eu.zuora.com/settings/tax-codes/global-tax-hub' \
      --header 'Authorization: Bearer ec165dca4d3842848e8224944aa9a843' \
      --header 'Content-Type: application/json' \
      --data '{
          "taxEngineId": "8a90a9b785947dfb0185949dd1231a36",
          "active": true,
          "description": "",
          "name": "TaxCode Name",
          "taxCompanyId": "8a90a9b786544a6901865cec97ae6a6c"
      }'
      

2. Associate Product Rate Plan Charge with Tax Code (API):
   1. Associate a tax code with a product rate plan charge. For more information, refer to the following links:
      • CRUD: Create a product rate plan charge
      • CRUD: Update a product rate plan charge
      • CRUD: Retrieve a product rate plan charge
3. Generate Invoice
   1. Create a bill run for the test account and generate an invoice. For more information, see Creating Bill Runs.