Generic Tax API

Generic Tax API

Purpose: Use the generic tax API to calculate tax using an external tax interface. The TAX_INT job in Working with Integration Layer Processes (IJCT) processes tax requests.

In this chapter:

• Process Overview

• Tax Request Message (CWTaxRequest)

• Tax Response Message (CWTaxResponse)

For more information: See:

• Vertex Interface and Vertex Setup for more information on the Vertex interface.

• Avalara AvaTax Interface and Avalara AvaTax Setup for more information on the Avalara interface.

Process Overview

When Order Management System needs to calculate tax for an order and you are using a tax interface, the system:

1. generates a Tax Request Message (CWTaxRequest).

2. maps the information in the Tax Request message to the format required by the external tax system.

3. sends the tax request to the external tax system for tax calculation.

4. The external tax system calculates the tax and sends a tax response to Order Management System.

5. Order Management System maps the information in the external tax response to the Tax Response Message (CWTaxResponse).

6. Order Management System uses the information in the Tax Response message to apply tax to the order.

Tax Request Message (CWTaxRequest)

The tax request message contains order and tax information required for an external tax system to calculate tax.

Generated when? The system generates this message when tax needs to be calculated for an order during:

• order entry

• order maintenance

• pick slip preparation

• billing

For more information: See:

• Generic Tax API for an overview.

• Tax Request Message: Sample XML for a sample message.

• XML Messages for a sample of the DTD, schema, and generic sample XML of the Tax Request XML message.

