Avalara AvaTax Interface

Avalara AvaTax Interface

Purpose: The Avalara AvaTax Interface provides a bridge between Order Management System 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 Management System 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 Management System. 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 is compatible with Avalara AvaTax REST API v2.

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

In this chapter:

• Tax Calculation Processing Overview

- Tax Overrides, Customer Exemptions, and Item or Class Exceptions

• AvaTax Processing

• Tax Request Maps

- Tax Interface Request Message > AvaTax Request Message

- AvaTax Response > Tax Interface Response Message

• Sample Tax Messages

- CWTaxRequest: Sample Message

- AvaTax Request: Sample Message

- AvaTax Response: Sample Message

- CWTaxResponse: Sample Message

Tax Calculation Processing Overview

Overview: The AvaTax Interface passes order and tax information between Order Management System 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.

Communication between Order Management System and AvaTax: When Order Management System 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 Management System 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).

For more information: See the Send Tax to Tax Interface as Quote Not Invoice (L11) system control value for a discussion on how the system sends different request types to AvaTax based on the setting of this system control value and whether the tax is overridden.

Customer tax exemptions: If a customer is flagged as tax exempt in Order Management System and has a tax-exempt Tax identification number, the merchandise and charges on the customer’s orders are not taxable. Order Management System passes the exemption tax identification number to AvaTax. Although Order Management System 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 Broker fulfilling orders: Invoice request messages are not sent to AvaTax for orders created to fulfill orders that originated in Order Management System, were submitted to Oracle Retail Order Broker, and then submitted to Order Management System because Order Broker selected the Order Management System warehouse for fulfillment or sourcing. See Order Broker Integration for background.

AvaTax Processing

When Order Management System 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 Management System 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 Management System.

3. Order Management System 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.

Tax Request Maps

Order Management System 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.

Reviewing messages: You can review the messages passed between Order Management System 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 and supports basic HTTP authentication, 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).

Tax Interface Request Message > AvaTax Request Message

The tax request message is used to send order and tax information to AvaTax. AvaTax uses this information to calculate the tax to assign to the order.

Generated when? Order Management System generates the Tax Request Message (CWTaxRequest) when tax needs to be calculated on an order during order entry, order maintenance, pick slip preparation, and billing.

The system maps the information in the Tax Request message to the AvaTax Request message and sends the AvaTax Request message to AvaTax.

Information included:

CWTaxRequest Message		AvaTax	Comments
Source Field/Table	In Message	In Message	Comments
entity_999_child_company in AvaTax Values by Company Properties File (where 999 is the entity associated with the order) or default_company field in AvaTax Values by Company Properties File or Company in Order Ship To table	company	companyCode	The company code associated with the transaction. The system uses the following hierarchy to determine the company code: 1. Use the value defined in the entity_999_child_company field in the AvaTax Values by Company Properties File, where 999 is the entity associated with the order. 2. If the entity_999_child_company field is blank, use the value defined in the default_company field in the AvaTax Values by Company Properties File. 3. If the default_company field is blank, use the actual Order Management System company code.
N/A	source	customerCode	OROMS defaults.
customer_usage_type_CC in AvaTax Values by Company Properties File where CC is the Customer Class in Customer Sold To table	sold_to_cust_class	customerUsageType	Identifies the customer within a group and is used to mark a customer as fully or partially exempt. The AvaTax system provides pre-populated customer taxability profiles with rules for the United States and Canada. From the customer_usage_type_CC in the AvaTax Values by Company Properties File where CC is the sold to customer class.
Resale Exempt # in Order Ship To table (labeled the Tax identification)	resale_exemption_nbr	exemptionNo	The Tax identification number. Up to 30 positions, and can include numbers, letters, and special characters.
Company + Order # + Ship To # in Order Ship To table	company + order_nbr + order_shipto_nbr	code	The code assigned to the transaction, made up of company code + order number + ship to number. For example, if the company code is 76, the order number is 160, the ship to number is 1, the code is 07600000160001.
N/A	date_created + time_created	date	The date the transaction took place, in YYYY-MM-DDTHH:MM:SS format.
N/A	request_type	commit	true = The request_type in the Tax Request message is QUOTATION. false = The request_type in the Tax Request message is INVOICE or DISTRIBUTETAX.
N/A	request_type	type	Identifies the type of transaction. Valid values are: SalesOrder = Tax request for a sales transaction. From request_type in the Tax Request message when its value is QUOTATION. SalesInvoice = Tax request for a debit invoice transaction. ReturnOrder = Tax request for a return transaction. ReturnInvoice = Tax request for a credit invoice transaction.
		lines
