Skip to main content

Vertex Advantage Tax Connector app v2


Vertex Advantage Tax Connector app v2


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

Version 2 (v2) of the Vertex Advantage Tax Connect app has significantly improved compared to its predecessor, the Vertex Advantage Tax Connector app (v1). It is strongly recommended to switch to v2 going forward, as v1 will no longer receive development and support.


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

Behavior Change


Handling of credit


Credits are treated as refunds. 


Credits are handled as negative amounts.

Use case details

Use Case





In the event of a failed posting document but a successful tax submission, an orphan tax transaction may be generated. The Vertex side must revert to this orphan transaction. For instance, when a payment failure causes an order transaction to fail.

Refund items are not manageable.

Capable of reversing all charges.


Multiple refunds for the same charge can happen if multiple removals or subscription cancellations occur before the removal date. Let’s consider a subscription that lasts 12 months and is billed annually. After ten months, the price changes, resulting in a two-month credit and a charge at the new price for the remaining two months. Canceling the subscription right away will result in the cancellation of the 2-month credit as well as the full 12-month credit.

Not suitable for addressing such scenarios.

Refunds can be processed by sending negative charges.

Cancel Charges with Discount

The Tax App initiates separate refund calls for each credit item, handled independently from the main tax transaction request sent to Taxamo.

In the current v1 integration, an extra refund call is needed to credit items for past transactions.

Integration and customization are made simpler, reducing complexity.

Switch Vendors

Transitioning from tax vendor A to Vertex Advantage Tax can be difficult when generating credit charges from past invoices. Nonetheless, Vertex Advantage Tax allows for processing credits as negative charges.

Previous transactions may not exist in Vertex Advantage Tax.

Capable of handling credits by processing them as negative charges.


Credit representation differs in the Vertex system, while the total reporting amount remains consistent.

Set up vertex advantage tax connector app v2

Follow these steps to streamline your tax compliance process:

  1. Configure Vertex Advantage Tax Connector in Zuora Billing:
    1. Navigate to Settings > Billing > Setup Tax Engine and Tax Date
    2. Choose Global Tax Hub from the dropdown and click Setup New Tax Engine.
    3. Name the engine, and select the Vertex Advantage Tax Connector app v2 from the dropdown list.
    4. Specify the environment for the engine usage. Reach out to Vertex for your token phase.
    5. Provide authentication details, including Engine Name, Vendor, Environment, and so on.
    6. Adjust Advanced Settings as needed.



      Engine Name

      Name of the engine to be used.


      Name of the third-party vendor.


      The designated environment for the tax engine application.

      Authentication Type

      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.

      Advanced Settings


      Tax Void Call Handling

      Option to specify the actions to be taken in case of void transactions with the external Vendor. Options include:

      • Pass-through: The vendor was not contacted, but the invoice cancellation was successful.
      • Enable: Vendor contacted through a call.
      • Block: The invoice cancellation post was blocked due to the failure to contact the vendor.

      Netread Timeout

      Duration in minutes before the timeout occurs.

      Request Headers

      Additional headers to tax requests are beneficial in scenarios requiring authentication through firewalls or other specific cases.

      Field Mappings

      Option to store and retrieve data from tax engine response onto Taxation Item object. Refer to Flexible Tax Mapping for more details.

      Custom Fields

      Choose from available custom fields for the tax engine.

      Company and Seller Information

      Add the company code, name, and address.

    7. Configure the template as required in the Request Template section. 
    8. Click Use Default Template to use the preconfigured 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.

      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.

    9. 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 '' \
      --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:
  3. Generate Invoice
    1. Create a bill run for the test account and generate an invoice. For more information, see Creating Bill Runs.

Current users of the Vertex Advantage Tax Connector app (v1) will experience significant enhancements and improvements when switching to the new Vertex Advantage Tax Connect app v2.