tax integration cookbook

7/31/2019 Tax Integration Cookbook

1/76

Oracle E-Business SuiteTax Partner Integration Cookbook

Oracle Partner Network

Copyright (C) 2006 Oracle Corporation

All Rights Reserved


2/76

For use by Oracle employees and authorized partner only. Do not distribute to third parties. Page 2 of 76

Contents

Oracle E-Business Suite....................................................................................1

Tax Partner Integration Cookbook................................................1

Overview............................................................................................................. 5

Oracle E-Business Suite Integration Framework.......................... 6

E-Business Suite Integration Standards ....................................................................................6

E-Business Suite Integration Outsourcing Standards ........................................................6

Tax Partner Services Integration Steps..............................................8

E-Business Suite Tax Events............................................................................................................8

Some Important Interface Attributes ...........................................................................................9Line Level Action attribute and its values............................................................................................... 9Attributes referring other Document Types ............................................................................................. 10Tax Line Attributes representing End User or E-Business Suite Processes Overrides............................ 10

Overrides by End User .........................................................................................................................10Overrides by E-Business Suite Processes.............................................................................................11

Attributes to uniquely (key) identify a Transaction Header, Line and Tax Line .....................................11

PL/SQL Based Tax Interfaces.......................................................................................................12

Registration and Plug-in of Partner Services for Out-of-the-Box Integration ....14

Additional Attributes for Tax Partners Use .........................................................................14

Example Scenarios Illustrating E-Business Suite Tax

Interfaces ..........................................................................................................17

Example 1 Sales Invoice..............................................................................................................17Step 1: Create Sales Invoice ..................................................................................................................... 18Step 2: Override Tax on Sales Invoice ..................................................................................................... 19Step 3: Update Sales Invoice....................................................................................................................21Step 4: Complete Sales Invoice................................................................................................................23Step 5: Create and Apply Credit Memo for Sales Invoice ....................................................................... 23

Example 2 Purchase Invoice .....................................................................................................24Step 1: Enter Prepayment ......................................................................................................................... 25Step 2: Create Purchase Invoice with Prepayment Applied.....................................................................25Step 3: Cancel Purchase Invoice ..............................................................................................................27


3/76


Example 3 Importing Sales Invoice ....................................................................................... 27Step 1: Import Sales Invoice with Tax ..................................................................................................... 28Step 2: Update Header Level Information on Sales Invoice .................................................................... 29Step 3: Tax Override on Sales Invoice by E-Business Suite Process.......................................................30Step 4: Update Header Level Reporting Attribute on Sales Invoice........................................................31

Step 5: Update Line Level Reporting Attribute(s) on Sales Invoice........................................................31

Oracle E-Business Suite Tax Interfaces ...........................................33

Tax Calculation....................................................................................................................................34

Tax Synchronization .......................................................................................................................... 39

Global Document Update ...............................................................................................................42

Commit for Tax ....................................................................................................................................43

Tax Partner Services Registration and Plug-In APIs ...............44

Tax Partner Services Registration ............................................................................................. 44Create Tax Partner Service Registration ..................................................................................................45Delete Tax Partner Service Registration ..................................................................................................46

Tax Partner Services Plug-in........................................................................................................46

Out-of-the-box Integration .............................................................................................................47

Appendix A Data Types and Database Views ...........................49zx_tax_partner_pkg.messages_tbl_type...................................................................................................49zx_tax_partner_pkg.output_sync_tax_lines_tbl_type .............................................................................. 50zx_tax_partner_pkg.tax_currencies_tbl_type........................................................................................... 51zx_tax_partner_pkg.tax_lines_tbl_type....................................................................................................51zx_tax_partner_pkg.trx_rec_type.............................................................................................................53zx_api_prvdr_pub.error_messages_tbl.....................................................................................................53ZX_IMPORT_TAX_LINES_INPUT_V .................................................................................................53ZX_O2C_CALC_TXN_INPUT_V / ZX_P2P_CALC_TXN_INPUT_V ............................................... 54ZX_SYNC_HDR_INPUT_V ................................................................................................................... 64ZX_SYNC_LINES_INPUT_V ................................................................................................................ 66

ZX_SYNC_TAX_LINES_INPUT_V......................................................................................................67

Appendix B List of Document Types .............................................69

Appendix C List of Country Codes.................................................70

Appendix D Tax Partner Service - Sample Logic.....................71

Appendix E Error Messages List for Registration APIs......72


4/76


Create Tax Partner Service Registration API...........................................................................................72Delete Tax Partner Service Registration API...........................................................................................72

Appendix F What has changed since Release 11i?..................73

Strategy Change for Tax Partner Integration ......................................................................73

Strategy Change for Supporting Customized User Procedures ..................................73

Strategy Change for Exemptions handling ............................................................................74

Appendix G List of Geography Types...........................................75

Appendix H Frequently Asked Questions ...................................76


5/76


Overview

The Tax Partner Services Integration Cookbook provides information for allowing eligible Oracle Partner

Network (OPN) members to integrate their tax solutions with Oracle E-Business Suite. This documentadheres to the integration standards published in Oracle E-Business Suite Integration Development Guideand Oracle E-Business Suite Outsourcing Integration Development Guide, both of which are brieflydescribed in Oracle E-Business Suite Integration Frameworksection.

This document is intended for product managers, analysts and developers of Tax Partners who plan tointegrate their transaction (indirect) tax engine with E-Business Suite.

This document introduces the E-Business Suite tax events concept, open tax interfaces for integrating taxpartner services and interface parameters. This document further discusses some business scenarios that taxpartners need to understand for making themselves compatible with the E-Business Suite tax interfaces and

parameters. This document also provides the technical and functional details of the E-Business Suite APIs,which should be invoked to register and plug-in tax partner services with E-Business Suite.

By integrating with E-Business Suite tax interfaces, tax partners are no longer needed to have separateintegrations built for different E-Business Suite products. Moreover, E-Business Suite Products no longerneed to worry about integration with Tax Partners as Tax Partners integration is now handled through E-Business Suite tax interfaces.

This document also discusses about the infrastructural support provided by E-Business Suite to let customerscapture additional information specific to a tax partner. This document explains all the interface parametersprovided by E-Business Suite. However, this document does not provide the details of what additional

information needs to be captured for a specific tax partner. The partners are required to publish about it intheir documentation provided to the mutual customers.


6/76


Oracle E-Business Suite Integration Framework

E-Business Suite Integration Standards

E-Business Suite Integration (EBSi) helps qualified Oracle Partner Network (OPN) members to providecomplete solutions to customers, integrating their complementary products with Oracle E-Business Suite.

Oracle E-Business Suite Integration Development Guide describes the integration development processfollowed by partners participating in Oracles E-Business Suite Integration (EBSi) initiative. It is intendedfor Oracle Partner Network (OPN) members who plan to integrate their applications with Oracle E-BusinessSuite. It provides useful guidance to:

Integration Project Managers

Integration Developers

Other Integration Team Members

The following tasks necessary to perform the integration process are described in this guide. Integrationtechniques, such as use of Oracle APIs, are outlined. This guide also discusses the responsibilities of thepartner.

Integration Project Launch

Determination of Strategy and Scope of integration

Analysis of specifications and processes for integration

Design for building integration code

Build of Integration Code

User Documentation

EBSi Approval for integration Distribution and support of the integration

Integration Upgrades and Enhancements