Line # in Order Detail table	odt_line_nbr + odt_line_item_type	number	The transaction line number.
Item Class + LSD Class + LSD Department in the Item table + Long SKU Division in Long SKU Department table or line_handling_tax_code in AvaTax Values by Company Properties File or line_freight_tax_code in AvaTax Values by Company Properties File or line_duty_tax_code in AvaTax Values by Company Properties File or additional_freight_tax_code in AvaTax Values by Company Properties File or order_freight_tax_code in AvaTax Values by Company Properties File	odt_line_item_type	taxCode	The tax code defined for the transaction line. Line merchandise tax (LM): the system uses the item class + long SKU class + long SKU department + long SKU division combination to find a tax code in the Tax Product Code Cross Reference table (Working with Tax Product Code Cross References (WTPC)). Line handling tax (LH): from the line_handling_tax_code in the AvaTax Values by Company Properties File. Note: If the S/H exclude tax? flag is selected for an additional charge code, then a line that uses this additional charge code for special handling is not subject to order line handling (LH) tax. Line freight tax (LF): from the line_freight_tax_code in the AvaTax Values by Company Properties File. Line duty tax (LD): from the line_duty_tax_code in the AvaTax Values by Company Properties File. Additional freight and shipper item charges tax (AF): from the additional_freight_tax_code in the AvaTax Values by Company Properties File. Order freight tax (OF): from the order_freight_tax_code in the AvaTax Values by Company Properties File.
ODT qty ordered in Order Detail table	odt_qty	quantity	The quantity of the item on the order line. 1 defaults if the tax_code is OF (order freight), LH (line handling), LF (line freight), LD (line duty), or AF (additional freight and shipper item charges).
		taxOverride
ODT future use Y/N 1 in Order Detail table	odt_tax_override	type	Identifies the type of tax override. Valid values are: none accruedTaxAmount deriveTaxable exemption taxAmount = the odt_tax_override in the Tax Interface Request message is Y. taxDate = the odt_tax_override in the Tax Interface Request message is N or blank.
Tax in Order Detail table	odt_tax_override_amt	taxAmount	The tax override amount. This value is populated only if the odt_tax_override in the Tax Request is Y.
ODT arrival date in Order Detail table	odt_arrival_date or order_date	taxDate	The date to use for the tax override, in YYYY-MM-DDTHH:MM:SS format. If the tax_date in the AvaTax Values by Company Properties File is I (Invoice), the system uses the arrival date. For QUOTATIONS, the arrival date represents the order date and for INVOICE/DISTRIBUTETAX, the arrival date represents the invoice date. If the tax_date in the AvaTax Values by Company Properties File is O (Order), the system uses the order date. This value is populated only if the odt_tax_override in the Tax Request is N or blank.
ODT future use Y/N 1 in Order Detail table	odt_tax_override	reason	The reason for the tax override. taxOverride defaults if the odt_tax_override in the Tax Request is Y. taxDate defaults if the odt_tax_override in the Tax Request is N or blank.
ITM number in Order Detail table	odt_item	description	A description of the item.
N/A	odt_line_item_type	ref1	Identifies the type of tax. Valid values are: LM = Line merchandise. LH = Line handling. LF = Line freight. LD = Line duty. AF = Additional freight and shipper item charges. OF = Order freight.
N/A	odt_extended_price	amount	The amount of tax.
		ref2
ITM number + SKU code in Order Detail table	odt_item + odt_SKU or odt_line_item_type	itemCode	If the odt_line_item_type is LM, this is the item number and SKU code of the item on the line. If the odt_line_item_type is a value other than LM, this is the line item type code.
Description in Item table	odt_item_desc	description	A description of the item.
		addresses
