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.

In addition, Vertex supports Retail Delivery Fees (RDF). RDFs are flat taxes applicable to deliveries to a location in the respective states. See Retail Delivery Fees for additional information.

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 Administration version 25.1.101.0 or later, is compatible with Vertex Indirect Tax O Series® On Demand 9.0 using 9.0 messages. 

For more information: See:

In this topic:

External Tax Response Data

Order Administration will persist the tax response details returned from the Vertex external tax service. Given the large amount of data returned, Order Administration stores the entire response received from Vertex within a blob, rather than parsing out individual fields.  

  • The tax response data will be stored new ORDER_SHIP_TO_TAX_RESPONSE and INVOICE_SHIP_TO_TAX_RESPONSE tables.

  • The tax response data will be included in CWOrderOut, CWInvoiceOut and CWEmailOut. This will allow retailers to consume all of the information and determine what tax jurisdiction details they want to include in customer facing communications/documents.

Order Ship To Tax Response

This table is leveraged to capture and store the tax data (jurisdiction details) returned in the quotation response messages for requests that included the ‘complete’ order ship to.  Entries in this table will have a process of either Order Entry or Order Maintenance. A single quotation response entry including the most recent blob data for the 'complete' order ship-to will be stored.

When multiple quotation requests are triggered during Order Entry (due to selecting the 'Refresh Order' one or more times or if using the Order In API 2 pass method), the quotation response entry will be updated, replacing the existing blob data with the latest blob data. The 'Updated Date/Time' will be updated to the current system date/time each time the blob data is replaced for a tax entry.

When an order is edited, that triggers a complete order ship to tax request (not to create a return or return authorization), when it is unlocked, a new quotation request will be initiated that includes all order charges (except canceled/soldout lines).  The quotation response entry for that order ship-to will be updated, replacing the prior blob data.

When a quotation request is initiated by pick generation, broker processing or drop ship processing, the request could potentially be a partial snapshot of the order. Quotation requests initiated by these processes will NOT update the entry, replacing the existing blob for the order ship to since it may not reflect the 'complete' order ship to. 

The data from this table will be included in the CWOrderOut and the CWEmailOut outbound XML messages.

Invoice Ship To Tax Response table

This table is leveraged to capture and store the tax data (jurisdiction details) returned in the tax response messages, triggered from billing. Response types that can be found in this table include, Invoice Response messages, DistributeTax Response messages and when Send Tax to Tax Interface as Quote not Invoice (L11) system control value is selected, Quotation Response messages.

This table structure supports multiple tax entries for a single invoice, which would be possible when Consolidated Invoice (B49) system control value is selected. When Consolidated invoicing is enabled, there may be multiple tax response entries with different blob data for a single invoice, since the invoice will be appended with each shipment that occurs in the same day. Subsequent shipments will trigger a tax request limited to the charges associated with that shipment (not the full invoice). The subsequent tax response blobs will be stored as individual entries associated with the same invoice.

The data from this table will be included in the CWInvoiceOut and the CWEmailOut outbound XML messages.

Note:

When an order is submitted via the Order In API with Tax override values, Order Administration will not trigger quotation requests; therefore, no quotation response data blobs will be stored at the Order Ship To level. When the tax override order is billed, the corresponding distribute tax response blob data will be stored at the Invoice level.

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.

Retail Delivery Fees

The Vertex Integration supports Retail Delivery Fees (RDF) that have been implemented for Colorado and Minnesota. RDFs are flat taxes applicable to deliveries to a location in the respective states. It does not apply to items that are picked up at a retailer location, therefore Ship for Pickup and Pickup orders will not assess the flat tax. Proper assessment of the RDF flat tax requires coordination and configuration within Order Administration and Vertex applications.

Note:

Retail Delivery Fee eligibility from Order Administration is limited to orders that are being delivered to the end customer where Order Administration is responsible for billing the end customer. This includes direct delivery from a Warehouse or Store. Retail Delivery Fees do not apply to orders that Order Administration is fulfilling from Order as the originating system should assess and bill the RDFs.

