Configuring Tax Calculation by Vertex

Note: The Vertex plugin package is delivered and installed automatically with the CloudBlue Commerce distribution.

Configuration

To set up automatic tax calculation using Vertex O Series or Vertex Cloud:

Step 1. Configure Taxes

Even though tax calculation will be performed on the Vertex side, you must configure the necessary taxes in CloudBlue Commerce so that they are displayed in PDF documents and notifications.

For Vertex O Series

For Vertex O Series, add the following tax configurations:

Mandatory: Configure a tax whose name will be used in invoice notifications and PDF documents to represent all reported taxes that do not have a mapping to a tax in CloudBlue Commerce. For convenience, this tax can be called, for example, Other Taxes or Aggregate Taxes.

Important: For better visualization and reconciliation, we strongly recommend that you configure tax mapping for all reported taxes (please see the Recommended configuration below). Without tax mapping, all taxes with the same tax rate will be aggregated in one record; all taxes with different tax rates will be represented by different records; however, all such records will have the same tax name.

Note: You will use this tax configuration to complete the mandatory Aggregate taxes in field when configuring the Vertex plug-in settings.
Recommended in addition: To display a tax breakdown in orders and AR documents, configure tax mapping between taxes reported by Vertex O Series and taxes you configured in CloudBlue Commerce. If you do not configure tax mapping, all reported taxes will be aggregated and displayed as one figure. For information about taxes reported by Vertex O Series, please refer to your service agreement with Vertex.

Important:
• Because tax calculations are made by Vertex, only the tax names and IDs from CloudBlue Commerce taxes are used. All tax calculation settings are ignored. To avoid confusion, set the tax rates to zero.
• A tax breakdown can be displayed only for the order total and AR document total. For order and AR document details, aggregated taxes are displayed in the UI and PDF.

For Vertex Cloud

For Vertex Cloud, add the following tax configurations:

Mandatory: Configure a tax whose name will be used to display the aggregate tax figure for all reported taxes. This tax name will be displayed in PDF documents and notifications. For convenience, this tax can be called in a general way, for example: Total Taxes or Aggregate Taxes.

Note: You will use this tax configuration to complete the mandatory Aggregate taxes in field when configuring the Vertex plug-in settings.

Step 2. Configure Connection to the Vertex Tax Service

To set up connection to the Vertex service:

Log in to Billing PCP. Go to System > Settings > Finance > Taxation. In the Advanced Settings section, click Vertex.
In the General tab, in the Connection Settings section, provide your registration data obtained from Vertex:
- Url : URL to the Vertex service.
- Protocol version:
  - 9.0 – Vertex O Series
- Trusted ID: An application token (also called an "access token"), provided by Vertex.
Note: You can switch between Vertex tax calculation engines by changing Url to the Vertex endpoint and Trusted ID.
To verify that the connection with Vertex is established, click test connection.

For more information, please see Initial Setup and Testing Connectivity.

Step 3. Configure Account Identification Settings

Specify customer and vendor codes that will be sent from CloudBlue Commerce to Vertex in taxation requests:

Go to System > Settings > Taxation > Vertex.
In the General tab, in the Account Identification section, complete these fields:
- Customer Code Source: Define the identifier for customers (and resellers acting as customers) in taxation requests sent to Vertex:
  - Account ID: the customer or reseller account ID.
  - Attribute: a custom value that you can configure using the Custom Attributes functionality. If this value is missing for an account involved in a taxation transaction, the system uses the Account ID.
- Company Code: Define the vendor identifier for taxation requests sent to Vertex. This option identifies the top-level legal entity for which taxability rules may be configured in the Vertex Central user interface. This value is used for the Company field in "QuotationRequest" and "InvoiceRequest" calls to Vertex.

Step 4. Configure Tax Aggregation and Request Type Settings

In the General tab, complete the Other Settings section:

Aggregate taxes in: Choose the tax configuration that will be used for tax aggregation:
- For Vertex O Series: The chosen configuration will be used to aggregate all taxes reported by Vertex except those for which you configure individual mapping to tax configurations in CloudBlue Commerce. If there is no mapping configured, all taxes will be aggregated.
  
  Note: Because tax calculations are made by Vertex, only the tax name and tax ID are used. All tax calculation settings are ignored. To avoid confusion, set the tax rate to zero. By contrast with EZTax, Vertex integration does not support tax levels.
- For Vertex Cloud: The chosen configuration will be used to aggregate all taxes reported by Vertex.
Send 'InvoiceRequest' on Invoice Calculation: You can configure whether taxation calls to Vertex executed on invoice calculation should be treated as "Final" transactions or "Preview" transactions. In preview mode, Billing will send "Quotation" request instead of the "Invoice" request when composing the invoice. The transaction will be considered as preliminary and not chargeable by Vertex.
Use Tax Registration ID in calculations: If enabled, the verified Tax Registration ID specified for a reseller or customer account will be used by Vertex for tax calculations.

Step 5. Configure Product Code Mapping

Create tax category mapping: associate Billing tax categories and order detail types with Vertex product class codes. The mapping is configured at System > Settings > Taxation > Vertex > Tax Categories Mapping tab.

Define the following fields:

In the Tax Category ID field, define the type of service.
In the Detail Type field, specify for the service which type of charging is subjected to taxation.
In the Product Class Code field, define the code of the service in Vertex which corresponds to the combination of tax category id and detail type in CloudBlue Commerce.

For more information, please refer to Product Code Mapping.

Step 6. Create a Taxation Rule with the Vertex Taxation Method

To create a taxation rule, go to System > Settings > Taxation and click Add:
- Select the Vertex as taxation method.
- Specify the tax zone and tax category.
Thus, you define that the taxes for specific products purchased by customers registered in certain locations will be calculated by Vertex.
Test the taxation rule you have created by clicking the respective button at System > Settings > Taxation > Test All Taxation Rules. The list of all withheld taxes for a test sales order is displayed in the Test Order Details section of the test result screen.

Note: If the daily billing process is unable to calculate taxes for an order with Vertex, it will not be created. All failed taxation requests are logged by the BSS component. To learn how to configure log levels and view logs of CloudBlue Commerce components, see the Logging Guide.

Step 7. Map Taxes Reported by Vertex O Series to Taxes in CloudBlue Commerce

For each tax reported by Vertex that must be displayed as a separate line in orders and AR documents, configure a mapping to a tax configured in CloudBlue Commerce:

Note: A tax breakdown can be displayed only for the order total and AR document total. For order and AR document details, aggregated taxes are displayed in the UI and PDF.

In the Vertex configuration profile at System > Settings > Taxation > Vertex , switch to the Tax Mapping tab.
Click New Tax Mapping. Complete the fields:
- Tax ID: Complete with the CloudBlue Commerce tax ID: click the magnifying glass and choose one of the configured taxes from the pop-up window.
- Vertex Tax ID: Complete with the corresponding tax ID from the Vertex system. For information, please refer to your Vertex specification.
  Note: For each tax, Vertex reports several different IDs. The value for Vertex Tax ID can be obtained from the impositionTypeID parameter reported by Vertex.
Save the mapping.