CustomerShipTo		shipTo
Order ship to: NAM city in Order Ship To Address table Permanent ship to: NAM city in Customer Ship To table Recipient sold to: NAM city in Customer Sold To table	ship_to_city	city	The city of the ship to address on the order.
Order ship to: RPR country in Order Ship To Address table Permanent ship to: RPR country in Customer Ship To table Recipient sold to: RPR country in Customer Sold To table	ship_to_country	country	The country of the ship to address on the order.
Order ship to: NAM street address in Order Ship To Address table Permanent ship to: NAM street address in Customer Ship To table Recipient sold to: NAM street address in Customer Sold To table	ship_to_addr1	line1	The street address of the ship to address on the order.
Order ship to: NAM address line 2 in Order Ship To Address table Permanent ship to: NAM address line 2 in Customer Ship To table Recipient sold to: NAM address line 2 in Customer Sold To table	ship_to_addr2	line2	The second address line of the ship to address on the order.
Order ship to: Address line 3 in Order Ship To Address table Permanent ship to: Address line 3 in Customer Ship To Extended table Recipient sold to: Address line 3 in Customer Sold To Extended table	ship_to_addr3	line3	The third address line of the ship to address on the order.
Order ship to: NAM zip in Order Ship To Address table Permanent ship to: NAM zip in Customer Ship To table Recipient sold to: NAM zip in Customer Sold To table	ship_to_postal	postalCode	The postal code of the ship to address on the order.
Order ship to: NAM state in Order Ship To Address table Permanent ship to: NAM state in Customer Ship To table Recipient sold to: NAM state in Customer Sold To table	ship_to_state	region	The state or province code of the ship to address on the order.
ShipFromWarehouse		shipFrom
Warehouse: City in Warehouse table Sold to: NAM city in Customer Sold To table or default_warehouse_city in AvaTax Values by Company Properties File	ship_from_city	city	The city of the sold to address on the order. If the ship_from_warehouse in the Tax Request message contains a value, from the ship_from_city in the Tax Request message; otherwise, if the ship_from_warehouse is 0 or blank, from the default_warehouse_city in the AvaTax Values by Company Properties File.
Warehouse: RPR country in Warehouse table Sold to: RPR country in Customer Sold To table or default_warehouse_country in AvaTax Values by Company Properties File	ship_from_country	country	The country of the sold to address on the order. If the ship_from_warehouse in the Tax Request message contains a value, from the ship_from_country in the Tax Request message; otherwise, if the ship_from_warehouse is 0 or blank, from the default_warehouse_country in the AvaTax Values by Company Properties File.
Warehouse: Address in Warehouse table Sold to: NAM street address in Customer Sold To table or default_warehouse_line1 in AvaTax Values by Company Properties File	ship_from_addr1	line1	The street address of the sold to address on the order. If the ship_from_warehouse in the Tax Request message contains a value, from the ship_from_addr1 in the Tax Request message; otherwise, if the ship_from_warehouse is 0 or blank, from the default_warehouse_line1 in the AvaTax Values by Company Properties File.
Warehouse: Address line 2 in Warehouse table Sold to: NAM address line 2 in Customer Sold To table or default_warehouse_line2 in AvaTax Values by Company Properties File	ship_from_addr2	line2	The second address line of the sold to address on the order. If the ship_from_warehouse in the Tax Request message contains a value, from the ship_from_addr2 in the Tax Request message; otherwise, if the ship_from_warehouse is 0 or blank, from the default_warehouse_line2 in the AvaTax Values by Company Properties File.
Warehouse: Address line 3 in Warehouse table Sold to: NAM address line 3 in Customer Sold To table or default_warehouse_line3 in AvaTax Values by Company Properties File	ship_from_addr3	line3	The third address line of the sold to address on the order. If the ship_from_warehouse in the Tax Request message contains a value, from the ship_from_addr3 in the Tax Request message; otherwise, if the ship_from_warehouse is 0 or blank, from the default_warehouse_line3 in the AvaTax Values by Company Properties File.
Warehouse: Zip Code in Warehouse table Sold to: NAM zip in Customer Sold To table or default_warehouse_postalcode in AvaTax Values by Company Properties File	ship_from_postal	postalCode	The postal code of the sold to address on the order. If the ship_from_warehouse in the Tax Request message contains a value, from the ship_from_postal in the Tax Request message; otherwise, if the ship_from_warehouse is 0 or blank, from the default_warehouse_postalcode in the AvaTax Values by Company Properties File.
Warehouse: State in Warehouse table Sold to: NAM state in Customer Sold To table or default_warehouse_state in AvaTax Values by Company Properties File	ship_from_state	region	The state or province code of the sold to address on the order. If the ship_from_warehouse in the Tax Request message contains a value, from the ship_from_state in the Tax Request message; otherwise, if the ship_from_warehouse is 0 or blank, from the default_warehouse_state in the AvaTax Values by Company Properties File.
		pointOfOrderAcceptance