Colorado

Colorado’s RDF legislative requirement is to charge a one-time predefined RDF flat tax for all orders shipping to Colorado regardless of shipping charges or number of shipments. Vertex automatically assesses the fee based on the 'OF' record which Order Administration includes for shipping charges in the request message. 

Since Vertex automatically assesses the RDFs for all orders with a Colorado ship to destination, Order Administration must include an RDF exemption indicator in the tax request message whenever a transaction should not assess the RDF flat tax. (In a multi-ship to order, each Ship To will be submitted in a separate tax request which includes all charges for the individual order Ship To). A Flexible Code Field with a hardcoded value of RDFEXEMPT is included in quotation, invoice and distribute tax requests when:

  • the OST_OBR_DELIVERY_TYPE field of the Order Ship To table in populated.

  • a subsequent invoice for split shipments occurs as the flat tax would have already been assessed on the initial invoice.

When a CWOrderIn request includes order line tax overrides but does not include a freight override tax value, or includes a freight override tax value that is less than the RDF Flat Tax Value (currently 0.29 for CO), Vertex will return an error response when the DistributeTax Request is received and the tax request will not be recorded for that transaction/invoice. 

See RDF Setup in Order Administration for more information on Flexible Code Field configuration.

Note:

Order Administration supports the RDF flat tax for Colorado irrespective of the ship to location. Vertex will ignore the RDF exemption indicator when it is not mapped to a taxability category applicable for the ship to location. Refer to RDF Setup in Vertex for setup information.

Reference the following link to learn more about the Colorado Retail Delivery Fee: https://tax.colorado.gov/retail-delivery-fee 

Minnesota

Minnesota’s RDF legislative requirement is to charge a one-time predefined RDF flat tax for all orders shipping to Minnesota regardless of shipping charges or number of shipments, only IF the retailer meets the criteria to pay the flat tax and IF the order meets specific eligibility requirements based on the merchandise items and their dollar value. The order must total $100 or more of qualifying merchandise + shipping for the fee to be assessed. 

Note:

Not all merchandise qualifies toward the order threshold value of $100. Certain items are excluded when calculating the threshold, such as drugs, medical devices/accessories/supplies, food, food ingredients, prepared food, certain baby products, electronics deliveries (such as computer software), utilities delivered thru pipes or wires (natural gas, electricity, etc.) and items purchased for the purpose of resale. 

Vertex requires that Order Administration include an RDF flat tax indicator in the tax request message whenever a transaction should assess the RDF flat tax for Minnesota. (In a multi-ship to order, each Ship To will be submitted in a separate tax request which includes all charges for the individual order Ship To). When configured in Order Administration, a Flexible Code Field with a hardcoded value of ‘DFP’ will be included in all quotation requests for delivery orders.

When Vertex reviews the quotation request that includes the Flexible Code Field with a value of ‘DFP’ it will evaluate the order, and if it qualifies, the flat tax will be returned in the quotation response. Order Administration evaluates the quotation response data and when an RDF flat tax is present, the Order Ship To table is updated identifying that RDF was assessed. At billing, Order Administration checks the Order Ship To and includes a Flexible Code Field with a hardcoded value of ‘RDFTAX’ with the first invoice request. The Flexible Code Field value of ‘RDFTAX’ does not evaluate if the transaction qualifies, instead it automatically adds the RDF fee to the tax response to account for a split shipment scenario where the order threshold is not met within the first invoice.

See RDF Setup in Order Administration for more information on Flexible Code Field configuration.

To identify when the RDF fee was included within a freight tax override value, the rdf_flat_tax attribute will be used in the ShipTo element of the CWOrderIn 14.0 message. This field should be used in conjunction with a freight tax override to indicate whether the Retail Delivery Fee has been included within the freight tax amount. 

  • When a CWOrderIn request has the RDF Flat Tax field set to Y but does not include a freight override tax value, or includes a freight override tax value that is less than the RDF Flat Tax Value (currently 0.50 for MN), Vertex will return an error response when the DistributeTax Request is received and the tax request will not be recorded for that transaction/invoice.

