Configuring Commerce for Vertex Tax Calculations

To complete the Commerce configuration for Vertex tax calculations, you will need to enter a few values from Vertex Cloud. If you need help, see Vertex Field Mapping.

When enabled, the Vertex section of the Tax configuration page includes the following Vertex sections:

Connection Settings Vertex ID and API connections
Integration Settings Vertex tax integration configuration
Flexible Fields Configure these settings to identify taxability based on information in your store beyond the standard
Delivery Terms Configure the shipping terms for shipments.
Seller Details Configure seller information used for tax calculation
Logging Configure logging functions
Developer & Support Information Displays information for the connector and shipping method codes

Enable the Vertex connection

These steps outline the configurations required for a valid Vertex connection.

  1. On the Admin sidebar, go to Stores > Settings > Configuration.

  2. To define the scope of the configuration for a multisite or multistore installation, set the Store View chooser in the upper-left corner to the specific website or store view that is to be configured.

  3. In the left panel, expand Sales and choose Tax.

  4. Expand Expansion selector Vertex on the page to enable Vertex and configure initial settings.

    Vertex Connection Disabled

    • Set Vertex Tax Links to Enable.

      This setting allows you to configure the Vertex settings.

    • Verify the default values for the Calculation API URL and Address Validation API URL.

      These connect the integration with Vertex Cloud and must match the URL displayed in your Vertex Connectors page for the Commerce connector in the ERP Connector URL and Address Lookup URL fields. Clear the Use system value checkbox and change these values if needed.

    • Enter the Trusted ID from your Vertex Cloud account.

      To find your Vertex Trusted ID, log in to your Vertex Cloud account and go to Settings > View All Connectors.

  5. Expand Expansion selector the Integrations Settings section and activate the tax calculations:

    Vertex - Integration Settings

    • Set Vertex Tax Calculation to Enable.

    • To determine when tax is calculated for an invoice according to the workflow, set Commit To Tax Journal When to one of the following:

      Invoice Created The tax is calculated and sent to Vertex when the invoice generates.
      Order Status is Changed The invoice generates when orders enter the selected status. If this value is selected, set the Invoice when Order Status option to specify the status.
    • To set the Allowed Countries, select the countries and nations to apply Vertex taxes for destination addresses.

      If a shipping address is not available on the order, the billing address is used.

    • Set how you want to Summarize Tax By: Product and Shipping or Jurisdiction.

  6. Expand Expansion selector the Seller Details section and do the following:

    Vertex - Seller Details

    • Enter the Company Code from the heading of the Configure Company page of your Vertex Cloud account.

    • Enter the Location Code from the Registration Details section of your Vertex Cloud account.

      This is the specific jurisdiction where the company is registered to file tax returns. This value corresponds to the Location Code that is entered as a Registered Location.

    • If you want to specify a seller address separately from the shipping origin, set Use Shipping Origin as Source to No and complete the address fields.

      If you leave the default Yes setting, Vertex uses the address set in the Origin section of the Shipping Settings.

  7. Click Save Config.

    If the configuration settings are correct, the API Status field turns green and indicates the status is Valid. At this point, you can continue with the remaining Vertex configuration settings, or complete them later.

    You need to save the configuration again if you modify any of the Vertex tax class or calculation settings.

    Vertex API Status - Valid

When you are ready to continue, you can complete the following sections for additional configuration as needed. You should also make sure that you configure the tax classes.

Flexible Fields

If you need to identify taxability based on information in your store beyond the standard customer and and product taxability drivers defined by Vertex, configure the flexible fields to be used in your Vertex Tax Assist Rules.