Attribute Name	Type	Length	Comments
Message
source	alpha		Identifies the source of the XML message. OROMS indicates the XML message is from Order Management System.
target	alpha		Identifies the target of the XML message.
type	alpha		Identifies the type of information in the XML message.
date_created	numeric	8	The date the message was created, in YYYY-MM-DD format.
time_created	numeric	6	The time the message was created, in HH:MM:SS format.
TaxInterfaceRequest
request_type	alpha		Identifies the type of tax request. Until you bill a shipment or credit, the tax totals on an 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. Valid values are: • QUOTATION = tax requested during order creation and pick slip generation. • INVOICE = tax requested during billing. If the Send Tax to Tax Interface as Quote Not Invoice (L11) system control value is selected, the system sends a QUOTATION request type instead of an INVOICE request type. • DISTRIBUTETAX = tax overridden through the Order API. If the Send Tax to Tax Interface as Quote Not Invoice (L11) system control value is selected, the system sends a QUOTATION request type instead of a DISTRIBUTETAX request type.
company	numeric	3	The company code associated with the order. From the Company in the Order Ship To table.
entity	numeric	3	The entity associated with the division defined for the source code on the order. From the Entity Number in the Division table.
order_nbr	numeric	8	The order number requesting tax. From the Order # in the Order Ship To table.
order_shipto_nbr	numeric	3	The ship to number on the order requesting tax. From the Ship To # in the Order Ship To table.
tax_area_ID			Information will be provided at a later date.
order_addl_charge_seq	numeric	2	The order additional charge sequence number associated with the charge. From the OAC Seq # in the Order Additional Charge table.
resale_exemption_nbr	alpha	30	The tax identification number assigned to the sold to customer. From the Resale Exempt # (Tax identification) in the Order Ship To table.
sold_to_cust_class	alpha	2	The customer class code assigned to the sold to customer. From the Customer Class in the Customer Sold To table.
sold_to_cust_class_description	alpha	30	A description of the customer class. From the Description in the Customer Class table.
CustomerShipTo
ship_to_addr1	alpha	32	The street address for the ship to customer. From the: • Order ship to: NAM street address in the Order Ship To Address table. • Permanent ship to: NAM street address in the Customer Ship To table. • Recipient sold to: NAM street address in the Customer Sold To table.
ship_to_addr2	alpha	32	The second address line on the ship to customer’s address. From the: • Order ship to: NAM address line 2 in the Order Ship To Address table. • Permanent ship to: NAM address line 2 in the Customer Ship To table. • Recipient sold to: NAM address line 2 in the Customer Sold To table.
ship_to_addr3	alpha	32	The third address line on the ship to customer’s address. From the: • Order ship to: Address line 3 in the Order Ship To Address table. • Permanent ship to: Address line 3 in the Customer Ship To Extended table. • Recipient sold to: Address line 3 in the Customer Sold To Extended table.
ship_to_addr4	alpha	32	The fourth address line on the ship to customer’s address. From the: • Order ship to: Address line 4 in the Order Ship To Address table. • Permanent ship to: Address line 4 in the Customer Ship To Extended table. • Recipient sold to: Address line 4 in the Customer Sold To Extended table.
ship_to_city	alpha	25	The city on the ship to customer’s address. From the: • Order ship to: NAM city in the Order Ship To Address table. • Permanent ship to: NAM city in the Customer Ship To table. • Recipient sold to: NAM city in the Customer Sold To table.
ship_to_state	alpha	2	The state on the ship to customer’s address. From the: • Order ship to: NAM state in the Order Ship To Address table. • Permanent ship to: NAM state in the Customer Ship To table. • Recipient sold to: NAM state in the Customer Sold To table.
ship_to_state_name	alpha	25	The name of the state. From the Description in the State table.
ship_to_postal	alpha	10	The postal code on the ship to customer’s address. From the: • Order ship to: NAM zip in the Order Ship To Address table. • Permanent ship to: NAM zip in the Customer Ship To table. • Recipient sold to: NAM zip in the Customer Sold To table.
ship_to_country	alpha	3	The country on the ship to customer’s address. From the: • Order ship to: RPR country in the Order Ship To Address table. • Permanent ship to: RPR country in the Customer Ship To table. • Recipient sold to: RPR country in the Customer Sold To table.
ship_to_country_name	alpha	30	The name of the country. From the Description in the Country table.
OrderDetail
odt_line_nbr	numeric	3	The order detail line number. From the Line # in the Order Detail table.
odt_line_item_type	alpha	2	The type of charge to which tax is applied. • LM = line merchandise • LH = line handling • LF = line freight (if the order uses a line-level freight method) • OF = order freight (if the order uses an order-level freight method) • AF = additional freight
odt_item	alpha	12	The code for the item on the order line. From the ITM number in the Order Detail table.
odt_item_desc	alpha	40	The description of the item. From the Description in the Item table.
odt_SKU	alpha	14	A code for the SKU, such as color, size, or style, of the item. From the SKU code in the Order Detail table.
odt_SKU_desc	alpha	40	The description of the SKU, if this is a SKUed item. From the Description in the SKU table.
odt_arrival_date	numeric	10	The date the customer requested delivery of the item, in YYYY-MM-DD format. From the ODT arrival date in the Order Detail table.
odt_item_class	alpha	3	The item class assigned to the item on the order. From the Item Class in the Item table.
odt_item_class_desc	alpha	30	The description of the item class. From the Description in the Item Class table.
odt_long_SKU_dept	numeric	4	The long SKU department assigned to the item on the order. From the LSD Department in the Item table.
odt_long_SKU_dept_desc	alpha	30	A description of the long SKU department. From the Description in the Long SKU Department table.
odt_long_SKU_class	numeric	4	The long SKU class assigned to the item on the order. From the LSD Class in the Item table.
odt_long_SKU_class_desc	alpha	30	A description of the long SKU class. From the Description in the Long SKU Class table.
odt_long_SKU_division	alpha	3	The long SKU division for the long SKU department assigned to the item on the order line. From the Long SKU Division in the Long SKU Department table.
odt_long_SKU_division_desc	alpha	30	A description of the long SKU division. From the Description field in the Long SKU Division table.
odt_qty	numeric	5	The quantity ordered. From ODT qty ordered in the Order Detail table.
odt_price	numeric	7.2	The per-unit selling price of this item, after applying all discounts and repricing. This price reflects any coupon discount amount or dollar discount by offer or source if the Prorate Dollar Discounts and Coupons (D90) system control value is selected. From ODT price in the Order Detail table.
odt_extended_price	numeric	11.2	The actual selling price * the order quantity.
odt_tax_override	alpha	1	If this flag is Y, the order was received from an external system that specified a tax, GST, or PST amount, indicating the tax amount from the external system should be retained on the order line. From the ODT future use Y/N 1 in the Order Detail table.
odt_tax_override_amt	numeric	10.5	The tax override amount. From the Tax field in the Order Detail table.
ShipFromWarehouse
ship_from_warehouse	numeric	3	The warehouse used to ship the order. From the Warehouse in the Order Ship To table.
ship_from_country	alpha	3	The country on the ship from address. From the: • Warehouse: RPR country in the Warehouse table. • Sold to: RPR country in the Customer Sold To table.
ship_from_country_name	alpha	30	The name of the country. From the Description in the Country table.
ship_from_addr1	alpha	32	The street address for the ship from address. From the: • Warehouse: Address in the Warehouse table. • Sold to: NAM street address in the Customer Sold To table.
ship_from_addr2	alpha	32	The second address line on the ship from address. From the: • Warehouse: Address line 2 in the Warehouse table. • Sold to: NAM address line 2 in the Customer Sold To table.
ship_from_addr3	alpha	32	The third address line on the ship from address. From the: • Warehouse: Address line 3 in the Warehouse table. • Sold to: NAM address line 3 in the Customer Sold To table.
ship_from_addr4	alpha	32	The second address line on the ship from address. From the NAM address line 2 in the Customer Sold To table.
ship_from_city	alpha	25	The city on the ship from address. From the: • Warehouse: City in the Warehouse table. • Sold to: NAM city in the Customer Sold To table.
ship_from_state	alpha	2	The state on the ship to customer’s address. From the: • Warehouse: State in the Warehouse table. • Sold to: NAM state in the Customer Sold To table.
ship_from_state_name	alpha	25	The name of the state. From the Description in the State table.
ship_from_postal	alpha	10	The postal code on the ship from address. From the: • Warehouse: Zip Code in the Warehouse table. • Sold to: NAM zip in the Customer Sold To table.