call_center_city in AvaTax Values by Company Properties File	N/A	city	The city of the call center address. From the call_center_city in the AvaTax Values by Company Properties File.
call_center_country in AvaTax Values by Company Properties File	N/A	country	The country of the call center address. From the call_center_country in the AvaTax Values by Company Properties File.
call_center_line1 in AvaTax Values by Company Properties File	N/A	line1	The street address of the call center address. From the call_center_line1 in the AvaTax Values by Company Properties File.
call_center_line2 in AvaTax Values by Company Properties File	N/A	line2	The second address line of the call center address. From the call_center_line2 in the AvaTax Values by Company Properties File.
call_center_line3 in AvaTax Values by Company Properties File	N/A	line3	The third address line of the call center address. From the call_center_line3 in the AvaTax Values by Company Properties File.
call_center_postalcode in AvaTax Values by Company Properties File	N/A	postalCode	The postal code of the call center address. From the call_center_postalcode in the AvaTax Values by Company Properties File.
call_center_state in AvaTax Values by Company Properties File	N/A	region	The state or province code of the call center address. From the call_center_state in the AvaTax Values by Company Properties File.

AvaTax Response > Tax Interface Response Message

The tax response message is used to send tax information to Order Management System. Order Management System uses this information to apply tax to an order.

Generated when? AvaTax generates a tax response message when it receives an Tax Interface Request Message > AvaTax Request Message from Order Management System.

The system maps the information in the AvaTax Response message to the Tax Interface Response message.

Information included:

AvaTax	CWTaxResponse Message		Comments
In Message	In Message	Target Field/Table	Comments
	Message
date	date_created	N/A	The date when the response was generated in Day Mon DD HH:MM:TT YYYY format; for example: Thu Sep 14 00:00:00 PDT 2017.
N/A	type	N/A	CWTaxResponse defaults.
N/A	target	N/A	OROMS defaults.
N/A	source	N/A	Avalara defaults.
	TaxInterfaceResponse
type	tax_type	N/A	The type of transaction. Valid values are: • SalesOrder • SalesInvoice • ReturnOrder • ReturnInvoice
N/A	order_shipto_nbr	Ship To # in Order Ship To table	From the order_shipto_nbr in the corresponding Tax Request Message (CWTaxRequest).
N/A	order_nbr	Order # in Order Ship To table	From the order_nbr in the corresponding Tax Request Message (CWTaxRequest).
N/A	entity	Entity Number in Division table	From the entity in the corresponding Tax Request Message (CWTaxRequest).
N/A	company	Company in Order Ship To table	From the company in the corresponding Tax Request Message (CWTaxRequest).
type	request_type	N/A	Valid values are: QUOTATION = tax requested during order creation and pick slip generation. This value defaults if the AvaTax status is Temporary and the type is SalesOrder or ReturnOrder. INVOICE = tax requested during billing. This value defaults if the AvaTax status is Committed and the type is SalesInvoice or ReturnInvoice.
	OrderDetail
rate	odt_total_tax_rate	N/A
totalTax	odt_total_tax_amt	Tax in Order Detail table
itemCode	odt_line_item_type	N/A
lineNumber	odt_line_nbr	Line # in Order Detail table
	JurisdictionLevel
