1. Integration and Import/Export Guide
  2. External Imports and Exports
  3. Vertex Interface

Vertex Interface

Purpose: The Vertex Interface provides a bridge between Order Administration and the Vertex Sales Tax system to calculate the tax information on your orders at strategic points, such as:

  • order entry
  • order maintenance
  • pick slip preparation
  • billing

Order Administration communicates with Vertex files to determine the appropriate tax rate at each stage of the order's life cycle. Vertex determines the appropriate tax rate based on the “ship-from” and “ship-to” addresses on the order.

The Vertex Sales Tax system stores the tax rates for each taxing jurisdiction in the United States and Canada and provides the necessary reporting for each jurisdiction in which you sell or operate.

If you use the Vertex interface, you don't need to keep current with the tax rates and reporting requirements of each taxing jurisdiction, and you no longer must maintain these rates on Order Administration. Also, the system does not consider any item tax exemptions set up through Working with Item Tax Exemptions (WITX) or Working with GST Tax Exemption Status (MGTX). Instead, you should use Vertex to set up any tax exemptions for items.

Note:

You cannot use both Vertex and tax-inclusive pricing (VAT) in the same company. See Tax Included in Price (E70) for more information on VAT.

Compatibility:

  • Order Management System version 19.2 or later, or Order Administration, is compatible with Vertex Indirect Tax O Series® On Demand 9.0 but continues to support integration with 7.0 and 8.0 using 7.0 messages.
  • Order Management System version 15.1 or later, or Order Administration, is compatible with Vertex Indirect Tax O Series® On Demand 7.0 and 8.0. The 7.0 messages are used for both releases.
  • Support for Vertex Indirect Tax O Series® On Demand 7.0 and 8.0 using 7.0 messages ends in September 2021.

For more information: See:

  • Vertex Setup for information on setting up Order Administration to support communication with Vertex. Also, see your Vertex documentation for detailed information on setup requirements within Vertex.
  • Vertex Troubleshooting

In this topic:

Tax Calculation Processing Overview

Overview: The Vertex Interface passes order and tax information between Order Administration and Vertex at various points in the order cycle (from order entry to billing).

Vertex evaluates and calculates the tax amount on the order at each phase and updates transactions appropriately. The tax amount is provided with only 2 decimal places. Depending on the settings in the external app, they round up or not. For example, .1875 would round up to .19 and may make the amount different from the original order total.

Communication between Order Administration and Vertex: When Order Administration needs tax information during order entry or maintenance, pick slip preparation, or billing, it sends a tax request message to Vertex using web services. The TAX_INT integration layer job defines the wsdl (Web Services Definition Language) file that controls the integration.

For troubleshooting purposes, Order Administration writes the tax request message to the Trace Log, masking the vertex user ID and password passed in the request. Additional processing is logged to the Application Log.

For more information: See Vertex Setup for more information on configuring the integration.

What is taxed? Based on its current data on tax rules for the shipping address on the order and the additional rules that you define for customer or item exceptions, Vertex indicates the tax amounts for merchandise, freight (order-level or line-level), handling charges, duty, shipper-item charges, and additional freight.

Tax Overrides, Customer Exemptions, and Item or Class Exceptions

Tax override: You can set the Tax override flag in the Order Detail table to Y when you create an order through the generic order API. If this flag is set to Y, Vertex does not calculate the tax amount for the item at any point in the order cycle and just uses the specified tax override amount; however, if there are any line-level freight, handling, or gift wrap charges, these charges may be subject to tax even if the order detail line has a tax override.

Similarly, you can override tax on freight through the order API by specifying a freight_tax_amount and setting the freight_tax_override to Y.

Note:

  • There is no way to set the Tax override flag through interactive order entry.
  • The system does not set the Tax override flag in the Order Detail table unless there is a tax amount specified in the inbound order message. As a result, you cannot use this setting to create an order line with no tax amount in interactive order entry. The only way to exempt an order line from tax is to set up an item or product class exception in Vertex.

Send Tax to Tax Interface as Quote Not Invoice (L11)

Purpose: The system sends different request types to Vertex based on the setting of this system control value and whether the tax is overridden. Use Send Tax to Tax Interface as Quote Not Invoice (L11) system control value to indicate whether the BILL_ASYNC job should send a tax interface request with a request_type of QUOTATION or INVOICE.

Note:

Billing checks the setting of this system control value only if the Use Generic Tax XML Interface (J10) system control value is set to AVATAX or VERTEX.

Quotation vs. invoice: Until you bill a shipment or credit, the tax totals on the order might change; so, during order entry, order maintenance, and pick slip preparation, the system sends a QUOTATION request. Sending the INVOICE tax interface request indicates that the tax totals in the response message will be billed.

You might select this system control value if you use Vertex to calculate tax for orders from multiple channels and want all invoice request messages to flow to the tax system through a single channel for auditing purposes.

Leave this field unselected if you want to send an INVOICE tax interface request during billing, or if you do not use the generic tax interface.

Tax override? The system generates a DISTRIBUTETAX request rather than an INVOICE at billing if:

  • you create an order through the order API and the CWOrderIn message specifies a tax override

  • the Send Tax to Tax Interface as Quote Not Invoice (L11) system control value is unselected

In this situation, the system does not send a quote at order creation or pick slip generation for the tax override; however, if the system requires a tax calculation for any other items or charges on the order, it generates a QUOTE request at order creation and pick slip generation, and an INVOICE request at billing for these items or charges.

Request type summary: 

Tax calculated or overridden: Send Tax to Tax Interface as Quote Not Invoice (L11) setting: Send Tax to Tax Interface as Quote Not Invoice (L11) setting:
 

Selected:

Unselected:
calculated

QUOTE (order creation, pick slip generation, and billing)

QUOTE (order creation, pick slip generation)

INVOICE (billing)
overridden

QUOTE (order creation, pick slip generation, and billing)

 DISTRIBUTETAX (billing only)

Customer tax exemptions: If a customer is flagged as tax exempt in Order Administration and has a tax identification number, the merchandise and charges on the customer’s orders are not taxable. Order Administration passes the exemption number to Vertex. Although Order Administration does not pass the customer’s tax-exempt expiration date, order entry does not let you create an order flagged as tax-exempt if the customer’s expiration date has passed.

Item or item class exceptions: When you use Vertex, you need to set up item and product class exceptions in Vertex rather than in Order Administration. For example, if you have two item classes that are not normally taxable, you can map these item classes to product classes in Vertex. See Creating the Product Class under Vertex Setup for more information on mapping this information.

Note:

Even if an item on an order is not subject to tax, Vertex still calculates tax for any freight, handling charges, and gift wrap charges if the order is otherwise subject to tax.