Tax Request Message: Sample XML

A sample of the Tax Request Message: Sample XML is presented below.

</OrderDetail>

</OrderDetail>

</OrderDetails>

</TaxInterfaceRequest>

</Message>

Tax Response Message (CWTaxResponse)

The tax response message contains calculated tax from an external tax system.

Generated when? The system generates this message as a response to a Tax Request Message (CWTaxRequest).

For more information: See:

• Generic Tax API for an overview.

• Tax Request Message: Sample XML for a sample message.

• XML Messages for a sample of the DTD, schema, and generic sample XML of the Tax Request XML message.

Attribute Name	Type	Length
Message
source	alpha		Identifies the source of the XML message.
target	alpha		Identifies the target of the XML message.
type	alpha		Identifies the type of information in the XML message. CWTaxResponse indicates the message is a tax response.
date_created	numeric	8	The date the message was created.
time_created	numeric	6	The time the message was created.
TaxInterfaceResponse
request_type	alpha		Identifies the type of tax request. Until you bill a shipment or credit, the tax totals on an 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. Valid values are: • QUOTATION = tax requested during order creation and pick slip generation. • INVOICE = tax requested during billing. If the Send Tax to Tax Interface as Quote Not Invoice (L11) system control value is selected, the system sends a QUOTATION request type instead of an INVOICE request type. • DISTRIBUTETAX = tax overridden through the Order API. If the Send Tax to Tax Interface as Quote Not Invoice (L11) system control value is selected, the system sends a QUOTATION request type instead of a DISTRIBUTETAX request type.
company	numeric	3	The company code associated with the order. Corresponds to the Company in the Order Ship To table.
entity	numeric	3	The entity associated with the division defined for the source code on the order. Corresponds to the Entity Number in the Division table.
order_nbr	numeric	8	The order number requesting tax. Corresponds to the Order # in the Order Ship To table.
order_shipto_nbr	numeric	3	The ship to number on the order requesting tax. Corresponds to the Ship To # in the Order Ship To table.
tax_type	alpha	2	The type of charge to which tax is applied. • LM = line merchandise • LH = line handling • LF = line freight (if the order uses a line-level freight method) • OF = order freight (if the order uses an order-level freight method) • AF = additional freight
tax_area_ID
order_addl_charge_seq	numeric	2	The order additional charge sequence number associated with the charge. Corresponds to the OAC Seq # in the Order Additional Charge table.
lookup_result
CustomerShipTo
ship_to_addr1	alpha	32	The street address for the ship to customer. Corresponds to the: • Order ship to: NAM street address in the Order Ship To Address table. • Permanent ship to: NAM street address in the Customer Ship To table. • Recipient sold to: NAM street address in the Customer Sold To table.
ship_to_addr2	alpha	32	The second address line on the ship to customer’s address. Corresponds to the: • Order ship to: NAM address line 2 in the Order Ship To Address table. • Permanent ship to: NAM address line 2 in the Customer Ship To table. • Recipient sold to: NAM address line 2 in the Customer Sold To table.
ship_to_addr3	alpha	32	The third address line on the ship to customer’s address. Corresponds to the: • Order ship to: Address line 3 in the Order Ship To Address table. • Permanent ship to: Address line 3 in the Customer Ship To Extended table. • Recipient sold to: Address line 3 in the Customer Sold To Extended table.
ship_to_addr4	alpha	32	The fourth address line on the ship to customer’s address. Corresponds to the: • Order ship to: Address line 4 in the Order Ship To Address table. • Permanent ship to: Address line 4 in the Customer Ship To Extended table. • Recipient sold to: Address line 4 in the Customer Sold To Extended table.
ship_to_city	alpha	25	The city on the ship to customer’s address. Corresponds to the: • Order ship to: NAM city in the Order Ship To Address table. • Permanent ship to: NAM city in the Customer Ship To table. • Recipient sold to: NAM city in the Customer Sold To table.
ship_to_state	alpha	2	The state on the ship to customer’s address. Corresponds to the: • Order ship to: NAM state in the Order Ship To Address table. • Permanent ship to: NAM state in the Customer Ship To table. • Recipient sold to: NAM state in the Customer Sold To table.
ship_to_state_name	alpha	25	The name of the state. Corresponds to the Description in the State table.
ship_to_postal	alpha	10	The postal code on the ship to customer’s address. Corresponds to the: • Order ship to: NAM zip in the Order Ship To Address table. • Permanent ship to: NAM zip in the Customer Ship To table. • Recipient sold to: NAM zip in the Customer Sold To table.
ship_to_country	alpha	3	The country on the ship to customer’s address. Corresponds to the: • Order ship to: RPR country in the Order Ship To Address table. • Permanent ship to: RPR country in the Customer Ship To table. • Recipient sold to: RPR country in the Customer Sold To table.
ship_to_country_name	alpha	30	The name of the country. Corresponds to the Description in the Country table.
SuggestedTaxAreaID
suggested_tax_area_ID
OrderDetail
odt_line_nbr	numeric	3	The order detail line number. Corresponds to the Line # in the Order Detail table.
odt_line_item_type	alpha	2	The type of charge to which tax is applied. • LM = line merchandise • LH = line handling • LF = line freight (if the order uses a line-level freight method) • OF = order freight (if the order uses an order-level freight method) • AF = additional freight
odt_total_tax_amt	numeric	10.5	The total tax amount on the order line. Corresponds to the Tax in the Order Detail table.
odt_total_tax_rate	numeric	5.2	The tax rate used to calculate tax for the order line.
SuggestedTaxJurisdiction
suggested_tax_jurisdiction	alpha	10	The tax jurisdiction the tax system suggests for the order line.
suggested_tax_jurisdiction_desc	alpha	30	The description of the tax jurisdiction.
suggested_tax_effective_date	numeric	8	The date the suggested tax becomes effective.
suggested_tax_expiration_date	numeric	8	The date the suggested tax expires.
JurisdictionLevel
jurisdiction_level	alpha		The tax jurisdiction level. Valid values are: • Country • Composite • State • Country • City • Special
jurisdiction_level_desc	alpha		A description of the tax jurisdiction level.
jurisdiction_level_tax_amt	numeric	10.5	The tax amount for the jurisdiction level.
jurisdiction_level_tax_rate	numeric	5.2	The tax rate for the jurisdiction level.