rate	jurisdiction_level_tax_rate	N/A
tax	jurisdiction_level_tax_amt	N/A
jurisType	jurisdiction_level_desc	N/A
jurisType	jurisdiction_level	N/A	Valid values are: • Country • Composite • State • Country • City • Special

Sample Tax Messages

• CWTaxRequest: Sample Message

• AvaTax Request: Sample Message

• AvaTax Response: Sample Message

• CWTaxResponse: Sample Message

CWTaxRequest: Sample Message

A sample of the Tax Request Message (CWTaxRequest) is presented below.

</OrderDetail>

</OrderDetails>

</TaxInterfaceRequest>

</Message>

AvaTax Request: Sample Message

A sample of the AvaTax Request message is presented below.

{

"companyCode" : "RGBU",

"customerCode" : "OROMS",

"code" : "07600000270001",

"date" : "2017-09-14T05:56:38",

"type" : "SalesOrder",

"lines" : [ {

"number" : "1",

"taxCode" : "P0000000",

"quantity" : 1,

"taxOverride" : {

"type" : "TaxDate",

"taxAmount" : 0,

"taxDate" : "2017-09-14T00:00:00",

"reason" : "TaxDate"

"description" : "OF",

"ref1" : "OF",

"amount" : 5,

"ref2" : "00001",

"itemCode" : "OF"

} ],

"addresses" : {

"shipTo" : {

"city" : "WESTBORO",

"country" : "US",

"line1" : "1800 WEST PARK DRIVE",

"postalCode" : "01581",

"region" : "MA"

"shipFrom" : {

"city" : "FRAMINGHAM",

"country" : "US",

"line1" : "100 MAIN STREET",

"postalCode" : "01701",

"region" : "MA"

"pointOfOrderAcceptance" : {

"city" : "Fort Myers",

"country" : "US",

"line1" : "24 Metro Parkway",

"postalCode" : "33907",

"region" : "FL",

"line2" : "",

"line3" : ""

}

AvaTax Response: Sample Message

A sample of the AvaTax Response message is presented below.

{

"messages" : [ {

"refersTo" : "Addresses[0] - TaxDate: 2017-09-14 00:00:00Z",

"source" : "Avalara.AvaTax.Services.Tax.Steps",

"details" : "\n Address: 100 MAIN STREET, FRAMINGHAM, MA 01701 US, TaxRegion:1053, Latitude: 42.316847°, Longitude: -71.423129° \n AddressCode: ORIG2\n AddressType: \n BoundaryId: 1053\n CarrierRoute: \n County: MIDDLESEX\n FipsCode: 2501724960\n GeocodeType: ZIP5Centroid\n PostNet: \n Reason: JAAS enabled for MA\n ValidateStatus: HouseNotOnStreet\n TaxRegionId: 1053\n",

"severity" : "Success",

"summary" : "Using JAAS"

}, {

"refersTo" : "Addresses[1] - TaxDate: 2017-09-14 00:00:00Z",

"source" : "Avalara.AvaTax.Services.Tax.Steps",

"details" : "\n Address: 1800 W Park Dr, Westborough, MA 01581-3926 US, TaxRegion:1053, Latitude: 42.282624°, Longitude: -71.569295° \n AddressCode: DEST3\n AddressType: H\n BoundaryId: 1053\n CarrierRoute: C006\n County: WORCESTER\n FipsCode: 2502700000\n GeocodeType: StreetLevel\n PostNet: 015813926997\n Reason: JAAS enabled for MA\n ValidateStatus: NormalHit\n TaxRegionId: 1053\n",

"severity" : "Success",

"summary" : "Using JAAS"

}, {

"refersTo" : "Addresses[2] - TaxDate: 2017-09-14 00:00:00Z",

"source" : "Avalara.AvaTax.Services.Tax.Steps",

"details" : "\n Address: 24 Metro Parkway, Fort Myers, FL 33907 US\n AddressCode: POA4\n Reason: JAAS enabled for FL\n ValidateStatus: NotValidated (non-source address)\n",

"severity" : "Success",

"summary" : "Using JAAS"

}, {

"refersTo" : "Addresses[0]",