Copies of this document and other E-Business Suite integration-related information are available in theInitiatives area of the Home tab at Oracle Partner Network web site (http://partner.oracle.com/)

E-Business Suite Integration Outsourcing Standards

E-Business Suite Outsourcing Integration (EBSO Integration) helps qualified Oracle Partner Network (OPN)

members to provide complete solutions to customers, integrating their complementary products with OracleE-Business Suite in Outsourcing environment.

The focus of the Oracle E-Business Suite Outsourcing Integration Development Guide is the EBSOIntegration standards and accepted techniques for Oracle E-Business Suite in Outsourcing environment. Theguide describes Integration development standards for Oracle E-Business Suite Outsourcing environmentonly and is not intended to describe other Outsourcing offerings.

Information about the qualifications for EBSO Integration can be found at the Oracle Partner Network website (http://partner.oracle.com/) and for Outsourcing at http://www.oracle.com/outsourcing. Copies of thisdocument are also available in the Partner Initiatives area of the Home tab at Oracle Partner Network web

site (http://partner.oracle.com/).


7/76


Oracle E-Business Suite Outsourcing Guide contains description for the following elements:

Outsourcing Life Cycle

Outsourcing Automation Platform

Outsourcing Services

The Outsourcing Life Cycle is a standardized, repeatable, highly automated process through which all OracleOutsourcing services are delivered. The tasks involved in this integration process are similar to thosedescribed in the above section for Oracle E-Business Integration Development Guide.

Outsourcing Automation Platform is a framework that defines Outsourcing software architecture, hardwarearchitecture, and Outsourcing tools.

Outsourcing Services contain administration, management and software and hardware configuration. Theseservices are delivered daily as services through which long term growth and optimal performance of theenvironment is assured.


8/76


Tax Partner Services Integration Steps

Integration with Oracle E-Business Suite requires a tax partner to perform the following tasks

Understand concept behind E-Business Suite tax events

Understand some important attributes of E-Business Suite tax interfaces

Provide PL/SQL based implementation of tax interfaces

Register and plug-in tax services for out-of-the-box integration with E-Business Suite

Publish user guidelines for what information to capture in additional transaction attributes providedby E-Business Suite tax interfaces. These attributes are provided exclusively for tax partners use.

Each of these steps is explained in detail in the subsequent sections.

E-Business Suite Tax Events

In this section, we have taken a scenario in a typical Sales Invoice lifecycle to explain the concept of a taxevent.

In this example scenario, each step represents an action being taken on the Sales Invoice. In this example,Sales Invoice is the transaction while Create, Update, Override Tax and Complete are the actions. A

transaction life cycle may have number of events but not all actions on a transaction require integration witha tax engine. Only those actions that require tax calculation or tax reporting attributes synchronization are taxevents.

With the help of above example, let us understand the terms Document Type and Document Level Action.In this example, Sales Invoice would be called Document Type while actions Create, Update etc. wouldbe referred to as Document Level Actions.

A complete list of Document Types is available in Appendix B.

A document type is categorized either as a Procure-to-Pay or Order-to-Cash type of document. We have used

the term Business Flow for such document categorization. Procure-to-Pay represents purchase transactions.The business flow code for this category is P2P. Order-to-Cash represents sales transactions. The businessflow code for this category is O2C.

A document level action invokes tax interface(s) based on the situation. For example, a document levelaction UPDATE requires re-calculation of taxes while the document level action SYNCHRONIZErequires update to the tax repository for the changed value of one or more tax reporting attributes liketransaction number. In both the above situations, for an end user, it is a change in the transaction.

Oracle would enhance the list of document type and document level actions as and when new Oracle E-Business Suite applications and events are supported. Certain document type or document level actions may

not be the tax event for a given situation. For example, few states in the United States do not impose any


9/76


sales tax, there is no sales tax collected on pre-payments in the United States at the time this document waswritten etc. It is the responsibility of the Tax Partner to determine whether there are any taxes or not for aspecific document type, document level action in a particular situation.

Some Important Interface Attributes

In this section, we are introducing some attributes that are not business related but are very important for thetax partner services. A brief explanation of each of these attributes is given here including the purpose ofthese attributes.

Line level action attribute

Transaction attributes that refer to other document types

Tax line attributes that represent overrides made by end user or by E-Business Suite processes

Attributes to uniquely (key) identify a transaction header, line and tax line

Line Level Action attribute and its values

While Document Level Action attribute represents an action on a Document Type (transaction), each line ofa transaction may have a different Line Level Action associated with it. For example, when UPDATEaction happens on a transaction, all the lines of that transaction may not be updated. The lines that areupdated have the line level action as UPDATE, whereas the lines that are newly added to an existingtransaction have the line level action as CREATE.

The applicable line level actions for each tax interface are explained in the description of that interface underOracle E-Business Suite Tax Interfaces section. Following are all possible line level actions with a briefexplanation:

Create To identify a newly created or imported transaction line requiring tax calculation

Update To identify a transaction line on which one or more attributes are updated after the last taxcalculation

Cancel To identify a transaction line marked as canceled. The transaction line amount may or maynot be set as zero when a transaction line is marked as Canceled. A canceled transaction line does notadd to the outstanding balance of the transaction. Canceled lines are not physically deleted from E-Business Suite. Some E-Business Suite Applications set the transaction line amount as zero whilecanceling a transaction line. This information is provided to the Tax Partners to synchronize theirrepository with Oracle E-Business Suite.

Delete To identify a deleted transaction line. Such lines are physically deleted from the transaction.

Synchronize To identify updates to attributes on a transaction line, which are used for tax reportingand not for tax calculation. This action does not require recalculation of taxes.

Quote To identify a transaction line that requires only a tax estimate and is not to be recorded in thetax repository

Create With Tax To identify an imported transaction line that is being imported with tax linesassociated with it. Additional taxes may be calculated for such transaction lines.


10/76


Line Info Tax Only To identify a dummy transaction line that is being stored for storing a tax onlyline.

Record With No Tax To identify an imported transaction line that is being imported without anyassociated tax lines and does not require tax calculation.

Apply From To identify a transaction line of another document included in the current document,e.g. prepayment line on a Purchase Invoice

Unapply From To identify a transaction line of another document unapplied from the currentdocument, e.g. negative prepayment line on a Purchase Invoice

Attributes referring other Document Types

E-Business Suite has certain attributes to specify the association of one document type to other documenttypes. For example, a Credit Memo may be created to apply a credit to an existing invoice. This kind of a

relationship between document types may influence tax calculation. To capture such relationships, E-Business Suite has added the attributes for other document types at the line level. These attributes areavailable, to ensure accurate tax calculation.

Adjusted Document Type It is used for a prior document type that is being adjusted by the currentdocument type. As an example, for an applied sales credit memo, the existing sales invoice, to whichthe credit is being applied, is the adjusted document. When calling tax partner service for determiningtaxes for the applied credit memo, E-Business Suite populates the adjusted document type relatedattributes on the credit memo line with the original invoice line identifier. Tax partner service for taxcalculation should ensure that the tax amounts for any tax on the credit memo do not exceed those onthe invoice. Also, it must be ensured that there is no additional tax returned for the credit memo,

which is not present for the sales invoice being adjusted.

Applied From Document Type It is used to indicate application of a transaction line from a priordocument to the current document type e.g. a prepayment amount from an existing prepaymentinvoice is applied to a new Purchase Invoice. When calling tax partner service for determining taxesof the purchase invoice, E-Business Suite populates this information on the applied prepayment lineof the standard invoice.

Tax Line Attributes representing End User or E-Business Suite Processes Overrides

This sub-section describes the attributes that represent overrides on the tax lines. The values of these

attributes are passed to the appropriate tax partner interface, along with other tax line attributes, forsynchronizing the tax partner repository.

Following are the two types of overrides possible in E-Business Suite:

Overrides by End User

Overrides by E-Business Suite Processes

Overrides by End User


11/76


E-Business Suite provides user interfaces for the end user to view and modify the taxes calculated for atransaction. An end user can update, cancel or delete an existing tax line determined by a tax partner service.However, the end user can only update the values of tax rate % and tax amount attributes.

The end user can manually enter additional tax lines too. These manual tax lines may or may not have an

actual transaction line. The tax lines that are not associated with a dummy transaction line are referred to astax only lines and are represented by setting Tax Only Line Flag attribute to Y.

The following table lists all the attributes that provide information regarding the user override of a tax line:

Attribute Description

User Override Flag Indicates whether the end user has overridden the tax line

Last Manual Entry Indicates whether the end user has overridden the tax amount or the tax rate %

Manually Entered Flag Indicates if the end user has manually entered the tax line

Tax Only Line Flag Indicates if this is a tax only line

Cancel Flag Indicates whether the end user has canceled the tax lineDelete Flag Indicates whether the end user has deleted the tax line

Overrides by E-Business Suite Processes

Some business processes in the Oracle E-Business Suite necessitate changes to the tax lines returned by thepartner. For example, if a tax line is already accounted, then it cannot be deleted after re-calculation. If theship to location changes to another state for the corresponding transaction line, it may necessitate the deletingof the previous tax line and creation of another tax line for the new ship-to state. However, since anaccounted tax line cannot be deleted, it is marked as Canceled with a zero tax amount, but retained tocreate reversing accounting entry and for reference with the accounting system. The E-Business Suite

synchronizes these zero amount tax lines with the tax partners repository.

E-Business Suite sets the Ebiz Override Flag attribute to Y for indicating the overrides made exclusivelyby an E-Business Suite process, without any intervention from the end user.

Attributes to uniquely (key) identify a Transaction Header, Line and Tax Line

The following two attributes uniquely identify a transaction header:


Document Type Identifier Represents code of the document type (e.g. 1 Purchase Invoice, 4 Sales Invoice etc)Transaction Identifier Represents the unique identifier of the document type instance

The following four attributes uniquely identify a transaction line:


Document Type Identifier Represents code of the document type (e.g. 4 Sales Invoice,1 Purchase Invoice, etc)

Transaction Identifier Represents the unique identifier of the document type instance

Transaction Line Identifier Represents the identifier of a transaction line within the transaction

Transaction Level Type Represents code of the transaction line type (e.g. LINE, FREIGHT). For few E-Business


12/76


Suite applications, transaction line identifier along with transaction level type identifies atransaction line uniquely within a transaction.

This attribute is only for the purposes of uniquely identifying a transaction line. It is not tobe used for tax calculations.

The following seven attributes uniquely identify a tax line:


Document Type Identifier Represents code of the document type (e.g. 4 Sales Invoice,1 Purchase Invoice, etc)

Transaction Identifier Represents the unique identifier of the document type instance

Transaction Line Identifier Represents the identifier of a transaction line within the transaction

Transaction Level Type Represents code of the transaction line type (e.g. LINE, FREIGHT). For few E-BusinessSuite applications, transaction line identifier along with transaction level type identifies atransaction line uniquely within a transaction.

This attribute is only for the purposes of uniquely identifying a transaction line. It is not tobe used for tax calculations.

Country Represents the taxation country

Tax Represents a classification of the charges imposed by a government through a fiscal or taxauthority. For example, it can be STATE, COUNTY, CITY, DISTRICT COUNTY,DISTRICT CITY, etc. While integrating with the tax partner, taxes (codes) defined in thepartner system needs to be uploaded into Oracle E-Business Suite to ensure the dataconsistency.

Situs Represents the location to which the Tax applies. For example, it can be SHIP_TO,BILL_TO, etc

PL/SQL Based Tax Interfaces

Since many E-Business Suite application processes reside in the database tier (not the middle-tier), PL/SQLtechnology is optimal for integrating tax partner services with E-Business Suite. Hence, it is a pre-requisitethat the tax partner services to be integrated with E-Business Suite should be PL/SQL stored procedures. Taxpartners are expected to wrap their services with PL/SQL stored procedures if written in differenttechnology.

E-Business Suite has defined a set of four tax interfaces to integrate tax partner services in a uniform, clearlydefined, and consistent manner. Each tax interface satisfies a specific functionality in the overall taxprocessing for a transaction. These interfaces are the single point of integration for tax partners to integratewith all E-Business Suite applications.

Following table lists all the four E-Business Suite tax interfaces with a short description. For detaileddescription of all these tax interfaces please refer to Oracle E-Business Suite Tax Interfaces section.

Tax Interface Name Description

Tax CalculationCalculates and Recalculates Taxes. Also, Imports documents from an external system withtax lines.

Tax SynchronizationSynchronizes tax reporting attributes changes in the application product. Also,synchronizes tax line overrides by an end user or an E-Business Suite process.

Global Document UpdateCommunicates to the tax partner about document level actions that are applicable to alltransaction lines such as CANCEL, DELETE, PURGE etc.

Commit for Tax Communicates to the tax partner when a data base commit is issued for a tax reportable


13/76


Tax Interface Name Description

transaction for which a tax partner was called for the tax calculation in the same databasetransaction. This interface is needed only if a tax partner is calling services written inmiddle-tier.

At present, these interfaces are available for US Sales and Use Tax only. Tax partners can provide a separateset of tax services for different business flows, or only one set for both the business flows (Order-To-Cashand Procure-To-Pay).

The following diagram shows a typical scenario where multiple tax partners are integrated with E-BusinessSuite for different countries and business flows.

In the above example diagram, there are two tax partners integrated with E-Business Suite Tax Interfaces. Ofthese, Tax Partner 1 provides a set of tax services to integrate with E-Business Suite Order-To-CashBusiness Flow and another set for Procure-To-Pay Business Flows for US Sales and Use Taxes. TaxPartner 2 provides only one set of tax services for integrating with both Order-To-Cash and Procure-To-Pay Business Flows.

E-Business Suite processes one document at a time through the tax interfaces passing header and all lines inone call.

Tax partner services are invoked synchronously. Hence, tax partner services are expected to commit basedon the Oracle Database commit instructions issued from E-Business Suite applications.


14/76


To provide support for some tax partners that are in the process of writing their tax services usingApplication Servers (middle-tier), E-Business Suite provides another optional interface, namely Commit forTax interface, to communicate the Oracle Database commit instruction to the tax partners. For moreinformation about this tax interface, please refer to Oracle E-Business Suite Tax Interfaces section. Pleasenote that the three interfaces listed in the table above are mandatory while Commit for Tax interface is

optional and applies to only those tax partners who plan to wrap their non PL/SQL services with PL/SQLstored procedures.

Registration and Plug-in of Partner Services for Out-of-the-Box IntegrationE-Business Suite provides a set of APIs for the tax partners to register and plug-in their tax services. Taxpartners can register only one tax service for a business flow and tax interface. The tax services that a taxpartner registers should be compatible with the E-Business Suite tax interfaces, as discussed in Oracle E-Business Suite Tax Interfaces section. This means that the specification of the tax partner service shouldhave the parameters with the same data type and also, in the same order, as the parameters listed for the taxinterface that they are being registered with. Please refer Appendix D for the sample logic representative ofhow to define the specification of a tax partner service that is compatible with the tax calculation interface.

Following table lists the E-Business Suite registration and plug in APIs with a short description of each API.For detailed description of all these APIs please refer to Tax Partner Services Registration and Plug-In APIssection.

API Name Description

create_srvc_registration Creates a tax partner service registration for a business flow and tax interface

delete_srvc_registration Deletes an existing tax partner service registration for a business flow and tax interface

execute_srvc_plugin Plugs in the registered tax partner services into the execution flow of E-Business Suite

Tax partners can provide out-of-the-box integration solution to mutual customers by using these APIs toregister and plug-in their tax services as part of their installation process.

Additional Attributes for Tax Partners Use

Certain information required by a tax partner service may not be captured in E-Business Suite. For example,a tax partner service may require username and/or password needed to validate the calling system beforeexecuting a tax partner service. E-Business Suite has provided additional attributes with each of its taxinterfaces. These attributes enable a tax partner service to receive additional information specific to the taxpartner. E-Business Suite also provides infrastructure for its customers to execute their custom PL/SQL

procedures, which derive the values of these additional attributes, just before calling a tax partner service.

Following are additional attributes provided by E-Business Suite for tax partners use. These are divided intothree sets, based on their data types. The three sets of additional attributes are provided at both transactionheader and line levels.

Header Char 1 .. Header Char 30 of type VARCHAR2

Header Numeric 1 .. Header Numeric 10 of type NUMBER

Header Date 1 .. Header Date 5 of type DATE.

Line Char 1 .. Line Char 30 of type VARCHAR2

Line Numeric 1 .. Line Numeric 10 of type NUMBER


15/76


Line Date 1 .. Line Date 5 of type DATE.

What each of these attributes means to a tax partner service is to be defined by the tax partner. Tax partnersmay choose to use none, some, or all of these attributes.

A tax partner needs to identify what additional information is expected in each of these attributes and publishit in the documentation provided to the mutual customers. This documentation should also describe if valuesare mandatory or optional. It should also provide the list of valid values, if applicable.

Based on the documentation provided by the tax partner, the customers can create PL/SQL procedures (userprocedures) for deriving the values of the additional attributes. The customers can then register and plug inthose user procedures with E-Business Suite.

The following diagram provides an example to demonstrate how these additional attributes can be made useof by a tax partner.

In the above example diagram, the tax partner has identified Header Char 1 (of type VARCHAR2) asCompany Code, and Line Char 1 (of type VARCHAR2) as Customer Class and documented it in the user

manual.


16/76


In the above case a tax partner would publish the following information to the mutual customers.

Attribute Data Type Level Mapped To

company_code NUMBER Header Header Numeric 1

customer_class VARCHAR2 Line Line char 1

The mutual customer defines one or more PL/SQL procedures to derive the values of these attributes. Usershave flexibility of writing additional attributes derivation logic differently for each operating unit or legalentity. The customer then registers and plugs-in his user procedures with E-Business Suite by making use ofthe infrastructure provided by E-Business Suite.

As shown in the above diagram, during the actual tax processing, E-Business Suite executes the userprocedures to populate the attributes Header Char 1 (of type VARCHAR2), and Line Char 1(of typeVARCHAR2). E-Business Suite then calls the tax partner service and passes these values to the tax partnerservice. Please note that any validations for the values of these attributes are to be carried out by the tax

partner service.


17/76


Example Scenarios Illustrating E-Business Suite Tax Interfaces

In this section, we have taken three examples to illustrate how E-Business Suite Tax Interfaces come intoplay for different tax events. These examples also describe the expected behavior of tax partner services. Thefollowing information applies to all the three examples:

Only few transaction line parameters are shown in the examples for simplicity.

Only few tax line attributes are shown here for simplicity. However, all relevant tax line attributesmust be passed back to E-Business Suite.

Examples taken here are by no means exhaustive and also, may not depict the actual E-Business Suiteapplication behavior. E-Business Suite applications specific details are available in the user guides ofthe applications.

The sample data shown for the tax lines does not represent the actual taxes of the example

jurisdictions considered.

Example 1 Sales InvoiceIn this example, we have taken a sample life cycle of a Sales Invoice to explain how calls are made to the taxpartner services through E-Business Suite tax interfaces.

The following diagram shows different tax events (i.e. document level actions) that may occur on a typicalSales Invoice. Each step represents a tax event in this diagram.

E-Business Suite Tax Interfaces for Example 1

STEP 1: Create Sales Invoice Tax Calculation Interface is invoked with the following document type,document level action and line level action:

Attribute Value

Document Type Identifier 4 (Sales Invoice)

Document Level Action CREATELine Level Action CREATE (for all invoice lines)

STEP 2: Override Tax on Sales Invoice Tax Synchronization Interface is invoked with the followingdocument type and document level action:

Attribute Value


Document Level Action SYNCHRONIZE_TAX_LINES

The following two points must be noticed for this tax event:


18/76


Invoice header and overridden tax lines information is passed to the tax partner service.

No invoice line is passed to the tax partner service.

STEP 3: Update Sales Invoice - Tax Calculation Interface is invoked with the following document type,document level action and line level action:

Attribute Value


Document Level Action UPDATE

Line Level Action UPDATE for changed invoice line(s), CREATE for newly added invoice line(s),CANCEL for canceled invoice line(s), and DELETE for the deleted invoiceline(s)

STEP 4: Complete Sales Invoice Global Document Update Interface is invoked with the followingdocument type and document level action:

Attribute Value


Document Level Action FREEZE_FOR_TAX

STEP 5: Create and Apply Credit Memo to Sales Invoice Tax Calculation Interface is invoked with thefollowing information:

Attribute Value

Document Type Identifier 6 (Sales Credit Memo)

Document Level Action CREATE

Line Level Action CREATE for all lines

Adjusted Document Information Sales Invoice Information

Step 1: Create Sales Invoice

Consider a sales transaction for the customer, ABCD Technologies, who buys five monitors, each priced at$100.00, and five hard drives, each priced at $50.00 from XYZ Corporation. Following diagram shows thesample data passed to the tax partner service for the sales invoice of XYZ Corporation:


19/76


Following diagram shows the tax lines returned by the tax partner calculation service for Invoice # 565. Thisinformation is stored in E-Business Suite. Please note that this example shows only three tax lines per itemline, although after a tax calculation, a tax partner may return any number of tax lines depending on theapplicable tax laws.

Please note that the tax line attributes shown below are always required for the tax lines information to bemeaningful in E-Business Suite.

Attribute Value

Tax STATE, COUNTY, or CITY

Situs SHIP_TO (in this example)

Tax Jurisdi ction CA, San Mat eo, or Redwood City

Tax Currency Code USD

Tax Amount

Step 2: Override Tax on Sales Invoice

Let us assume that the monitors are 100% exempt for all taxes, but the exemption information is not yetsetup in the tax partner system. The end user decides to override the tax amount as highlighted in thefollowing diagram:


20/76


In this scenario, the changed tax information is communicated to the tax partner synchronization service.Please note that a user may not always override tax amount as 0. Only the transaction header identifiers andthe overridden tax line(s) are provided to the tax partner service.

For Tax Line 1 of Line 1 of Invoice # 565, following are some of the tax line attributes sent to the taxpartner. Similar information is passed for the other overridden tax lines of this example.

Attribute Value

Tax State (the possible values for the attribute Tax would beprovided by the tax partners for upload in Oracle E-BusinessSuite)

Situs SHIP_TO

Tax Amount 0

User Override Flag Y

Last Manual Entry TAX_AMOUNT

Manually Entered Flag N

Tax Only Line Flag N

Cancel Flag N

Delete Flag N

The tax partner service is expected to synchronize the tax information in the tax partner repository. Since,synchronization service is called to synchronize the tax amounts between E-Business suite and the taxpartner, recalculation of taxes is not expected for this service. It should not return changed tax and/ortransaction line amounts. It may return the effective tax rate and/or taxable basis, if determined duringsynchronization. E-Business Suite records the effective tax rate and/or taxable basis returned by the taxpartner service.

If there is any subsequent update to this invoice that requires tax re-calculation, the tax partners need toconsider the effect of the tax line override during re-calculation.


21/76


Step 3: Update Sales Invoice

Assume that ABCD Technologies decides to

purchase 6 monitors instead of five

purchase 10 keyboards, priced at $20 each cancel the order for hard drives

Because the invoice is not yet completed, XYZ Corporation has updated their invoice to reflect the abovechanges. The following diagram shows the updated Invoice # 565 information that is sent to the tax partnerservice for re-calculation. The following diagram represents the canceled invoice line as crossed out. In theactual data, the line level action of the invoice line is sent to the tax partner service as CANCEL

Please note that the transaction line for hard drives is canceled (physically retained with the status ascanceled). Instead, this transaction line can be physically deleted too. If such is the case, E-Business Suitepasses deleted transaction line identifiers to the tax partners with line level action as DELETE instead of

CANCEL. Please note that for deleted transaction lines, no re-conciliation is needed because thetransaction lines are physically deleted from the transaction tables in Oracle E-Business Suite.

Following diagram shows the resultant tax lines returned by the tax partner service. It also represents thecanceled invoice and tax lines as crossed out. The canceled invoice lines are sent to tax partners by Oracle E-Business suite and tax partners are not expected to return the tax lines corresponding to the canceled invoicelines. Similar to cancel, if the invoice line for the hard drives is physically deleted, then also E-BusinessSuite does not expect the tax partner to return any tax lines back for the deleted invoice line. Please note thatthe tax partners are expected either to physically delete all tax lines associated with a deleted transaction lineor just mark them as deleted, depending on the audit compliance consideration by the partner.


22/76


If the tax partner retains the user overridden tax amounts, then the resultant tax lines returned by the taxpartner service are as shown in the following diagram. Please note that if there are no changes made to aninvoice line but a call to re-calculate taxes is issued, the tax partner must return exactly the same tax lines asalready stored in Oracle E-Business Suite. In the context of above examples, if the quantity of monitors wasnot changed but the call to recalculate tax was made, the tax amounts retuned should all be zeros.


23/76


Please note that in this example, there are no updates on the header level attributes. In case of header levelattributes update, all the transaction lines are passed to the tax partners.

However, in this example, all the transaction lines got changed, and hence, all transaction lines are passed tothe tax partner.

To illustrate another situation, let us consider that the order for hard drives was not canceled, i.e. Line 2 ofInvoice # 565 did not undergo any changes. In that case, only the changed Lines 1 and 3 of Invoice # 565 arepassed to the tax partner. In this case, if a header level max tax is involved, then the tax partner service canre-calculate taxes for the whole transaction (including Line 2), even though all transaction lines are notpassed to it. E-Business Suite can handle such a situation if and only if the tax partner service setsthreshold_indicator_flag to Y on all tax lines of that transaction.

Step 4: Complete Sales Invoice

Invoice # 565 is completed by XYZ Corporation. This means that it has reached a final state and hence, is

available for reporting to the tax authorities. In this case, the tax partner service for Global Document Updateinterface is given the following information:

Attribute Value


Transaction Identifier Sales invoice transaction id for Invoice # 565

Document Level Action FREEZE_FOR_TAX

Step 5: Create and Apply Credit Memo to Sales Invoice

Suppose that ABCD Technologies has returned 3 monitors back to XYZ Corporation due to some faultyoperation. XYZ Corporation is issuing a Credit Memo for the returns and applies it to invoice # 565.

Following diagram shows the credit memo details, which is sent to the tax partner calculation service.

The credit memo is a separate transaction, but it keeps the link to the invoice that it adjusts. Following arethe adjusted document attributes sent to the partner with the credit memo line:

Attribute Value

Adjusted Documents 4 (Sales Invoic e)


24/76


Attribute Value

Document Type Identifier

Adjusted Document TransactionNumber

565

Adjusted Document Transaction

Identifier

Invoice transaction id for invoice # 565

Adjusted Document LineIdentifier

Invoice transaction line id for line # 1 of invoice # 565

When a credit memo is applied to an invoice, the tax partner calculation service is called to calculate the Taxon the credit memo. The tax partner service is expected to handle max tax condition if applicable. Followingdiagram shows the resultant tax lines returned by the tax partner service for the credit memo.

Example 2 Purchase InvoiceIn this example, we have taken a case from Procure-to-Pay flow to explain how calls are made to the taxpartner services through E-Business Suite tax interfaces.


STEP 1: Enter Prepayment Tax Calculation Interface is invoked with the following document type,document level action and line level action:

Attribute Value

Document Type Identifier 7 (Purchase Prepayment)


Line Level Action CREATE for all prepayment lines


25/76


STEP 2: Create Purchase Invoice with Prepayment Applied- Tax Calculation Interface is invoked withthe following information:

Attribute Value

Document Type Identifier 1 (Purchase Invoice)Document Level Action CREATE

Line Level Action APPLY_FROM for the prepayment application line and CREATE for all otherinvoice lines

Applied From Document LineInformation

Prepayment Information for the prepayment application line

STEP 3: Cancel Purchase Invoice Global Document Update Interface is invoked with the followinginformation:

Attribute Value

Document Type Identifier 1 (Purchase Invoice)

Document Level Action CANCEL

Step 1: Enter Prepayment

Consider that ABCD Technologies makes prepayment for five keyboards to XYZ Corporation. Followingdiagram shows the sample data for this prepayment that is sent to the tax partner calculationservice.

In this example of US Sales Tax, we have assumed that the tax partner does not return any tax lines for the

pre-payment invoice.

Step 2: Create Purchase Invoice with Prepayment Applied

Suppose that ABCD Technologies enters a purchase invoice for the five keyboards that they bought fromXYZ Corporation for $100. Also, suppose that the formerly created prepayment PP.1001 is applied to thisinvoice. The total invoice amount owed by ABCD Technologies becomes zero at this point. Followingdiagram shows the sample data for the purchase invoice that is sent to the tax partner service:


26/76


Following diagram shows the tax lines returned by the tax partner service. The total invoice amount owed byABCD Technologies at this point becomes $8.60.

For the prepayment line PP.1001.Line1 shown in the above example, E-Business Suite passes the followingattributes that refer to the original prepayment transaction:

Attribute Value

Applied From Document TypeIdentifier

7 (Purchase Prepayment)

Applied From TransactionNumber

PP.1001

Applied From TransactionIdentifier

Prepayment transaction id for PP.1001

Applied From Line Identifier Prepayment transaction line id for PP.1001.Line 1


27/76


Please note that since tax was not calculated on the prepayment document, it is also not calculated on thepurchase invoice line that corresponds to the prepayment line.

Step 3: Cancel Purchase Invoice

Consider that ABCD Technologies has canceled the entry of the above purchase invoice. In this case, the taxpartner service for Global Document Update interface is called with the following information:

Attribute Value

Document Type Identifier 1 (Purchase Invoice)

Transaction Identifier Purchase invoice transaction id for Invoice # 1001

Docu ment Level Action CANCEL

Example 3 Importing Sales Invoice

The Step 1 in following diagram shows the tax event for importing Sales Invoice. Please notice that Step 3does not have any end user intervention; it is an indirect result of the user action taken in Step 2 and theposting of transaction with accounting.


STEP 1: Import Sales Invoice with Tax Tax Calculation Interface is invoked with the followingdocument type, document level action and line level action:

Attribute Value



Line Level Action CREATE_WITH_TAX for invoice lines that have imported tax lines,LINE_INFO_TAX_ONLY for dummy invoice lines that have tax only lines,and CREATE for invoice lines that need tax calculation

Please note that imported tax lines are passed to the tax partner service for this tax event.

STEP 2: Update Header Level Information on Sales Invoice - Tax Calculation Interface is invoked withthe following document type, document level action and line level action:

Attribute Value


Document Level Action UPDATE

Line Level Action UPDATE (for all invoice lines)

STEP 3: Tax Override on Sales Invoice by E-Business Suite Process Tax Synchronization Interface isinvoked with the following document type and document level action:


28/76


Attribute Value


Document Level Action SYNCHRONIZE_TAX_LINES

The following two points hold good for this tax event:

Invoice header and overridden tax lines information is passed to the tax partner service.

No invoice line is passed to the tax partner service.

STEP 4: Update Header Level Reporting Attribute on Sales Invoice Tax Synchronization Interface isinvoked with the following document type and document level action:

Attribute Value


Document Level Action SYNCHRONIZE_HEADER_ONLY

STEP 5: Update Line Level Reporting Attribute(s) on Sales Invoice Tax Synchronization Interface isinvoked with the following information:

Attribute Value


Document Level Action SYNCHRONIZE_TRX_LINES

Step 1: Import Sales Invoice with Tax

A transaction can be imported through an open interface/import process of an E-Business Suite application.The imported transaction may also have tax lines associated with its transaction lines. For further illustrationof this scenario, consider a sales transaction for the customer, ABCD Technologies, who buys 1 monitorpriced at $100.00, 1 hard drive priced at $50.00, and one keyboard priced at $20.00 from XYZ Corporation.Assume that the sales invoice created for this transaction is being imported into the XYZ Corporations E-Business Suite, along with tax lines determined by an external system. Following diagram shows theimported sales invoice information that is passed to the tax partner calculation service.


29/76


The tax partner service is expected to synchronize the partner repository with the input tax lines and not re-calculate taxes that are imported. The partner service should not return imported tax lines back to E-BusinessSuite. However, it may determine the missing taxes on the transaction lines and return them to E-BusinessSuite.

Though not shown in this example, it is possible to have some imported transaction lines for which the taxpartner service is expected to calculate taxes. These transaction lines carry the line level action asCREATE.

Step 2: Update Header Level Information on Sales Invoice

E-Business Suite does allow users to update transaction after importing. Let us assume that the address in thetransaction header is updated to be in Las Vegas, NV instead of Redwood City, CA. Following diagramshows the updated invoice information sent to the tax partner calculation service.


30/76


Please note that normally E-Business Suite sends only updated transaction lines to the tax partner for re-calculation. In case there is an update on a header level attribute, the E-Business Suite considers it as anupdate for all transaction lines. Hence, in the above example, though there is no update on invoice lines 1, 2and 3, they are all sent to the tax partner with line level action as UPDATE, because there is update onheader level address attributes that may impact taxes on all transaction lines.

Following diagram shows the re-calculated tax lines as returned by the tax partner service:

Step 3: Tax Override on Sales Invoice by E-Business Suite Process

Let us assume that the invoice # Imp.1000 has been accounted before the user has updated it in the abovestep. In this case, since the tax lines for California jurisdictions have already been accounted, they cannot bephysically deleted. E-Business Suite retains the tax lines for California jurisdictions as canceled tax lineswith zero tax amounts. These lines are then passed to the tax partner synchronization service for recordingthem in the tax partner repository. Following diagram shows the complete invoice information as stored in E-

Business Suite. In this diagram, the tax lines sent to the tax partner for synchronization are highlighted.


31/76


If there is any subsequent update to this invoice that results in re-calculation, then the tax partners areexpected to retain the E-Business Suite overridden tax lines to maintain the data consistency with E-BusinessSuite.

Step 4: Update Header Level Reporting Attribute on Sales Invoice

Let us assume that the transaction number is changed from Imp.1000 to ABCD-1. This is a header level

change that does not require any tax calculation. Hence, E-Business Suite calls the tax partnersynchronization service and provides it with only header level synchronization information.

Step 5: Update Line Level Reporting Attribute(s) on Sales Invoice

Let us assume that the transaction line description for Line # 2 of invoice ABCD-1 has been updated from40 GB HD to 50 GB HD. In this case, there is no tax calculation required. Hence, E-Business Suite callsthe tax partner synchronization service and provides it with both header level and line level synchronizationinformation for Line # 2.

Please note that if the user updates the transaction number as well as the line description at the same time,then there is only one call made to the tax partner synchronization service. But as shown in this example,


32/76


these updates can happen at different points in time, in which case, there would be two calls to the taxpartner synchronization service.


33/76


Oracle E-Business Suite Tax Interfaces

This section describes the open tax interfaces of E-Business Suite needed by tax partners for integrating withE-Business Suite.

Tax Calculation Interface

Tax Synchronization Interface

Global Document Update Interface

Commit for Tax

Commit for Tax interface is to notify the Tax Partners to commit the transaction(s) in their system. All taxpartners are not required to provide this optional tax interface. This is to be used only by those tax partners thatare in the process of writing their tax services using Application Servers (middle-tier).

Before getting into the details of each tax interface, let us look at some common features of all these interfaces.

The parameters of these tax interfaces cover a comprehensive list of attributes needed for all businessscenarios. Some attributes may not be relevant for a particular business flow.

Returning Errors to E-Business Suite Tax Interfaces

The errors encountered during the processing of a tax partner service should be returned using a PL/SQLCollection of type messages_tbl_type. Please refer Appendix A for a detailed description of the data typemessages_tbl_type.

Each error should be returned for one of the following three contexts:

Transaction Header

Transaction Line

Tax Line

Also, each error should be associated with one of the following error message types. The error message typerepresents whether the message gives error or information.

Error Message Type Description

ERROR Represents that it is an error message

INFORMATION Represents that it is an informative message

For example, based on the address information passed to a tax partner API, if the API does not result in aunique tax jurisdiction, the partner may return the higher tax rate, along with the INFORMATION messageabout it. This message would be logged and a corrective action can be taken by the user to pass moreaccurate information subsequently.


34/76


Tax Calculation

As the name indicates, this interface is used to calculate and re-calculate transaction taxes for manuallyentered and imported transactions. This interface is also used for importing transactions for which the taxesare already calculated by an external system and needs to be recorded substantially as is in the Tax Partner

Repository. In this case, the tax partner may still calculate taxes, and come up with any missing or additionaltaxes.

The transaction specific inputs for this tax interface are available through ZX_O2C_CALC_TXN_INPUT_Vand ZX_P2P_CALC_TXN_INPUT_V views. ZX_O2C_CALC_TXN_INPUT_V view provides both headerand line level attributes for Order-To-Cash transactions, where as ZX_P2P_CALC_TXN_INPUT_V viewprovides both header and line level attributes for Procure-To-Pay transactions. E-Business Suite sets a globalvariable, namely ZX_PARTNER_PKG.G_BUSINESS_FLOW, to inform the tax partners about the businessflow. The possible values for this global variable are O2C (Order-To-Cash) and P2P (Procure-to-Pay).

Following transaction attributes are always passed to the tax partner irrespective of the business flow.

Header Level

internal_organization_id

document_type_id

transaction_id

business_flow

document_level_action

trx_date

legal_entity_number

Line Level

transaction_line_id

line_level_action

trx_level_type

transaction_line_date

trx_line_currency_code

line_amount

trx_business_category

For import scenarios, the imported tax line inputs for Tax Calculation interface are available throughZX_IMPORT_TAX_LINES_INPUT_V view.

For the description of the columns for the above-mentioned views, please refer Appendix A.

Document Level and Line Level Actions

The valid document level actions for this interface are CREATE, UPDATE and QUOTE. When calledfor document level action UPDATE, each transaction line has a line level action to indicate the action takenfor that particular line e.g. changed lines are passed with line level action 'UPDATE', whereas newly addedlines are passed with the line level action CREATE. Lines, which have not changed since the last call to


35/76


calculate taxes for a transaction, are not be passed in the subsequent call for re-calculation. However, if anyof the header level attributes change, all existing transaction lines are passed.

Possible values for line level action attribute are listed in the following table:

Document Level

Action

Line Level Action Possible business scenarios

for the line level action

Expected behavior in the

partner system

CREATE Newly created transaction line Calculate taxes for the transactionline; Record the transaction lineand tax information in therepository.

CREATE_WITH_TAX Imported transaction line withtaxes

Record associated imported taxlines as is. Optionally determineadditional tax lines.

QUOTE Requesting a tax estimate for aspecific transaction line

Calculate taxes for the transactionline; Do NOT record thetransaction line and taxinformation in the repository. A

tax calculation call may have sometransaction lines with Quote linelevel action while some other lineswith other line level actions.

RECORD_WITH_NO_TAX Oracle Receivables allowscredit for transaction linesonly withoutcalculating/impacting the tax.

Do not calculate taxes on thetransaction line; Only record thetransaction line information in therepository.

APPLY_FROM A transaction line of anotherdocument type that is beingapplied to the currenttransaction e.g. a pre-paymentline applied to a payablesinvoice.

Calculate taxes on the amountapplied of the pre-payment line.

CREATE

LINE_INFO_TAX_ONLY A dummy transaction line witha tax only line

Store dummy transaction line as iswithout tax calculation. If a taxline is also sent then record taxline too. For manually enteredinvoices a tax line would not beavailable during tax calculationcall. Tax line would later besynchronized with the partnersystem.

CREATE Addition of new line in theexisting transaction

Calculate taxes for the newlyadded transaction line; Record thetransaction line and taxinformation in the repository.

UPDATE Modifications on thetransaction header or line levelattributes that have taximplications

Recalculate taxes for the changedtransaction lines; Record thetransaction lines and taxinformation in the repository.

CANCEL Cancellation of a transactionline

Cancel the transaction line. Recordchanges to the line amount, if any.

DELETE Deletion of a transaction line Physically delete the transactionline from the repository.

UPDATE

QUOTE Requesting a tax estimate for aspecific transaction line

Calculate taxes for the transactionline; Do NOT record thetransaction line and taxinformation in the repository.


36/76


SYNCHRONIZE Modifications to reporting onlyattributes of a transaction line,which does not require tax re-calculation

Do not recalculate taxes on thechanged transaction line; Recordthe changes to transaction lineinformation in the repository. Donot update the tax information inthe repository.

APPLY_FROM A transaction line of anotherdocument type is being appliedto the current transaction e.g. apre-payment line applied to apayables invoice.

Calculate taxes on the amountapplied of the pre-payment line.

UNAPPLY_FROM A transaction line of anotherdocument type is being un-applied from the currenttransaction e.g. a pre-paymentline un-applied from a payablesinvoice.

Negate the results of theAPPLY_FROM line level actionon the transaction.

LINE_INFO_TAX_ONLY A dummy transaction line witha tax only line

Store dummy transaction line as iswithout tax calculation. If a taxline is also sent then record taxline too. For manually entered

invoices a tax line would not beavailable during tax calculationcall. Tax line would later besynchronized with the partnersystem.

QUOTE Requesting a tax estimate forthe entire transaction

Calculate taxes for the transactionline; DO NOT record thetransaction line and taxinformation in the repository.

QUOTE APPLY_FROM A transaction line of anotherdocument type that is beingapplied to the currenttransaction e.g. a pre-paymentline applied to a payables

invoice.

Calculate taxes on pre-paymentline or retrieve the taxes from thepre-payment transaction.

Tax Estimate Request

This interface supports requests to get tax estimate for a transaction or a specific transaction line. The requestfor tax estimate for the entire transaction is represented by the document level action QUOTE. In this case,the tax partners are not expected to store calculated tax lines in their repository. A quote request can be mademore than once for the same transaction. E-Business Suite passes all the transaction lines, each time a taxestimate is requested for a transaction.

Allow Tax Calculation

E-Business Suite allows an option to the user to enable/disable Tax Calculation in certain products. In thiscase, user can enter tax lines manually and the tax partners are not expected to calculate tax. The request toskip the tax calculation is represented by the attribute Allow Tax Calculation Flag.

Rounding

E-Business Suite maintains transactions in multiple reporting currencies. It uses un-rounded tax amounts forconverting to reporting currencies. Hence, tax partners are expected to return both the rounded and un-rounded tax amounts for the transaction currency. If a tax partner is unable to return un-rounded tax amount,it must return the rounded tax amount in both the attributes.


37/76


E-Business Suite processes may also attempt to perform rounding for the already rounded tax amountsreturned by the tax partners. To avoid any mismatches between the tax amounts between tax partners and E-Business Suite, the mutual customers are advised to have the same or higher rounding precision setup in E-Business Suite. If the tax partners rounding setup has a higher rounding precision, E-Business Suite raisesan error.

Use Tax Vs Sales Tax Determination in US

For US, tax partners can indicate whether they have determined Use Tax or Sales Tax by setting the attributeUse Tax Flag to Y or N respectively, on the tax lines.

End users are not allowed to override the value of this flag. For example, if the end user intends to changeSales Tax to Use Tax, he is not allowed to do so. Instead, he can delete the Sales Tax tax line andenter a new Use Tax tax line.

E-Business Suite tax calculation interface does not call different tax partner services for Use Tax

determination and Sales Tax determination in US. If the tax partners have different tax services available,then they are expected to write a wrapper with appropriate logic to call their two different services. Thiswrapper service can then be integrated with E-Business Suite tax calculation interface.

Max Tax Handling

Tax Partners may support max tax or threshold based tax at both transaction header and line levels. If aheader level max tax is incurred on a transaction, the tax partner service is expected to communicate it backto E-Business Suite by setting the attribute threshold indicator flag to Y for all tax lines. Though, all thetax lines may not be subjected to the header level max tax, E-Business Suite still requires all tax lines of thetransaction to have threshold indicator flag set to Y. An example of max tax is in the state of Florida,

where only the first $5,000 of a single sale of tangible personal property is subject to the county discretionarysales surtax.

Any modifications to one or more lines of the transaction, carrying header level max tax, may result inchanges to the taxes of all transaction lines. For such cases, even though E-Business Suite does not pass alltransaction lines, E-Business Suite does handle the return of tax lines belonging to the entire transaction, ifand only if the tax partner service sets threshold indicator flag to Y.

Exemptions and Exceptions Handling

All exemptions or exceptions must be setup within tax partner system for tax calculations. However, E-

Business Suite does allow its users to enter exemption information such as exemption certificate number andexemption reason on a transaction line if the user wants to enforce a specific exemption certificate. Oracleusers refer to this feature as on-the-fly exemptions. Users can enter the exemption certificate number orselect it on the transaction lines using a List of Values. In order to get the List of Values, the exemptionsmust also be defined in Oracle E-Business Suite.

Tax partners can perform validation of the exemption certificate number, check existence and/or create anew exemption to handle on-the-fly scenario.

Additionally, tax partners APIs are passed with another attribute (flag) called exemption_control_flag witheach transaction line. Following table shows the possible values of this flag and the expectation of the user

for choosing one of those values on the transaction line.


38/76


39/76


Parameter Usage Data Type Description

Currencies Table IN OUT zx_tax_partner_pkg.tax_currencies_tbl_type

PL/SQL Collection for passing exchange rate information fortax and transaction currencies to the tax partner. This is alsoused for receiving the precision for transaction and taxcurrencies returned by the tax partners tax calculation service.

This is the precision used by the tax partner for rounding thetax amounts in transaction and tax currencies.

This table contains one record each for the tax and transactioncurrencies if they are different.

Resultant Tax Lines OUT zx_tax_partner_pkg.tax_lines_tbl_typePL/SQL Collection for returning tax lines determined by thetax partner service

Error Status OUT VARCHAR2

Represents whether call to tax partner service is successfullyexecuted or not. Possible Values are:

Success S

Error - E

Unexpected error - U

Error / DebugMessages

OUT zx_tax_partner_pkg.messages_tbl_type PL/SQL Collection for returning error and/or debug messages

For a detailed description ofzx_tax_partner_pkg.tax_currencies_tbl_type,zx_tax_partner_pkg.tax_lines_tbl_type, and zx_tax_partner_pkg.messages_tbl_type data types, please referto Appendix A.

Tax Synchronization

As the name indicates, this interface is used to synchronize transaction or tax related attributes with the taxpartner repository. This interface is used to update information in the tax partner repository for transactionattributes that do not influence tax calculation, but are used in tax reports. Another use of this interface is to

synchronize the tax partner repository for the tax line overrides made by the end user or E-Business Suiteprocesses.

Tax partner can return the effective tax rate and/or taxable basis for the overridden tax lines during tax linessynchronization. However, tax partners are not expected to return any output information for synchronizationof transaction attributes.

The transaction specific synchronization inputs for this tax interface are available throughZX_SYNC_HDR_INPUT_V and ZX_SYNC_LINES_INPUT_V views. The tax line specificsynchronization inputs for this tax interface are available through ZX_SYNC_TAX_LINES_INPUT_Vview.

For the description of the columns for the above-mentioned views, please refer Appendix A.

Document Level Actions

The valid document level actions for this interface are listed below:

Document Level Action Possible business scenarios for the

document level action

Expected behavior in the tax partner

system

SYNCHRONIZE_HEADER_ONLY Modifications to reporting only attributesof a transaction header only, which doesnot require tax re-calculation

Do not recalculate taxes on the changedtransaction; Record the changes totransaction header information in the


40/76


repository. Do not update the taxinformation in the repository.

SYNCHRONIZE_TRX_LINES Modifications to reporting only attributesof a transaction line, which does notrequire tax re-calculation.

Do not recalculate taxes on the changedtransaction; Record the changes totransaction line information in therepository. Record the changes totransaction header information, if available.Do not update the tax information in therepository.

SYNCHRONIZE_TAX_LINES End user or E-Business Suite overrides totax lines.

For tax only invoices tax linesinformation is passed forsynchronization.

Do not recalculate taxes for the transaction;Record the changes to tax line informationin the repository; Optionally determineeffective tax rate and/or effective taxablebasis for the changed tax lines.

The line level action attribute is not explicitly provided for this tax interface. It should always be implicitlytaken as SYNCHRONIZE for this tax interface.

Transaction Header and Line Level Synchronization Attributes

There are some reporting only transaction header or line attributes that can undergo changes after the taxcalculation. Such changes do not require re-calculation of taxes and should only be synchronized with the taxpartner repository. For example, in some E-Business Suite applications, to satisfy some legal requirements,the transaction number is assigned at the time of approving / finalizing an invoice. When such an eventoccurs to modify the transaction number, tax partner need to be called to synchronize their repositories.

Following are the reporting-only attributes available at the transaction header level:

Transaction Number

Transaction Description Document Sequence Value

Transaction Due Date

Following are the reporting-only attributes available at the transaction line level:

Transaction Line Description

Product Description

Please note that in addition to these reporting attributes, a tax partner may also use other additional attributesfor reporting purposes.

Handling Tax Line Overrides by End Users

The end user may decide to correct the taxes returned by the tax partner service as they may be incorrect dueto inadequate setup. E-Business Suite stores user overridden tax amounts and then communicates them to thetax partner in order to keep the tax partner repository in synchronization with E-Business Suite.

The end user is allowed to update the tax rate percentage or tax amount on calculated tax lines. The user candelete or cancel an existing tax line too. The user can also enter a manual tax line, which may or may not beassociated with a transaction line. Tax lines that are not associated with any transaction lines are referred toas tax only lines and are represented by setting Tax Only Line Flag attribute to Y on the tax line.


41/76


The onus is left on the tax partner to decide an appropriate behavior for handling user overridden taxamounts during re-calculation of taxes. For example, if there is any subsequent transaction header or lineupdate to an already tax overridden transaction, then the tax partner may choose to ignore any prior end usertax overrides or he/she may decide to honor them during re-calculation of taxes. Please note that some E-Business Suite applications may invoke tax recalculation though nothing has changed on the transaction line.

Any tax amount change by the tax partner in such situations may not be acceptable to the end users.

Handling Tax Line Overrides by E-Business Suite Processes

Certain business functionality may require E-Business Suite to modify the taxes returned by tax partners. Forexample, if tax lines are already accounted, E-Business Suite retains old tax lines with zero tax amounts, ifthey are no longer valid for a transaction line. Such tax lines are to be synchronized with the tax partnerrepository.

If there is any subsequent update to an E-Business Suite overridden transaction, which results in re-calculation, then the tax partners are expected to retain the E-Business Suite overridden tax lines to maintain

the data consistency with E-Business Suite.

Please refer to Step 2 and Step 3 of Example 3 in Example Scenarios Illustrating E-Business Suite TaxInterfaces section.

Tax Only Invoices

A tax only invoice comprises of tax only lines. There is a dummy item (transaction) line present for such aninvoice. For imported transactions, the dummy transaction line with the line level action asLINE_INFO_TAX_ONLY is passed and the associated tax only line is also passed during tax calculationinterface invocation. For manually entered transactions, first a dummy transaction line with the line level

action as LINE_INFO_TAX_ONLY is passed during tax calculation interface. A tax partner is expected tosimply store the dummy transaction line at this time. Later, another call is made using tax synchronizationinterface to store the tax only line associated with the dummy transaction line in the tax partners repository.Oracle passes the most granular information such as state tax, county tax, city tax, district tax that do notrequire further distributions by the tax partner.

Technical Specification

For this interface, tax partners are expected to supply a tax synchronization service whose specification isexpected to have the list of parameters with the same order, usage and data type as listed below:


ResultantSynchronized TaxLines

OUT zx_tax_partner_pkg.output_sync_tax_lines_tbl_type

PL/SQL Collection for returning all synchronized taxlines for which the tax partner service has updatedeffective tax rate and/or taxable basis.

This parameter is expected to be NULL ifsynchronization is for transaction attributes only.


Represents whether call to tax partner service issuccessfully executed or not. Possible Values are:

Success S

Error - E

Unexpected error - U

Error / DebugMessages OUT zx_tax_partner_pkg.messages_tbl_type PL/SQL Collection for returning error and/or debugmessages


42/76


For a detailed description ofzx_tax_partner_pkg.output_sync_tax_lines_tbl_type andzx_tax_partner_pkg.messages_tbl_type data types, please refer to Appendix A.

Global Document Update

This tax interface is provided for the tax events that are the same for all transaction lines, i.e. the tax eventsthat are at the document level and do not differ at the line level. Valid document level actions for this taxinterface are listed below:

Document Level Action Possible business scenarios for the

document level action

Expected behavior in the tax partner

system

CANCEL Informs about cancellation of atransaction, while keeping a persistentrecord of it.

Mark corresponding tax lines as canceled

DELETE Informs about del etion of a transaction,without keeping a persistent record

Physically delete the corresponding tax linesfrom the repository.

PURGE Informs about purge of a transactionfrom E-Business Suite

Purge all tax lines for the transactionPurge is normally invoked to clean uphistorical transactions from the customersinstallation, where as Delete is used for theday to day transactions that can potentiallybe deleted before reaching a final state likeapproval.

FREEZE_FOR_TAX Indicates to the tax partner that thedocument is ready for tax reporting

Mark the transaction as ready to report to thetax authorities

UNFREEZE_FOR_TAX Indicates to the tax partner that a frozentransaction needs to be updated

If the transaction is not yet reported, thenmark it as not ready to report to the taxauthorities. If it is already reported, thenreturn an error to indicate that the unfreezeprocess is not successful.

Technical Specification

For this interface, tax partners are expected to supply a tax service whose specification is expected to havethe list of parameters with the same order, usage and data type as listed below:


Transaction Record IN zx_tax_partner_pkg.trx_rec_type Identifies transaction and the document level action