Note:

This field is currently only applicable for freight tax override Ship To destinations where Vertex does not automatically assess the Retail Delivery Fee. For example, setting this value to N or Blank will not prevent the Colorado RDF from being assessed since there are no qualifying conditions to exclude it for a delivery order. 

  • Set to Y to indicate a tax override is on the order and the RDF flat tax amount has been included within the freight tax amount.

    • The Order Ship To record will track that RDF was assessed.

    • At billing the distribute tax request will include the RDF tax indicator with the first invoice request. In this scenario, Vertex will include the RDF flat tax when dividing the freight tax override amount across all applicable jurisdictions. 

    • For Example, if the freight tax override amount was 5.00, Vertex will allocate 0.50 to the RDF flat Tax fee first and then divide the remaining 4.50 across the applicable jurisdictions.

  • Set to N (blank or not included) to indicate the RDF Flat Tax is NOT included within the freight tax override amount.

    • At billing the distribute tax request will not include the RDF tax indicator with the first invoice request and Vertex will NOT include the RDF flat tax when dividing the freight tax override amount across all applicable jurisdictions. 

    • For Example, if the freight tax override amount was 5.00, Vertex will divide the full 5.00 across the applicable jurisdictions.     

Note:

Order Administration supports the RDF flat tax for Minnesota irrespective of the ship to location. Vertex will ignore the RDF tax indicators when they are not mapped to a taxability category applicable for the ship to location. Refer to RDF Setup in Vertex for setup information.

Reference the following link to learn more about the Minnesota Retail Delivery Fee: https://www.revenue.state.mn.us/retail-delivery-fee

Vertex Troubleshooting

Purpose: Troubleshooting information includes:

Error in order entry: The message Error calling Tax Interface, check configuration in order entry indicates that one or more of the required files were not found. See Configuration Files for more information.

Processing Errors

Troubleshooting for the integration between Order Administration and Vertex begins with checking the TRACE.log and CWDirect.log files.

  • The TRACE.log file is typically located under /domain/conf/OMSFiles/Logs/TRACE/ on your application server, where domain is the WebLogic domain directory for Order Administration.
  • The CWDirect.log file is typically located under /domain/log/CWDirect.log on your application server, where domain is the WebLogic domain directory for Order Administration.

Note:

In addition to the errors written to log files, you will also see an error message in order entry if the extended order line price is over a million: Error occured on CALL to program Cwwebservice. Vertex does not support tax calculation for order line values that high.
Error in TRACE.log File Explanation How to Correct:

Initial Configuration Issues

    

ERROR TRACE - Class not found:

ERROR TRACE - TAX_INT web service error: - null

A required class was not installed during the initial installation process.

Contact your Order Administration representative.

ERROR TRACE - AxisFault exception in invoke method of com.cwi.direct.interfaces.webservice.VertexWS: exception on AXIS invoke: User login failed: invalid_user.

; nested exception is:

User login failed: invalid_user.

Possible causes:

Check the contents of the Vertex User ID and Password and confirm that the user ID and password exist in Vertex and have authority to the correct partition in Vertex. See Set up Data within Vertex Vertex Setup and your Vertex documentation for more information.

After you change the user ID and password in the Vertex User ID and Password, you need to stop and restart Order Administration. See Restarting Order Administration for more information.

ERROR TRACE - AxisFault exception in invoke method of com.cwi.direct.interfaces.webservice.VertexWS: exception on AXIS invoke: SAX processing failed on input stream