Step 1: Create custom Flexible Field in Commerce

  1. Expand Expansion selector the Flexible Fields section.

    Flexible Fields

  2. Expand the area for the category you want to use to map a Commerce field.

    There are three available flexible field categories:

    Code Fields Use this category to define a fields using an alphanumeric string value with a maximum length of 40 characters. Strings that exceed the size limit are truncated. You can create a maximum of 25 flexible code fields.
    Numeric Fields Use this category to define fields using numeric values for data, such as durations and weights, including floating decimal points. You can create a maximum of 10 flexible numeric fields.
    Date Fields Use this category to define fields using dates in the format YYYY/MM/DD. You can create a maximum of five flexible date fields.
  3. For the Field ID you want to configure, click the Data Source option to display the list of Commerce fields and select the field to use as a flexible field in Vertex Cloud.

    You can enter a text string in the search field at the top of the list to filter the displayed items and help to find the field you want.

    Code - Field ID 1

  4. Click Save Config.

Step 2: Use the Flex Field in a Vertex Tax assist rule

Add a new tax assist rule or edit an existing rule for your Vertex Cloud account that uses the configured flex field for tax calculation.

For detailed information about adding tax assist rules in the Vertex Cloud, see Add a tax assist rule (requires a login to the Vertex Documentation Center).

Vertex Tax Assist Rule

In this example, Flex Code 1 is mapped to Product > Eco Collection and when this has a value of 1, the Physical Origin/Ship From address (215 S Gilbert St, Danville, IL 61832) is used instead of the Company Address configured in Vertex.

Vertex Tax Assist Rule

Delivery Terms

Set the delivery terms (shipping terms) that determines the vendor or customer jurisdiction where the title transfer of a supply takes place. You can set a global term and overrides per country. These options provide support to EU VAT.

  1. Expand Expansion selector the Delivery Terms section.

    Vertex Delivery Terms

  2. To change the default Global Delivery Term, select an option (SUP - Supplier Ships is the default).

  3. (Optional) Create a Delivery Term Override for each country you want a specific delivery term that differs from the global.

    Click Add and select a country and term.

  4. Click Save Config.


To track and review Vertex actions and taxes, enable the logging options. This exports the logs and saves the information to the var/vertexlog_Y-m-d.csv file (year-month-day). When opening and reviewing the CSV log files, make sure to use a spreadsheet application that supports long cell contents. Some applications, like Microsoft Excel, could cause issues with cut off data.

  1. Expand the Logging section.

  2. Set Vertex Request Logging to Enable to capture full logs.

  3. Set Log Rotation to Enable.

    Additional configuration fields appear for setting the rotation.

    • For Rotation Action, set to Delete or Export to File and Delete.

    • For Log Entry Lifetime (days), set how long the log should exist before the rotation action occurs.

      For example, if set to 7, on the 7th day the action completes on the schedule.

    • Set the Rotation Frequency to Daily, Weekly, or Monthly.

    • For Rotation Time, set the hours, minutes, and seconds in the day to complete the rotation action.

    Vertex Logging

  4. Click Save Config.

Developer & Support Information

This section provides connector version information and lists all shipping methods and rates that are currently mapped to product SKUs in Vertex Cloud.

Vertex - Developer & Support Information

Refresh the cache

After you save your configuration changes, refresh the cache.

  1. On the Admin sidebar, go to System > Tools > Cache Management.

  2. Select the checkbox of each invalid cache.

  3. Set Actions to Refresh and click Submit.

Test the Vertex configuration

After completing the configuration, your store is connected to Vertex Cloud. Visit the Vertex Cloud Help Center to review your settings in more detail, and to learn how to enter test transactions, generate returns, and run reports.

Vertex Cloud has excellent documentation with videos to help you come up to speed. When your testing is complete and you are ready, you can Go Live with the click of a button.

Vertex API automatically disabled

When the Vertex connector is enabled and the Display prices in Catalog is set to Including Tax, updating your product prices in the catalog to include tax could significantly degrade Commerces performance. In this situation, the Vertex connector will automatically disable and you will see an error message in the Vertex configuration settings. You must set this value to Excluding Tax to re-enable the Vertex connector.

Vertex API error

Vertex cache management

When clearing caches using Cache Management, Vertex has a cache option included. This option improves performance during the checkout process.