Avalara AvaTax Interface

Purpose: The Avalara AvaTax Interface provides a bridge between Order Administration and the Avalara AvaTax system to calculate the tax information on your orders at strategic points:

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

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

The AvaTax 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 AvaTax interface, you don't need to keep current with the tax rates and reporting requirements of each taxing jurisdiction, and you no longer have to 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 AvaTax to set up any tax exemptions for items.

Note:

You cannot use both AvaTax and tax-inclusive pricing (VAT) in the same company; you must use separate companies for regular tax and VAT. See Tax Included in Price (E70) for more information on VAT.

Compatibility: Order Management System version 17.0 or later, or Order Administration, is compatible with Avalara AvaTax REST API v2.

For more information: See Avalara AvaTax Setup for information on setting up Order Administration to support communication with AvaTax. Also, see your AvaTax documentation for detailed information on setup requirements within AvaTax.

In this topic:

Tax Calculation Processing Overview

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

AvaTax 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 AvaTax: When Order Administration needs tax information during order entry or maintenance, pick slip preparation, or billing, it sends a tax request message to AvaTax 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. Additional processing is logged to the Application Log.

For more information: See Avalara AvaTax 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, AvaTax 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, AvaTax 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 exception in Working with Tax Product Code Cross References (WTPC).

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

Purpose: The system sends different request types to AvaTax 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 AvaTax 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-exempt Tax identification number, the merchandise and charges on the customer’s orders are not taxable. Order Administration passes the exemption tax identification number to AvaTax. 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 AvaTax, you need to set up item exceptions in Working with Tax Product Code Cross References (WTPC). For example, if you have two item classes that are not normally taxable, you can map these item classes to tax product codes in AvaTax.

Note:

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

Order Orchestration fulfilling orders: Invoice request messages are not sent to AvaTax for orders created to fulfill orders that originated in Order Administration, were submitted to Order Orchestration, and then submitted to Order Administration because Order Orchestration selected the Order Administration warehouse for fulfillment or sourcing. See Order Orchestration Integration for background.

AvaTax Processing

When Order Administration needs to calculate tax for an order and you are using the AvaTax interface, the system uses the AvaTax REST API v2 web service to communicate with the AvaTax system via HTTP POST.

  1. Order Administration generates a Tax Request Message (CWTaxRequest), maps the information in the Tax Request message to the AvaTax Request message, and sends the AvaTax Request message to AvaTax for tax calculation.

  2. AvaTax calculates the tax and sends an AvaTax Response message to Order Administration.
  3. Order Administration maps the information in the AvaTax Response message to the Tax Response Message (CWTaxResponse) and uses the information in the Tax Response message to apply tax to the order.

For more information see the Order Administration Web Services Guide on My Oracle Support (ID 2953017.1).

Tax Request Maps

Order Administration maps the generic tax messages (Tax Request Message (CWTaxRequest) and Tax Response Message (CWTaxResponse)) to the AvaTax message format to pass tax information to and from AvaTax.

For more information see the Order Administration Web Services Guide on My Oracle Support (ID 2953017.1).

Reviewing messages: You can review the messages passed between Order Administration and AvaTax in the Trace Log if its Logging Level is set to DEBUG or ALL. Use this log to help troubleshoot the AvaTax integration.

License key authentication: The AvaTax integration uses RESTful web services, passing the account and license defined in the AvaTax Values by Company Properties File to AvaTax.

For more information: See:

Tax Calculation Processing Overview for an overview of the AvaTax process.

Generic Tax API for more information on the generic tax API, including information on the Tax Request Message (CWTaxRequest) and Tax Response Message (CWTaxResponse).

For more information see the Order Administration Web Services Guide on My Oracle Support (ID 2953017.1).