SAX processing failed when attempting to create new element. (parent element=com.vertexinc.tps.xml.calc.parsegenerate.builder.ParticipantData, new element=null, local element name=PhysicalOrigin

No physical origin is being passed. The physical origin is the address of the warehouse for the order detail line. Possible causes:

AxisFault exception in invoke method of com.cwi.direct.interfaces.webservice.VertexWS: exception on AXIS invoke: SAX processing failed on input stream

Non-fatal error detected during SAX parsing. Verify document against schema or contact document supplier. (URI=null, line number=30, error=cvc-datatype-valid.1.2.1: '' is not a valid value for 'integer'.)

The Default Warehouse (A04) is not listed in the Warehouses XML File .

Warehouses XML File: Confirm that the Default Warehouse (A04) is included in this file.

Tax Calculation Failing After Initial Setup

    

ERROR TRACE - AxisFault exception in invoke method of com.cwi.direct.interfaces.webservice.VertexWS: exception on AXIS invoke: ; nested exception is:

java.net.ConnectException: Connection refused: connect; nested exception is:

java.net.ConnectException: Connection refused: connect

Order Administration can no longer reach Vertex.

Contact your Order Administration representative.

ERROR TRACE - AxisFault exception in invoke method of com.cwi.direct.interfaces.webservice.VertexWS: exception on AXIS invoke: An error occured during CalcEngine.calculateTax. This may be an incorrect use of the calculation engine. Please contact your software vendor.

Error trying to calculate tax.

Cannot find tax areas. Please verify that the address or tax area id provided for the location is correct and retry.

The postal code passed in the tax request message from Order Administration is incorrect, or is associated with a city that does not exist in Vertex. To confirm, log onto Vertex and advance to the Tax Area Lookup Tool, then search for the shipping address that is causing the error. A message such as the following indicates that the postal code is incorrect:

No tax areas were found during the lookup. The address fields are inconsistent for the specified asOfDate. (Street Information=24 PRIME PKWY, Postal Code=01701, City=NATICK, Sub Division=null, Main Division=MA, Country=USA, As Of Date=20060627)

Correct the postal code information in Order Administration.

ERROR TRACE - AxisFault exception in invoke method of com.cwi.direct.interfaces.webservice.VertexWS: exception on AXIS invoke: ; nested exception is:

java.net.SocketException: No buffer space available (maximum connections reached?): connect

The Order Administration server is out of memory.

Reboot the Order Administration server.

ERROR TRACE - AxisFault exception in invoke method of com.cwi.direct.interfaces.webservice.VertexWS: exception on AXIS invoke: (404)Not Found; nested exception is:

(404)Not Found

The URL specified for Vertex in the Vertex URL property is incorrect.

  1. Correct the URL in the Vertex URL property.

  2. Stop and restart Order Administration.

See Restarting Order Administration for more information.

Miscellaneous Log Messages

    

WARN TRACE - WARNING: Responses for DISTRIBUTE not found in configuration xml.

The log includes this message when Order Administration requests tax information for an order that includes a tax override.

No need to correct; message is informational only.

TRACE - message: com.sun.xml.ws.fault.ServerSOAPFaultException: Client received SOAP Fault from server: An unit based tax rule cannot be applied to a line item with a quantitiy of zero. Please ensure that the quantity is not zero and retry. Please see the server log to find more detail regarding exact cause of the failure.

Certain states, such as Tennessee, require a quantity for tax calculation, and this error occurs when the quotation request includes a zero quantity for freight or additional freight charges.

Add a new rule in Vertex to change the quantity to 1 for the related product classes.

Tax Calculation Rules

Situation Explanation

New settings in Vertex apply when you use the Vertex Transaction Tester, but not when Order Administration requests tax information

If you have Vertex configured to cache information for improved performance, it might be retrieving tax rules from cached information when Order Administration requests tax information. Caching does not apply when you use the Transaction Tester. Consult your Vertex documentation for more information on configuring caching.

An item on an order is not taxable based on its item or product class settings in Vertex, or on the Tax override flag for the order line; but there is still tax on the order

Even if an item on an order is not taxable, freight, handling, gift wrap, additional freight, and duty can still be subject to tax.

You receive an order that includes an item with a tax override through the generic order interface, but the order line is still taxed

Even if the tax_override flag is set to Y in the inbound order message, Order Administration does not apply a tax override unless the inbound order message also specifies a tax amount greater than zero for the order line.

You change the user ID and password in the Vertex User ID and Password, but the changes do not take effect

Before your changes take effect, you need to restart Order Administration. See Restarting Order Administration for more information.