TaxabilityTax determination is based on several factors, which include the following: Product Taxability: The type of product being transacted. Non-Inventory Items: The use of the product (non-inventory) can determine taxability. Exempt Management: Products, customers, and specific transactions that can be exempt.
Product TaxabilityDescriptionFor proper taxation, the tax engine needs the kind of product being sold, e.g., milk products might be taxed differently than automotiveproducts. Instead of mapping each item from a transaction system in the tax system to its product taxability, it is common to categorize items intoproduct tax categories, such as commodity code or product code. In addition to product tax categories, other tax factors such as exemptionmanagement need to be identified.Business UsageThe product tax category represents the tax treatment of a group of items or materials in the financial system. The tax category is mapped to aproduct (item/SKU) and is usually stored in the item's master record. The category is not changeable during the transaction process, whichincludes placing an order and issuing an invoice. The product tax category can be sourced from the financials system (ERP) by: 1. Commodity code (if available) and maintained in the source system. See Commodity Code. 2. Another ERP field on the item master that categorizes products. This requires customers to manually do the mapping of the ERP values in Determination to a Product Category using Product Mappings. See Other Standard ERP Field. 3. Adding a new ERP field for maintaining a product code. See Add New Field. Preference is to use a four-digit field that then can hold a Thomson Reuters predefined Product Code. These Product Codes are pre-mapped in Determination during onboarding and simplifies maintenance. See Product Tax Code. Use any other field length and value to hold a customer's own code. This requires customers to manually do the mapping in Determination. See Other Standard ERP Field.In addition to a product tax category, taxability is also determined by exemption management. Items, customers, transactions can be exempt fromtax. Alternatively, normally exempt transactions can be taxable. The transaction needs to be flagged in the XML request indicating the change inexempt status. See Exempt Management.Tax UsageTransactions processed by ONESOURCE Indirect Tax Determination include a product tax category, either a product code or commodity code,associated with a product. ONESOURCE Indirect Tax Determination uses this transaction data to drive rule selection, select exemptioncertificates, or fully exempt the product according to your configuration.
Commodity CodeDescriptionThe commodity code is a standard way to group items using an adopted standard such as a Harmonized Commodity Description and CodingSystem (Harmonized System) or a United Nations Standard Products and Services Code (UNSPSC). Each code designates a specific good witha unique number. Commodity codes provide a universal nomenclature for describing commodities, Companies use commodity codes as itsimplifies documentation of international trade, helps monitor controlled products, identifies goods for tax purposes, and supports price and quotaregulations on exports and imports.The commodity code can be passed to Determination to identify kinds of products being sold.More information on commodity codes can be found on the following sites: The Thomson Reuters International Tax Research page displays the maintained list of International Taxability Matrices. Harmonized System Code - http://www.wcoomd.org/en/topics/nomenclature/overview/what-is-the-harmonized-system.aspx UNSPSC code -https://www.unspsc.org/Business UsageThe commodity code can be maintained on the item master in the financial system.For the Enterprise Web Service, the commodity code value is passed in the <COMMODITY_CODE> element.The <COMMODITY_CODE> element is not available in the Simple Web Service. As a work-around, the value can be mapped and passed in auser attribute. A TransEditor is then created in Determination to use this user attribute as a commodity code. For more information on userattributes and TransEditors, see User Attribute Container or contact the implementation consultant.Alternatively, the Product Tax Code functionality can be used to determine item taxability.If both Product Tax Code and commodity code are passed in the Enterprise Web Service to Determination, the commodity code takesprecedence.Tax UsageDetermination uses this transaction data to drive rule selection, qualify exemption certificates, or fully exempt the product according to yourconfiguration.
Other Standard ERP FieldDescriptionSome transaction systems may not have a commodity code field or another specific field to hold a product code value. Implementers can selectany other field in the transaction system that represents a grouping of products that can be matched to product taxability in Determination.Business UsageFor proper product taxability, items need to be grouped. Many transaction systems have specific fields to group items for inventory management,planning, or other material management purposes. When there is an existing field available in the transaction system, the value of that field canbe used to drive product taxability. These customer-specific values need to be mapped to the ONESOURCE product taxability matrix. If a customfield is used, the value is sent to Determination in the <ProdcutCode> field.Tax UsageProduct taxability drives proper taxation. ONESOURCE has a mapping function that allows custom field values to be mapped to the properproduct taxability group. During the onboarding process, the ONESOURCE professional services team will work with customers to determinewhich product groups are utilized and how to map their custom field values to the proper group. See Product Tax Code section for details on thisprocess.
Add New FieldDescriptionSome transaction systems do not have a commodity code, Product Tax Code, or another standard product grouping. In these cases, a newcustom field can be created in the transaction system at the item master level to categorize items into product groups for taxability.Business UsageWhen adding a new field we recommend the use of the Thomson Reuters 4-character Product Tax Code. This simplifies implementation, as thereis no mapping needed in Determination. If a custom field or another standard ERP field is used, tax engine mapping is required, in that case, seeOther Standard ERP Field.Tax UsageThe custom field is used in the tax calculation to determine the proper product taxability.Technical design and setupThe following is the recommended approach to adding the custom field: 1. Add new list of value table It is recommended to add a custom table that holds the product tax code (4-character code) and a description of the code. This allows for easy selection of the proper product tax code. 2. Add field to item master This should be done in a manner that is supported by the system vendor by either adding a field to an existing table, using a shadow table linked to the original table or other design means. Upgradability and supportability should be taken into consideration when adding the field to the existing item master. 3. Expose field on item Once the field has been added to the table it should be made visible for a user to enter a value into the field. Use of the value table is desired to assist with data entry. Depending on system design it is also recommended to assign a special user role/permission for this task so that only authorized users can maintain this value. 4. Form to do mass maintenance It is highly recommended that you also build a form or screen that allows mass maintenance of item to product code assignments as well as a mass upload at the time of original implementation. See Product Tax Code Import.
Product Tax Code This section on applies to United States transactions.DescriptionThomson Reuters Product Tax Codes represent the tax treatment of a group of similar items or materials in the financials system using a 4-digitcode.Business UsageProduct codes are mapped to products (items/SKUs). They are usually stored on the master record of the item and cannot be changed during thetransaction process (order/invoice, etc.). Thomson Reuters provides a list of preset 4-character product codes/50 character product codedescription for customers to select from. Of the over 4,000 product codes provided, most customers only use a subset that is relevant to theirindustry. Product codes can be assigned to products (items, SKUs), sales categories, and/or miscellaneous charges. For cases where a productcode is not defined on the item and cannot be derived, it is a good design concept to have a default product code in ONESOUCE Indirect Taxconfiguration screen. Although this field is not required, the Product Code value does aid in tax calculation.The Product Code value is passed in the <ProductCode> element using either the tax calculation service or the simple tax service.Tax UsageTransactions processed by ONESOURCE Indirect Tax Determination include a product tax category, either a product code or commodity code,associated with a product. ONESOURCE Indirect Tax Determination uses this transaction data to drive rule selection, select exemptioncertificates or fully exempt the product according to your configuration.Consider the business process of entering an item number on a document line. The basic tax request includes the Product Code associated withthe item number on these documents. Product Codes can also be associated with charges, such as freight or insurance, that may also beincluded on a transaction line. This information is passed with the tax request for tax determination.<Attributes><IsCredit>false</IsCredit><IsExempt>false</IsExempt><PointOfTitleTransfer>Origin</PointOfTitleTransfer><ProductCode>GC66</ProductCode><PartNumber>SLH Part Number 001</PartNumber><PartDescription>SLH Part Description 001</PartDescription>ProcessDuring the onboarding process, Items will be reviewed with a taxability expert and they will be mapped to the appropriate product tax code usingthe Thomson Reuters Product Guide available on the Software Support Network. For 2016 you can find the source in Knowledge Base article 1428, US 2016 Product Guide.pdf. Each year a new Knowledge Base article will be created with a new yearly Product Guide attached.
Product Tax Code ImportDescriptionIdeally, the use of an automated method to load the ONESOUCE Indirect Tax Product Codes into the ERP is preferred.Business UsageIt is desired to have the ability to load this data using a provided .csv file by command line, database script, or similar method. For datamaintenance, a user interface accessed through a menu option should be provided to allow the addition of new product codes and descriptions asneeded. Prior to the deletion of a product code, a check should be made to ensure that no items are mapped to that product code. If an itemmapping is found, an error should be raised and deletion should not be allowed.Tax UsageDetermination uses this transaction data to drive rule selection, qualify exemption certificates, or fully exempt items based on your configuration.Item Extract/Product Code Import EnhancementImporting product codes is a two-step process, first an item extract and then the product code import. The first step extracts item information fromthe ERP into a .csv file. The second step imports the same file back into the ERP, with an additional column added for the product codes.Item ExtractThe item extract is a process, run either at the system command line level, by SQL script, or through a system menu that creates a CSV file withminimal item data. The resulting CSV file will Identify items uniquely; usually by item number/ID, item description, item class and/or item category Provide organizational data if items are stored organizationally within the source system Provide additional fields related to items that could assist in identifying their taxability such as classifications, inventory planning, material groupings, sales categories, MRP/forecasting attributes, allocations, etc.The following is an example of the type of information that is contained in an item extract. This is sample data only, your ERP definitions and fieldsmight be different.Item Item Description Class ID Item Short Generic Planning TypeNumber Description Description Type1-A3261A Multi-Core SERVERS-1 Sales Processor Servers Manufacturing Processor InventoryProduct Code ImportOnce all items in the item extract file are mapped to a product code a mass upload process is required to import that information back into thetransaction system. This process is either initiated at the command line level or via a menu item. The process can use the .csv file generatedduring the extract process, but with an additional column added for the Product Code. The following is an example:Item Item Description Class ID Item Short Generic Planning TypeNumber Description Description Type1-A3261A Multi-Core SERVERS-1 Sales Processor Servers Manufacturing Processor InventoryBest practice is to implement a check against the list of values table to check if a product code to be assigned to an item is in that table or not. Ifthe product code doesn't exist, the record should not be updated and a message should be written to an error log.Alternate Processes
After a mass update assigning a product code to all the currently existing items, a client will assign a product code during the creation/change of anew/existing item. Alternatively, a client could use a commodity code instead of a product code if the commodity code is available in thetransaction system. Commodity codes do not require a mapping in the tax engine and therefore, their use can greatly simplify setup andmaintenance.Additional InformationThomson Reuters will provide the CSV templates to clients. We also provide processes, tools, and resources to assist in product code mappingduring the new client onboarding process.
Non-Inventory ItemsDescriptionSome financial systems do not provide an easy way to assign product tax codes to non-inventory items. An alternative method to determineline-item taxability is to map the general ledger account or cost center element on non-inventory items. Product tax codes can still be used, if theycan be assigned in the financial system.Business UsageThe general ledger account segment or the cost center on the transaction can be used to derive taxability for non-inventory items. The generalledger account can identify the type of product purchased; office supplies or maintenance supplies, etc. The cost center can identify where thegoods are consumed; R&D, IT, etc.Tax UsageThis alternative can be used in buyer transactions for product qualification in complex tax scenarios. The general ledger account or cost centerelement of non-inventory items is mapped to determine line-item taxability. Rules are defined in Determination to identify taxation. For example: Define a general ledger account based rule. If the general ledger account is 401300, then treat the line as office supplies; if the general ledger account is 402400, then treat the line as maintenance supplies. Define a Cost center element rule. If a laptop is purchased and the cost center is R&D then treat the line as exempt. If the cost center for the laptop purchase is IT, then the line is taxable.To utilize the general ledger account option, send the account in the XML element <GlAccount>. To utilize the cost center option, send the costcenter value in the XML element <CostCenter>.
Exempt ManagementDescriptionThe basic assumption of a tax calculation is that everything is taxable. However in some cases, taxes do not need to be assessed. In thesecases, an exemption is applied.Business UsageThe recommended process to apply an exemption is to setup an exemption certificate in the Determination. At the time of a tax transactionDetermination will look at the SOAP request customer number or customer name and if an exemption is defined, that exemption will be appliedand tax will not be calculated. This process is not driven by the transaction system, it is entirely based on transaction data and tax policy setup inDetermination. There are two sub-processes to exemptions: Exempt a transaction: A transaction needs to be exempted but an exemption certificate is not setup in Determination. Therefore, the exemption needs to be forced. This can happen when a new customer relationship is built but the customer has not yet provided the certificate, hence one is not setup in Determination. In this case, the transaction header (document level) or line needs to indicate that the transaction should not be taxed. In these cases, the standard Tax Code of IDT (see Product Taxability) would be overridden with IDT_EXEMPT indicating that the SOAP XML element IsExempt needs to be set to “true”. Tax an exempt customer: A transaction needs to override an existing exemption certificate in Determination. This can happen if for this one transaction the exemption is not applicable, e.g. a reseller exemption certificate is setup in Determination, but a specific order is not for resale, it is for the customer's own consumption. In these cases the standard Tax Code of IDT (see Product Taxability) would be overridden with IDT_OVERRIDE indicating that the SOAP XML element IsExempt needs to be set to “false”.Tax UsageDuring returns processing for transactions where a certificate was applied, the exemptions are grouped by the ExemptReason code. They arethen applied to the returns form box based on the requirements of the filling authorities. Any exempt transactions without a reason code arereported in the \"Other Exemptions\" category.Customer exemption certificates and exemption processing can be managed in the following ways when integrating with ONESOURCE: The recommended method is to use the ONESOURCE Portal to manage all customer exemptions. This method provides you the ability to define exemptions by state and maintain effective and expiration dates. The alternative method is within the financials system, typically on the customer/vendor master. Managing exemptions in this way typically does not provide you with the level of detail that may be required for calculation and reporting purposes.ONESOURCE Managed ExemptionsCustomer exemptions and exempt reasons can be maintained in ONESOURCE Indirect Tax Determination. When a tax call is made toDetermination and the exempt field is set to blank, the exemption for the transaction is determined by customer and exemption data stored withinDetermination. Exemptions can be defined at different levels: Exemptions can be defined for all states or only for the state(s) where a specific exemption applies. Exemptions are maintained with effective dates. Expired exemptions will automatically start generating the applicable tax. Exemptions are managed using Determination and can be overwritten if a specific transaction needs to be taxable for a normally exempt customer. Existing customer exemptions can be uploaded by batch to Determination prior to going live as part of the onboarding process.PrerequisiteIf the financial system allows for customers, vendors, or materials to be set to not tax relevant or exempt they will need to be set to taxable.Exempt FieldThe value of the IsExempt field determines how Determination evaluates exemptions.IsExempt ResultValuetrue Forces a document to be exempt; overrides Determination exemption management (treats a transaction as exempt even if there is no certificate defined)false Forces a document to be taxed; overrides Determination exemption management (ignores an existing certificate)<blank> Determination exemption management determines exemption (default behavior)
Exempt ReasonsIf a line item is exempt (IsExempt = true), the ExemptReason field should be set to explain why an exemption was forced by the financialsystem. The exempt reason code is used to report the exemptions by reason on the tax return. The IsExempt field can be sent without an ExemptReason code. In this case, Determination will use the default exempt reason code of '99 - Other'. It is recommended to send the accurate ExemptReason as an amount with a '99-Other' code is an audit risk and could lead to an audit for customers. The valid exempt reasons currentlyavailable are listed below:Code Exempt Reason05 Sales for Resale10 Sales in Interstate Commerce15 Non-taxable Food20 Sales to Government25 Exempt Industrial and Farm Machinery30 Non-taxable Labor or Service35 Prescription Drugs40 Returned Merchandise45 Bad Debts50 Gasoline (Motor fuel on which tax is paid)55 Direct Pay Permit60 Sales to Exempt Organizations (schools, hospitals, non-profit, churches, etc.)65 Food Stamps and WIC Sales70 Medical Equipment75 Broadcasting80 Enterprise Zone99 OtherFor the most current list of valid exempt reasons, refer to Knowledge Base Article 724.Exemption ExampleThe following is an example of an XML request for an exempt override:<IsExempt>true</IsExempt><ExemptReason>99</ExemptReason>Managing Exemptions in The Financials SystemThe alternative method for handling exemptions is to manage them within the financials system. Indicate on the customer master that a customer is exempt or taxable. If the customer is exempt, include the reason for the exemption when possible as the reason code is used during compliance processing. If a specific transaction should be taxable, override the customer exemption on that transaction.e-commerce SystemsWe won't expose the process of exempt overrides and/or force to e-commerce platforms. It is assumed that an e-commerce platform client wouldrequire a customer to provide an official exempt certificate upfront, which will be set up in Determination and then automatically applied totransactions when applicable. This follows common industry practices, for example, Amazon's approach.
RegistrationsDescriptionIn order to collect and report VAT (or VAT-like tax; Canada GST, PST, etc), a registration number is required. Currently, only The US and Canadaare in scope. In Canada, there are registration numbers for GST, HST, QST and PST.Business UsageA VAT registration number is an alphanumeric identifier, consisting of up to 15 characters, unique to a corporate entity doing business in acountry that implements a Value Added Tax system. As a general rule entities conducting business in a VAT country should be registered with thetax authority to collect tax. A registration can be issued for a company for all locations, or it can be location specific. In some jurisdictions, theregistration numbers are required to be printed on documents (i.e. invoices), so the data must be stored. There are specific registration numbermasks that apply to each jurisdiction.The Registration Masks in Determination.pdf document contains more information about supported registration masks listed by country.For current registration masks see the https://www.onesourceidtsupport.com/app/answers/detail/a_id/1116/kw/1116 article on the ONESOURCEsupport site.Tax UsageValue Added Tax is a consumption tax, meaning that it is borne by the end user; although any number of intermediaries may pay VAT on aproduct as it moves along its distribution pathway, these intermediaries claim the tax back as part of their accounting procedures. The only partythat cannot claim the tax back is the end user. In order to conduct business and collect and pay taxes, a registration number is required.Determination uses registration numbers to determine if tax should be calculated. If tax is to be calculated, the registration number is a componentin determining which tax applies.The Registration Number that is passed in the transaction will take precedence over anything in the database. The Registration in the indataserves as an override to the database.Integration UsageThe XML <Registrations> block contains information about the Buyer Registration and the Seller Registration, including country, type, and value.Currently, only The US and Canada are in scope, so only Canadian registrations apply at this time. To properly calculate tax for Canada, buyerand seller registration information is included as shown in the following example Indata XML:
<Registrations> <BuyerRegistrations> <Registration> <Country>CA</Country> <Type>Federal</Type> <Value>123456789RT</Value> </Registration> <Registration> <Country>CA</Country> <Type>Provincial</Type> <Value>R123456</Value> </Registration> </BuyerRegistrations> <SellerRegistrations> <Registration> <Country>CA</Country> <Type>Federal</Type> <Value>987654321RT</Value> </Registration> <Registration> <Country>CA</Country> <Type>Provincial</Type> <Value>R987654</Value> </Registration> </SellerRegistrations></Registrations> NOTE: Country and Registration Type (Federal or Provincial) are not used by Determination at this time. It will be used for future functionality. However, the simple request requires a value in the Country and Registration Type column. Passing a federal registration type for all registration numbers is acceptable.
Sales Tax Code Integration Level MethodsDescriptionDifferent tax level details can be returned to a transaction in the ERP system. Sales tax code integration level methods indicate the level of taxdetail to be displayed and stored in the ERP system.Business UsageThere are two different sales tax code integration level methods that can be implemented using the simple web request. Each method requires aset of specific tax codes to be loaded into the ERP system as part of the installation process of the integration. Both methods will be supported inthe integration, but each client will choose one method at the time of installation. An implementation method is chosen based on the level of taxdetail a client wants to see in the ERP; a separate bucket for state, county, city, and district or summarized by state (state, county, city and districtsummarized to the one state bucket). If further detail is needed for specific state, county, city, and districts then the client can access thisinformation in Determination.The following provides more information on each implementation method: 1. US Authority Level Implementation (Bucket): Creates separate buckets for state, county, city, and district taxes. This option has only four sales tax codes for the United States (state, county, city and district) and four for Canada. Tax details of the specific state, county, city or district (multiple districts are summed up) will not be in the ERP system. If further detail is needed for specific state, county, city and, districts, the client can access this information in Determination. This method is done the majority of the time and is the best option. 2. State Implementation: Summarizes the tax detail for state, county, city and district in one state bucket. It has one sales tax code for each of the 50 states in the United States (plus Washington DC) and one for each US territory (except Puerto Rico). Total sales tax will be summed up by state (including the different tax results for state, county, city and district) per each document line item. There will be no ERP visibility into the specific state, county, city, and district details. A user can log into Determination for specific details. Clients who break out different sales tax payable general ledger accounts per state have the option to continue with these separate breakouts.Tax UsageTax results returned from Determination are displayed and stored based on the implementation method selected. The appropriate tax codes willneed to be defined in the ERP system to support the chosen implementation method. The technical details of how to map the XML elementsbased on the implementation method are defined in the Tax Results Mapping section of this guide.At the time of installation, the sales tax codes will automatically populate into the ERP system.Tax CodesUS Authority Level Implementation (Bucket)The US Authority Level (Bucket) implementation method has four sales tax codes for the United States (state, county, city, and district) and fourfor Canada. Sales tax codes should also be defined for use tax (used for P2P transactions) and zero rated (a tax type returned for US exports).The preferred naming conventions for US tax codes for the US Authority Level (Bucket) implementation are as follows:Tax Code Tax Code Name/DescriptionIDT_CITY_S IDT City Sales Tax CodeIDT_COUNTY_S IDT County Sales Tax CodeIDT_DISTRICT_S IDT District Sales Tax CodeIDT_STATE_S IDT State Sales Tax CodeIDT_ZERO_S IDT Zero Rated Sales Tax CodeIDT_USE_P IDT Use Tax CodeThe preferred naming conventions for Canada tax codes are as follows:Tax Code Tax Code Name/DescriptionIDT_GST_S IDT Canada Goods and Services Tax Code
IDT_PST_S IDT Canada Provincial Sales Tax CodeIDT_HST_S IDT Canada Harmonized Sales Tax CodeIDT_QST_S IDT Quebec Sales Tax CodeIDT_ZERO_S IDT Zero Rated Sales Tax CodeUS State Level ImplementationThe US State Level implementation method has one sales tax code for each of the 50 US states (plus Washington DC), one for each US territory(except Puerto Rico), and four for Canada. Sales tax codes should also be defined for use tax (used for P2P transactions) and zero rated (taxtype returned for US exports).The preferred naming convention for US tax codes is IDT_<StateCode>_S, where <StateCode> is the two-digit state abbreviation (50 states,plus DC, plus territories' specific details). The Tax Code Name/Description will be 'IDT <state name> Sales Tax Code'. The list of tax codes is asfollows:Tax Code Tax Code Name/DescriptionIDT_AK_S IDT Alaska Sales Tax CodeIDT_AL_S IDT Alabama Sales Tax CodeIDT_AR_S IDT Arkansas Sales Tax CodeIDT_AZ_S IDT Arizona Sales Tax CodeIDT_CA_S IDT California Sales Tax CodeIDT_CO_S IDT Colorado Sales Tax CodeIDT_CT_S IDT Connecticut Sales Tax CodeIDT_DC_S IDT District of Columbia Sales Tax CodeIDT_DE_S IDT Delaware Sales Tax CodeIDT_FL_S IDT Florida Sales Tax CodeIDT_GA_S IDT Georgia Sales Tax CodeIDT_HI_S IDT Hawaii Sales Tax CodeIDT_IA_S IDT Iowa Sales Tax CodeIDT_ID_S IDT Idaho Sales Tax CodeIDT_IL_S IDT Illinois Sales Tax CodeIDT_IN_S IDT Indiana Sales Tax CodeIDT_KS_S IDT Kansas Sales Tax CodeIDT_KY_S IDT Kentucky Sales Tax CodeIDT_LA_S IDT Louisiana Sales Tax CodeIDT_MA_S IDT Massachusetts Sales Tax CodeIDT_MD_S IDT Maryland Sales Tax CodeIDT_ME_S IDT Maine Sales Tax CodeIDT_MI_S IDT Michigan Sales Tax CodeIDT_MN_S IDT Minnesota Sales Tax CodeIDT_MO_S IDT Missouri Sales Tax CodeIDT_MS_S IDT Mississippi Sales Tax Code
IDT_MT_S IDT Montana Sales Tax CodeIDT_NC_S IDT North Carolina Sales Tax CodeIDT_ND_S IDT North Dakota Sales Tax CodeIDT_NE_S IDT Nebraska Sales Tax CodeIDT_NH_S IDT New Hampshire Sales Tax CodeIDT_NJ_S IDT New Jersey Sales Tax CodeIDT_NM_S IDT New Mexico Sales Tax CodeIDT_NV_S IDT Nevada Sales Tax CodeIDT_NY_S IDT New York Sales Tax CodeIDT_OH_S IDT Ohio Sales Tax CodeIDT_OK_S IDT Oklahoma Sales Tax CodeIDT_OR_S IDT Oregon Sales Tax CodeIDT_PA_S IDT Pennsylvania Sales Tax CodeIDT_RI_S IDT Rhode Island Sales Tax CodeIDT_SC_S IDT South Carolina Sales Tax CodeIDT_SD_S IDT South Dakota Sales Tax CodeIDT_TN_S IDT Tennessee Sales Tax CodeIDT_TX_S IDT Texas Sales Tax CodeIDT_UT_S IDT Utah Sales Tax CodeIDT_VA_S IDT Virginia Sales Tax CodeIDT_VT_S IDT Vermont Sales Tax CodeIDT_WA_S IDT Washington Sales Tax CodeIDT_WI_S IDT Wisconsin Sales Tax CodeIDT_WV_S IDT West Virginia Sales Tax CodeIDT_WY_S IDT Wyoming Sales Tax CodeUS Territories Defined as States Tax CodesUS Territories and Armed ForcesTo be supported by the simple web request, US territories must be defined as states in the ERP. Currently the new market integrations supportonly the United States and Canada, using US tax content. Therefore, if the US territories are defined as states in the ERP, United States Contentwill provide the sales and use tax calculations. If US territories are defined as countries International Content (unavailable for new marketIntegrations at this time) supplies VAT (Value Added Tax) calculation results, which is not supported by the current simple web request and newmarkets.The preferred naming conventions for US territories and Armed Forces tax codes are as follows:Tax Code Tax Code Name/DescriptionIDT_AS_S IDT American Samoa Sales Tax CodeIDT_FM_S IDT Federated States of Micronesia Sales Tax CodeIDT_GU_S IDT Guam Sales Tax CodeIDT_MH_S IDT Marshall Islands Sales Tax Code
IDT_MP_S IDT Northern Mariana Islands Sales Tax CodeIDT_PW_S IDT Palau Sales Tax CodeIDT_VI_S IDT Virgin Islands Sales Tax CodeIDT_AA_S IDT Armed Forces Americas Sales Tax CodeIDT_AE_S IDT Armed Forces Europe Sales Tax CodeIDT_AP_S IDT Armed Forces Pacific Sales Tax CodePuerto RicoPuerto Rico is implementing a VAT system effective 1 June 2016, therefore, it is not supported in new markets product at this time. VATscenarios, including recoverability and deferments, are not currently supported by the simple web service.Canada Tax CodesThe preferred naming conventions for Canada tax codes are as follows:Tax Code Tax Code Name/DescriptionIDT_GST_S IDT Canada GST Sales Tax CodeIDT_PST_S IDT Canada PST Sales Tax CodeIDT_HST_S IDT Canada HST Sales Tax CodeIDT_QST_S IDT Canada QST Sales Tax CodeIDT_ZERO_S IDT Zero Rated Sales Tax CodeAlternate Naming ConventionSome ERP systems have field length constraints prohibiting the use of the above naming conventions. For example, Microsoft Dynamics AX hasa field length limitation of 10 characters for the Tax Code field and 30 characters for the Tax Code Name field (viewable to the users). Thisrequires an alternative naming convention that shortens the names. In these situations, an abbreviated naming convention can be implemented,as follows:Tax Code Tax Code Name/DescriptionIDT_CIT_S IDT City Sales Tax CodeIDT_CTY_S IDT County Sales Tax CodeIDT_DIT_S IDT District Sales Tax CodeIDT_STT_S IDT State Sales Tax CodeIDT_ZRO_S IDT Zero Rated Sales Tax CodeIDT_USE_P IDT Use Tax CodeNOTE: Only the US Authority Level (Bucket) implementation method tax codes will change because they are over the limitation. Individual statetax codes (and US territories) for the US state level implementation method will remain: IDT_<StateCode>_S, where <StateCode> is thetwo-digit state abbreviation. For more information, see US State Level Implementation, above.Exempt Tax CodesSome ERP systems require that tax codes are defined to indicate an exemption action for a transaction. Thomson Reuters recommendsmanaging customer tax exemptions in Determination. If an exemption for a customer is not defined in Determination, an exempt tax code can beused to flag the transaction as exempt. If an exemption is defined in Determination and a transaction should be taxed, an exemption override taxcode can be used to flag the transaction as taxable (overriding the exemption defined in Determination). Examples of tax codes are: IDT_EXEMPT: Indicates the item in the ERP is non-taxable (exempt) and, therefore, Determination will return a tax result of zero for the particular sales order line item. The IS_EXEMPT flag will be set to True. The response.xml file will show zero sales tax liability. IDT_EXEMPT_O: In sales tax countries (such as the US), the exempt indicator prevents tax from being charged. This tax code would override an exemption, taxing the transaction. The IS_EXEMPT flag will be set to False. If False is explicitly passed the exemption
certificate lookup is suppressed; tax will be charged even though an apparently valid certificate may exist in Determination.For more information on exemptions, see Exempt Management.New Tax CodesIn addition, sales tax codes should also be defined for use tax (for P2P transactions) and zero rated (tax type returned for US exports):Tax Code Tax Code Name/DescriptionIDT_USE_P IDT Use Tax CodeIDT_ZERO_S IDT Zero Rated Sales Tax Code
Quantity and Unit of MeasureDescriptionThe quantity and unit of measure (UOM) are key components on a business transaction and can affect the taxability or tax rate on a transaction.Business UsageQuantity is the number of items the transaction refers to. The value passed in the integration is the transaction the line item's quantity.UOM is a standard unit or system of units that account for and express a quantity. It gives meaning to quantities. The value passed in theintegration is the transaction line item's UOM.Tax UsageThe quantity and UOM could have tax implications on max tax or tiered tax scenarios.Quantity is essential for accurate tax calculation: In Florida, this is especially related to the county surtax threshold for goods ($0-$5000 per item). For example, in the Miami, Florida zip code 33101: Gross Amount = $10,000, quantity of one, $650 in tax ($600 state, $50 county) Gross Amount = $10,000, quantity of 100, $700 in tax ($600 state, $100 county) In Richmond, VA, the \"doughnut law\" makes quantity essential for accurate tax calculation. A purchase between one and five doughnuts is charged the six percent meal tax. However, a purchase of six or more doughnuts is exempted from the tax, since that amount is deemed as more than a single serving. In certain industries different rates could apply based on quantity. For example, in the hospitality industry, different rates (including total exemptions for stays lasting beyond a certain number of days, e.g., 30, 90, 180) could apply based on the duration of the stay.UOM plays a role in certain jurisdictions, for example: The basis of the California Electronic Waste Recycling Fee applies to each item, e.g., how many monitors are you recycling? The basis of taxes in the oil and gas industry is primarily on volume, but can also include other units of measure. The private copying levy applies to music or data that can be copied to another medium. Calculating taxes for sweetened goods and similar products in Canada.
MiscellaneousDetermination Allocation FunctionalityThe allocation functionality in Determination is not supported by the Simple Tax Calculation web service at this time. The service will not trigger anallocation; instead, it calculates “regular” tax. As a workaround, the use of UserAttributeContainer and Determination TransEditors functionalitymay be used. Please reach out to your Developer Community contact if you plan to use the UserAttributeContainer andDetermination TransEditors functionality.
US to Canada Purchasing Cross Border TransactionsDescriptionCross-border purchasing (buyer) transactions between the US and Canada return both input and output GST. The Simple Tax Service currentlycannot consume the tax direction (Input or Output) on the tax result. Therefore, a workaround must be used to support these cross-border buyertransactions.Seller TransactionIn this example, the seller is exporting from the United States and shipping to Canada. For this transaction, Determination returns US Export tax.No tax direction is returned. Ship From: US Ship To: Ontario POTT – I US Export tax calculatedBuyer TransactionIn this example, goods are imported into British Columbia, Canada from the US. In this situation, Canadian Customs would charge GST on theimport. Because the seller is registered for the PST Canadian Customs would also assess PST on the sale. The input GST assessed by Customscan be recovered provided it meets the required business conditions. For this transaction, Determination calculates the input and output GST andthe PST. The transaction is viewed as the sourcing of goods from US followed by a local sale in Canada. The input and output tax directions areincluded in the tax result. POTT – I Seller and buyer registered in CA Ship From: US Ship To: BC GST I and GST O plus PSTTransEditorThe workaround, assumed to be in place by the Implementation Team, is to define a TransEditor in Determination to set the Point of Title Transferto 'D' (destination) when the ship to country is Canada. The following screenshot is an example TransEditor: For Community level members in the Developer Community the above TransEditor has already been defined in Determination.
Related LinesDescriptionTransaction data may be related to other data on the same transaction. The Related Lines functionality provides a mechanism for building arelationship between these data elements. Determination can then identify that the two are related and that the tax policy for one should inheritthe tax of the other.Business UsageIn some cases, a business process may call for one product's taxability to relate to another product on the document or invoice. For example,freight, included as a unique line item in the XML, should inherit the same product taxability as the product being shipped. For example, if the itemline is exempt, then the related freight line would be exempt.Tax UsageTo XML line level elements,<LineNumber > and <RelatedLineNumber>, identify the relationship of two lines.The <LineNumber > XML element is used to specify and reference a particular line on a particular invoice. The <RelatedLineNumber> XMLelement identifies a charge related to the <LineNumber >. The <RelatedLineNumber> element specifies the line that contains the product whosetaxability will be used. A dependent line must always appear in the Input XML after the line it depends on, though it does not need to be the nextline. When the transaction is processed, Determination selects the authorities to process based on the included address data. If a related charge is included, the resulting authorities must be the same for both the parent product and related charge(s). For example, the Ship From addressmust be the same for both lines. If the Related Charge rule is defined, the engine calculates both products using the parent product taxability. Ifthe Related Charge rule is not defined, each product is evaluated separately using the product taxability attributes associated with each.If related line number functionality is not implemented (some ERP systems do not support it), then the Determination Allocated Chargefunctionality can be used. See Determination documentation for more information.The sample code below shows how the two fields are used. In this example, an invoice contains two line items both shipping to and fromWashington State. The <RelatedLineNumber> element is taxed according to how <LineNumber > 1 is taxed. <LineNumber>1</LineNumber> <Product>Widgets</Product> <LineNumber>2</LineNumber> <Product>Freight</Product> <RelatedLineNumber>1</RelatedLineNumber>
Coding StandardsDescriptionDuring the sign-up process for the Thomson Reuters Professional Developer Community, the Terms Of Use were outlined. On this page, wedescribe a few considerations to keep in mind when coding a solution. Neither the program or the optional verification of your solution will reviewyour code. You own and manage your IP.Naming ConventionsWhen designing your solution make sure your code is clearly distinguished from the source code of the transaction system. To ensure distinction,we recommend the use of defined name spaces, naming patterns, and similar depending on your development environment. For example, if yourintegration is built for an ERP system called All Best Code (ABC), and your company name is We Know Tax (WKT) then your code could includeWKT as an identifier. Depending on the programming language your classes would start with wkt_, your packages are named wkt_, etc. Do not use any Thomson Reuters names, brands, or abbreviations such as ONESOURCE, Indirect Tax, IDT, etc. in your product. Note: This is not a full list all names, brands, and abbreviation that are protected by Thomson Reuters.Open SourceWhile open source code is helpful and commonly used in today's software development process, using open source code has a few pitfalls. Wehighly recommend that you pay attention to the individual licenses of open source libraries when considering their use. Depending on the license,your code and the whole product could become public domain, rendering your IP useless. Open Source compliance can be achieved in manyways, either by simply reviewing each open source library license or using tools to scan your code to identify the open source you use and it'scompliance. Thomson Reuters uses Black Duck Protex.Code VulnerabilityIt is the developer's responsibility to ensure code is free of flaws that could be exploited by hackers and malicious individuals. We recommend thatyour code is subjected to a test by a vulnerability scanning tool, Thomson Reuters uses the Veracode Vulnerability Scanning Tools.
Security ConsiderationsDescriptionWhen building an integration, consider the security of the data being managed during tax calculations as well as preventing changes to theintegration setup. This section outlines some key areas that should be implemented in an integration.PasswordA username and password are required to communicate with ONESOURCE provided web services. The values must be stored somewhere in theconfiguration setup in order for the integration to work. We strongly recommend storing the password in the database in a secure manner, eitherby using a data type provided by the development environment or by storing it in a hashed or encrypted format. Passwords should never bestored as plain text.When a web service call is logged the password must never be stored in the log. The logging process should replace the password withsomething different. For example, most of our integrations replace the password with \"REMOVED FOR SECURITY\".Configuration SetupWe recommend you consider using system access roles when designing an integration. For example, there are system users who createtransactions and there are advanced users who can configure ONESOURCE Indirect Tax. There could also be a third type of user, such as a taxbusiness user, who runs reports, reconciliations, and other business tasks provided by the solution. We recommend separating these roles byimplementing a security profile for each. This will be dependent on the development environment the integration is built in. When developingwithin an ERP system, system security profiles might be used to add specific roles to the integration. With a standalone API, which has text filebased configuration properties, this might not be possible. In addition, the files must be secured when installed via file level access policies on thefile system. It is important to give this area some consideration.Web Service CallAll communications with the Thomson Reuters ONESCOURCE Indirect Tax Cloud must use the HTTPS communication protocol. HTTPSencrypts the payload for security purposes. Your integration must support HTTPS. Depending on your integration's development environment youmay have to design your integration specifically to support HTTPS or you may need to create specific setups or include libraries to enable HTTPScommunication. You can find generic instructions that explain how to download and install the required HTTPS certificates on the ONESOURCESoftware Support Network, see KB 1375 and 1430.While HTTPS is a requirement for all cloud managed ONESOURCE customers, we still support on-premise deployments of our software wherethe tax engine might be behind a customers' firewall and, therefore, HTTPS is not required. In these cases, HTTP can be used. We highlyrecommend that your integration supports HTTP in addition to HTTPS.
WSS-Header-RequirementsDescriptionIn order to connect an application to ONESOURCE Indirect Tax via web services, the following requirements and recommendations should beobserved:All Web Services REQUIRED: Password element with Type attribute. RECOMMENDED: Nonce element.Web Service 2009-12-20 (\"Simple Tax Service\") REQUIRED: Timestamp element OPTIONAL: Created element within UsernameTokenWeb Service 2011-09-01 FORBIDDEN: Timestamp element RECOMMENDED: Created element with UsernameTokenAll Web ServicesThe following elements are required or recommended for all ONESOURCE Indirect Tax web services:REQUIRED — Password element with Type attributeThe Type attribute must now be supplied with the Password element, with a complete namespace path. The only supported Type is PasswordText. Formerly, Password was accepted without any attributes. The following code block is an example: <wsse:Password Type=\"http://docs.oasis--open.org/wss/2004/01/oasis--200401--wss--username--token-- profile--1.0 #PasswordText\">YourPasswordHere</wsse:Password>RECOMMENDED — Nonce elementA Nonce element may be supplied within the UsernameToken element. If present, the value must be unique across all requests, and the value must be valid according to the EncodingType attribute. The value should be at least 16 bytes (128 bits) of cryptographicallystrong random binary data before encoding. The value MUST NOT be reused. Example: <wsse:Nonce EncodingType=\"http://docs.oasis-open.org/wss/2004/01/oasis-200401--wss--soap--message-- security--1.0#Base64Bi nary\">Hit431nzikeFeZT9yyzeAg==</wsse:Nonce>Web Service 2009-12-20The 2009-12-20 web service (also known as the \"Simple Tax Service\") has the following additional requirements and recommendations:REQUIRED — Timestamp elementThe Timestamp element must be present. The Id attribute must be present and must be unique within the request. The Created subelement must be present and contain a date/time stamp that conforms to the requirements in Date/Time Stamp Format below. The Expires subelement may be supplied. If present, it must contain a date/time stamp that conforms to the requirements in Date /Time Stamp Format below. If not present, the default is 5 minutes from the date/time in Created.The following code block is an example: <wsu:Timestamp wsu:Id=\"Timestamp--1\"> <wsu:Created>2016--01--14T20:03:06.021Z</wsu:Created> <wsu:Expires>2016--01--14T20:08:06.021Z</wsu:Expires> </wsu:Timestamp>OPTIONAL — Created element within UsernameTokenThe UsernameToken element may contain a Created element (not to be confused with that contained in Timestamp, discussed above). The valueis a date/time stamp that conforms to the requirements in Date/Time Stamp Format below. If present, this date/time stamp takes precedence
over Timestamp. A request with a Created element contained within UsernameToken expires 5 minutes from the supplied date/time stamp.The following is an example security header for the 2009-12-20 web service, with allrequired and recommended fields (some long elements are broken across lines for clarity): <soapenv:Envelope xmlns:ns=\"http://www.sabrix.com/services/taxservice/2009--12--20/\" xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\"> <soapenv:Header> <wsse:Security soapenv:mustUnderstand=\"1\" xmlns:wsse=\"http://docs.oasis--open.org/wss/2004/01/oasis--200401--wss--wssecurity--secext--1.0 .xsd\" xmlns:wsu=\"http://docs.oasis--open.org/wss/2004/01/oasis--200401--wss--wssecurity--utility--1.0 .xsd\"> <wsse:UsernameToken wsu:Id=\"UsernameToken--1\"> <wsse:Username>YourUsernameHere</wsse:Username> <wsse:Password Type=\"http://docs.oasis-open.org/wss/2004/01/oasis-200401--wss--username--token--profile--1.0#Pa sswordText\">YourPasswordHere</wsse:Password> <wsse:Nonce EncodingType=\"http://docs.oasis-open.org/wss/2004/01/oasis-200401--wss--soap--message--security --1.0#Base64Binary\">Hit431nzikeFeZT9yyzeAg==</wsse:Nonce> </wsse:UsernameToken> <wsu:Timestamp wsu:Id=\"Timestamp--1\"> <wsu:Created>2016--01--14T20:03:06.021Z</wsu:Created> <wsu:Expires>2016--01--14T20:08:06.021Z</wsu:Expires> </wsu:Timestamp> </wsse:Security> </soapenv:Header> <soapenv:Body>Web Service: 2011-09-01The 2011-09-01 web service has the following additional requirements and recommendations:FORBIDDEN — Timestamp elementThe Timestamp element must not be present.RECOMMENDED — Created elementThe UsernameToken element may contain a Created element whose value is a date/time stamp in UTC, in restricted ISO-8601 format and with aresolution of seconds or milliseconds. If present, the request will expire 5 minutes from the supplied date/time stamp.The following is an example security header for the 2011-09-01 web service, with all required and recommended fields (some long elements arebroken across lines for clarity): <soapenv:Envelope xmlns:ns=\"http://www.sabrix.com/services/taxcalculationservice/2011--09--01\" xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\"> <soapenv:Header> <wsse:Security soapenv:mustUnderstand=\"1\" xmlns:wsse=\"http://docs.oasis--open.org/wss/2004/01/oasis--200401--wss--wssecurity--secext--1.0 .xsd\" xmlns:wsu=\"http://docs.oasis--open.org/wss/2004/01/oasis--200401--wss--wssecurity--tility--1.0. xsd\"> <wsse:UsernameToken wsu:Id=\"UsernameToken--1\"> <wsse:Username>YourUsernameHere</wsse:Username> <wsse:Password Type=\"http://docs.oasis--open.org/wss/2004/01/oasis--200401--wss--username--token--profile--1.0# PasswordText\">YourPasswordHere</wsse:Password> <wsse:Nonce EncodingType=\"http://docs.oasis--open.org/wss/2004/01/oasis--200401--wss--soap--message--securi ty--1.0#Base64Binary\" >Hit431nzikeFeZT9yyzeAg==</wsse:Nonce> </wsse:UsernameToken> <wsu:Timestamp wsu:Id=\"Timestamp--1\"> <wsu:Created>2016--01--14T20:03:06.021Z</wsu:Created> <wsu:Expires>2016--01--14T20:08:06.021Z</wsu:Expires> </wsu:Timestamp> </wsse:Security> </soapenv:Header> <soapenv:Body>Date/Time Stamp FormatDate/time stamps supplied in Created or Expires elements must conform to the following: The timezone for the date/time stamp must be in UTC (Coordinated Universal Time). The format of the date/time stamp must be in restricted ISO-8601 format (see References below) and must end with a trailing 'Z' character to denote the UTC timezone.
The resolution of the date/time stamp must be either seconds ( YYYYM- M-DDThh:mm:ssZ) or milliseconds (YYYY-MMD- DThh:mm:ss.mmm Z).Date/Time Stamp ExamplesThe examples below illustrate both valid and invalid date/time stamps.Valid Date/Time Stamps Seconds: 2016--01--14T20:03:06Z Milliseconds: 2016--01--14T20:03:06.021ZInvalid Date/Time Stamps Not UTC, invalid timezone specification: 2016--01--14T15:03:06--0500 UTC, but invalid timezone specification: 2016--01--14T20:03:06+0000 Missing timezone specification: 2016--01--14T20:03:06 Missing timezone specification: 2016--01--14T20:03:06.021 Missing 'T' time-of-day separator character: 2016--01--14 20:03:06.021Z Invalid decimal separator: 2016--01--14T20:03:06,021Z Missing seconds: 2016--01--14T20:03ZReferencesDate and Time Formats: http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/#isoformats+Username Token Profile: http://www.oasis-open.org/committees/download.php/16782/wss-v1.1-spec-os-UsernameTokenProfile.pdf+Web Services Security Core Specification: http://www.oasis-open.org/committees/download.php/16790/wss-v1.1-spec-os-SOAPMessageSecurity.pdf+Web Services Security Technical Committee: https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss+
SimpleTaxServiceDescriptionThe SimpleTaxService provides real-time tax calculation using the SOAP XML format. The functionality and elements are less complex than the TaxCalculationService. At this time, the Integrator Playbook focuses on the SimpleTaxService. Make sure to review the Main Components of a TaxCall section before moving on. The service is structured with a SOAP header and SOAP body.SOAP HeaderThe header section contains the information required to communicate securely with ONESOURCE. The two main elements are Timestamp and UsernameToken. Both are described in more detail in the WSS-Header-Requirements section of this playbook.SOAP BodyThe body of a SOAP communication includes either Web Service Request or Web Service Response data.
Web Service RequestDescriptionThe body of a web service request contains all the information required to calculate tax based on the transaction system's data. The fields sent toONESOURCE will be used in the tax determination based on the tax policy configured and the taxability rules for the taxing authorities inquestion.Request contain the following containers: host request information document lineHost Request InfoThis container is comprised of a list of informational fields that assist ONESOURCE in troubleshooting and identifying the transaction in question,see Informational Fields section below for a field-by-field explanation.DocumentsThe Documents container is a list of documents, each defined by a collection called Document. A document in this context can be any type oftransaction document, for example, a quote, order, invoice, requisition, vendor invoice, credit, or debit, etc. This usually matches with yourtransaction system's calling process. Information sent at the document level is sometimes also referred to as header data. Data at this levelusually applies to the whole document, including all lines within the document. However, if the same data is also available at line level, thatinformation will supersede the document level information. Some of the key fields in the Document collection outlined in the table below.Field UseDocumentNumber This field uniquely identifies the transaction systems document, required for an audited transaction. Also, see Uniqueness in AuditAddresses These fields are optional at the document level.Attributes There are several fields in this container, the playbook explains the use of most of them in their respective design concept area. To initiate an audit of your tax calculation for later reporting and compliance the IsAuditResult field has to be set to tr ue.Dates There are two date fields. DocumentDate: drives taxability FiscalDate: required at time of auditVendorTax This field stores the tax stated by the supplier on the vendor invoice. It is an informational field that can be written to the audit database for later reporting.LinesThis container holds the information for each line in your transaction system and is critical for tax calculation.Field UseLine Id This field must be unique in your request for each Line collection within the Lines container.LineNumber The LineNumber field should correspond to the transaction system's line number.RelatedLineNumber Use to build a relationship between the main line and a sub-line, usually for Bill of Materials, Kits, or similar.Addresses The line level address fields are required for tax calculation.Amounts See AmountsChargeCollection See ChargesAttributes There are several fields in this container, the playbook explains the use of most of them in their respective design concept area.
TaxabilityInfo The fields in the TaxabilityInfo collection are mostly used when transaction tax calls from within the accounting systems AR or AP area, like posting a financial voucher. These types of transactions commonly have no associated item masterQuantity data, therefore product taxability information isn't available. For these cases, two additional fields could be used to triggerRegistrations proper taxability based on configurations in the tax engine: GlAccount: the General Ledger Account the transaction is posted to CostCenter: the Cost Center element the transaction is posted to See Non-Inventory Items See Quantity and Unit of Measure See Registrations
Informational FieldsPurposeA collection of fields in HostRequestInfo provide information needed for customer assistance and to uniquely identify a transaction in ourmulti-tenant database. All fields in the HostRequestInfo collection are required, i.e., they must have a value sent. If necessary, multiple values canbe combined in one field by separating them with a pipe (|) character. Some values can be derived from the environment the integration runs in,some are hardcoded into the integration, and in some cases they could be sourced from a field in a set up window.Field ListField Description<HostRequestInfo> Container for information about the requestor. <CallingClient/> Unique identifier of the source making the call, i.e., machine name, domain, IP (or similar), that is not currently saved in the audit database. <CallingSource/> Easily-readable description of the source making the tax call, including Microsoft Dynamics GP, SAP Business One, SAP hybris, NetSuite, and more. <CallingSystemNumber/> A unique identifier that ensures different instances of the same clients calling systems are clearly separated. A pass-through element that contains a descriptor of the calling system ID sending the transaction. For example, a system that uses different database schemas to separate legal entities could use the following: Name of database schema. Name of database schema AND the (client) machine name servername and database. If multiple fields are merged into one string, separate them with a pipe (|) character. When selecting the field, make sure that the field's source is the same for each system even if it is set up as a cluster. For example: if there are multiple applications serving one instance to distribute load and performance, than the value must apply the same in the cluster. <CallingUser/> User ID of the person processing the transaction. It is used to assist in troubleshooting possible issues. For e-commerce this might be the ID of the user placing the transaction. In an ERP, this is traditionally the logon or user ID. Examples of user IDs are: u123456, johndoe, jdoe, or [email protected]. <DbVersion/> Database version of the application sending the transaction. Can be set to N/A if not relevant. For example: 1.0.0.0.000, 1.0, or v1. <ErpVersion/> Version of the transaction system sending the calculation request. For example: 1.0.0.0 or 2015.1. <HostRequestId/> Unique identifier for the tax calculation request throughout the ONESOURCE system. Saved to the database on audit calls. <HostRequestLoggingId/> Unique identifier for the tax calculation request throughout the ONESOURCE system. Used to match up logs across systems for a call. For many systems the HostRequestLoggingId is a generated random ID. <HostSystemNumber/> Unique value that describes the nature of the system making the tax call. Options include: In some ERPs, this value could be the SID, Instance Name, System Name, or a similar value. Sending a value such as DEVELOPMENT, TEST, STAGE, or PRODUCTION. As a last alternative, sending the tax calculation URL. When selecting the field, make sure that the field's source is the same for each system even if it is set up as a cluster. For example: if there are multiple applications serving one instance to distribute load and performance, than the value must apply the same in the cluster. <IntegrationVersion/> Unique identifier of the product version that is integrating with ONESOURCE. <SdkVersion/> If using a Thomson Reuters-provided software development kit (SDK), this field must contain the version</HostRequestInfo> number of the SDK. If the Thomson Reuters SDK is used, enter N/A. N/ANOTE: <DbVersion/>, <HostSystemNumber/>, and <UniqueInvoiceNumber> make up a unique key to add to a transaction to the Determination
tax liability database. For more information, see Uniqueness in Audit.
Determining Postal Code and Geo Code This section is only relevant for addresses located in the United States.OverviewIn 1983, the US Postal Service began using an expanded ZIP+4 code. The ZIP+4 code consists of two segments: a five-digit postal code and afour-digit geo code. The ZIP+4 code provides the most accurate location for tax calculation purposes. The tax calculation software has two XMLfields for addressees with a ZIP+4 code: PostalCode and GeoCode.The following is a tax request's ship-from segment. The postal code and geo code are included in two separate HTML tags: <ShipFromAddress> <Country>UNITED STATES</Country> <Region>IL</Region> <City>Melrose Park</City> <Address1>Address Line One</Address1> <PostalCode>60164</PostalCode> <GeoCode>1068</GeoCode> <PartnerNumber>TWO</PartnerNumber> <PartnerName>Fabrikam, Inc.</PartnerName> </ShipFromAddress>However, some systems store the postal code and the geo code in a single text field. The zip code may be entered one of the following formats: 12345-1234 12345 1234 123451234NOTE: Be sure to enter the full zip code, otherwise the tax will not be calculated.Mapping RequirementsMapping the postal code and geo code (if provided) to the GeoCode is required. Logic should be implemented to validate the zip code by firstchecking for a total length of nine characters without a separating character or for 10 characters with a separating character. If a zip code doesnot meet these requirements, an error appears and the tax request stops.Example of zip code logicIf the address = USIf zip text string = 9 characters // check for 9char, all numericalThen PostCode = left 5 // map 5 charPostCode XML GeoCode = right 4 // map 4 char GoeCode XMLElse zip text string = 10 and 6th character is not numerical // check for 10 char,all numericalThen PostCode = left 5 // map 5 char PostCode XML GeoCode = right 4 // map 4 char GoeCode XMLElse zip text string = 5 // map 5 char PostCode XMLThen PostCode = left 5 // map 5 char PostCode XMLRemove GeoCode tag from xml // do not send an NULL or empty string GeoCodeElse ErrorElse do nothingExample Java zip code validation code
Web Service ResponseDescriptionThe body of a web service response contains all the information required to collect the appropriate tax information to return to the transactionsystem. The response contains these main containers: request status tax document tax line tax data (summary, zone, detail)Request StatusThis collection provides information about the tax calculation success or failure. Two status levels are provided; RequestStatus and DocumentStatus. Please see Status of a Response for details on how to process this information.Tax DocumentThis collection contains a list of documents, each defined by a collection called TaxDocument, matching to the request documents sent toONESOURCE for tax calculation. Each document will contain detailed information about the tax calculated.Field UseDocumentNumber Uniquely identifies the transaction system's document, linking back to the request's document number.UseTaxInformation Not yet supported, reserved for future use.TotalTaxAmount The compounded total tax for this document for all lines and authorities.Tax LinesThis collection holds the information for each line in your transaction.Field UseLine Id This field must be unique in your request for each Line collection within the Lines container linking back to the request.TaxSummary This level contains the total tax for the line.ZoneTaxSummaries Returns tax in up to four buckets; State, County, City, and District based on the Effective Zone Level of the authority.TaxDetails Details for each taxing authority with no summarization.For all three tax collections the following fields are returend:Field UseEffectiveTaxRate TaxSummary only; calculated rate for that tax lineCalculatedTaxAmount Tax amount chargedAccrualTaxAmount Not yet supported, reserved for future usePartnerTaxAmount Not yet supported, reserved for future useTaxableBasis Amount used to calculate the tax. Usually the amount sent in the Amounts collection for the request, but could be modified based on tax rules and laws.ExemptAmount Amount applied against an exemption. Could be the total of the tax calculated (fully exempt) or a partial amount.Additional fields are returned in some levels, see Tax Results Mapping for details on how to process the returned data back into the calling
system.
Status of a ResponseDescriptionIt's imperative to know quickly if a request sent to ONESOURCE has successfully calculated tax for all documents and lines. To assist in this theweb service has two collections, RequestStatus and DocumentStatus.Status Collection FieldsField UseSuccess Returns a value of either Success, PartialSuccess, or Failure.Code This is a technical error identifier returned by ONESOURCE.Description A human readable error text that should be displayed on the user screen.ErrorLocationPath This is a technical explanation of where the error occurred in the XSD.If multiple errors are found in a transaction or a document the status collection only returns the first error.Request StatusThe RequestStatus collection indicates if the whole request was successful or not. Possible values are:Value MeaningSuccess The whole calculation request (all documents and lines) calculated taxes successfully.PartialSuccess This indicates that one or more documents in the request have failed.Failure This indicates that all documents in the request have failed.Document StatusThe DocumentStatus collection indicates if the whole request was successful or not. Possible values are:Value MeaningSuccess The whole document (all lines) calculated taxes successfully.Failure One or more lines in the document in question contained an error.PartialSuccess is not a possible value. A document with one or more errors at line level is always considered in failure.ExamplesAssume you send a request with a batch of two documents and each document contains two lines sent to ONESOURCE for calculation. Thepossible return status' are:RequestStatus DocumentStatus - DocumentStatus - Result SoapUI Request sample Document 1 Document 2 SuccessSuccess Success All documents and lines 0_AllLevelsSuccess Success calculated tax.PartialSuccess Failure Failure One or more lines in the second 1_PartialSuccess_OneDocumentFails document failed.Failure Failure One or more lines in both 2_Failure_OneTaxLineEachFails documents failed.Attached SoapUI sample ResponseStatus.xml showcases above scenarios.
Tax Results MappingDescriptionThe SOAP response has three main areas containing tax results in different summarization levels at line level:Level DescriptionTaxSummary Contains the total tax for the lineZoneTaxSummaries Returns tax in up to four buckets; State, County, City, and DistrictTaxDetails Contains details for each taxing authority, no summarizationUS Tax MappingsDepending on the type of implementation tax should be collected from one of the three levels: 1. Authority Level Summarization: Returns tax in up to four buckets; State, County, City, and District For this implementation method, one can read the ZoneTaxSummaries collection. Within that collection, there are up to four ZoneTaxSu mmary collections, each containing the summarized tax for a specific summarization level, indicated by the SummarizationLevel tag. The SummarizationLevel can contain one of the following four values; State, County, City, or District. 2. Tax Summary by State: Returns tax summarized by state For this implementation method, one would read the TaxSummary information. However, there is one important field missing from that collection, the Taxable State to assist in determining what tax detail, tax schedule, tax code, tax area, etc. to assign to in the ERP system. To determine the taxable state one has to read the first occurrence of a TaxDetail collection in the TaxDetails information. The first TaxDetail will contain the TaxableRegion the state for which the tax was calculated. See long to short name mapping in the appendix at the end of this document. 3. Authority Detail Implementation: Returns tax details by authority This method is rarely used in the mid-market. But if the source system allows for this kind of an implementation without major constraints or work, then this option could be selected. The TaxDetail collection in the TaxDetails information structure holds the tax for each single authority that taxed the line. Within the TaxDetail collection, all relevant tax information can be found.Canada Tax MappingsFor Canadian implementations we usually return the taxes by tax type; HST, GST, PST, and QST.The TaxDetail collection in the TaxDetails information structure holds the tax for each single authority that taxed the line. Within the TaxDetail collection, the AuthorityType field would hold the value for HST, GST, PST, or QST. In some cases, two types are returned (GST/PST, GST/QST)in others only one (HST).To separate between US vs. CA tax liabilities the TaxDetail -> TaxableCountry will hold a value of US or CA.US/Canada cross-border use caseTransactions that ship between US and Canada will be Not Liable on the US side and Zero Rated on the Canadian side. In these cases, we needto account for the Not Liable tax being returned in the ERP by creating a tax schedule, tax code, tax area, etc. of IDT_ZERO_S to uniquelyidentify that tax. This will be used to total all Not Liable and Zero Rated transactions. This is especially relevant to transactions where theShip-From is within Canada and the Ship-To is within the US. These transactions will result in no tax calculation as they would be Not Liable onthe US side and Zero Rated on the Canadian side. If these Not Liable and Zero Rated transactions are ignored, we would have no response fromthe tax engine to display in the ERP.
Sample Results Tax RateUS Tax ResultsExample: Results for San Francisco = $200Option 1: 4 Authorities Authority
IDT_State $12.00 6.25% IDT_Cnty $2.50 1.25% IDT_City IDT_Dist $2.00 1.00%Option 2: State Authority Tax Rate IDT_CA $16.50 8.50%Canada Tax ResultsExample: Sale with Ship to=Canada, Ship from = Canada - CAD200Option 1: British ColumbiaAuthority Tax RateIDT_GST 14 7.00%IDT_PST 10 5.00%Option 2: Nova Scotia Rate 15.00%Authority TaxIDT_HST 30 Rate 15.25%Option 3: QuebecAuthority TaxIDT_QST 31Cross-Border Tax ResultsExample: Sale with Ship to=US, Ship from = Canada (US Not Liable (NL) amount of zero and a Canadian Zero Rated amount of zero)Option 1: British ColumbiaAuthority Tax RateIDT_ZERO_S 0 0.00%Example: Sale with Ship to=Canada, Ship from = US (US NL amount of zero)Option 1: British ColumbiaAuthority Tax RateIDT_GST 0 7.00%IDT_PST 0 5.00%IDT_ZERO_S 0 0.00%State long name to 2-digit mappingTo generate the proper tax area code, i.e. IDT_CA_S, or IDT_AZ_S we need to map the state long name as returned in the TaxableRegion fieldto a 2-digit code. We will support the 50 US States plus DC, as well as 7 Territories and 3 Armed Forces regions.Puerto Rico is not supported as that territory is switching to a full VAT regime in June 2016. This will require VAT processing logic in theERP and Integrations, which is not currently supported in the Simple Tax Service.
Please use the following table as mapping guide: 2-digit code Long Name AL US States plus DC AK ALABAMA AZ ALASKA AR ARIZONA CA ARKANSAS CO CALIFORNIA CT COLORADO DE CONNECTICUT DC DELAWARE FL DISTRICT OF COLUMBIA GA FLORIDA HI GEORGIA ID HAWAII IL IDAHO IN ILLINOIS IA INDIANA KS IOWA KY KANSAS LA KENTUCKY ME LOUISIANA MD MAINE MA MARYLAND MI MASSACHUSETTS MN MICHIGAN MS MINNESOTA MO MISSISSIPPI MT MISSOURI NE MONTANA NV NEBRASKA NH NEVADA NJ NEW HAMPSHIRE NM NEW JERSEY NY NEW MEXICO NEW YORK
NORTH CAROLINA NCNORTH DAKOTA NDOHIO OHOKLAHOMA OKOREGON ORPENNSYLVANIA PARHODE ISLAND RISOUTH CAROLINA SCSOUTH DAKOTA SDTENNESSEE TNTEXAS TXUTAH UTVERMONT VTVIRGINIA VAWASHINGTON WAWEST VIRGINIA WVWISCONSIN WIWYOMING WYTerritoriesAMERICAN SAMOA ASFEDERATED STATES OF MICRONESIA FMGUAM GUMARSHALL ISLANDS MHNORTHERN MARIANA ISLANDS MPPALAU PWVIRGIN ISLANDS VIArmed ForcesARMED FORCES AMERICAS AAARMED FORCES EUROPE AEARMED FORCES PACIFIC AP
TaxCalculationServiceDescriptionThis tax calculation service provides real-time tax calculation using XML format. The functionality and elements are more complex than the simpletax service. At this time the Integrator Playbook focuses on the SimpleTaxService, at a later point we will expand to the morecomplex TaxCalculationService. Please reach out to your Developer Community contact if you plan to use the TaxCalculationService in yourintegration with ONESOURCE.
Address Validation Service This section is only relevant for addresses located in the US.DescriptionTo provide the most accurate US tax, Determination requires complete and valid address information including ZIP+4. In financial systems wherean address validation / address quality service is not deployed, the ONESOURCE solution needs to ensure that the relevant addresses havebeen validated and updated with proper information. The ONESOURCE Address Validation Service is a product that can validate US addresseseach time a new address is created or when editing an existing US address for a transaction where tax will be calculated.In addition to tax calculations, the benefits of validated addresses include more accurate shipping, fewer returns, and improved invoicing. Whileeach address in the system could be relevant for tax calculations the ONESOURCE process usually focuses on the key entities that changefrequently and are commonly not well maintained. The priority order is as follows: 1. Customer master address (ship-to, main customer address) – required for US O2C transactions 2. O2C one-time overrides during transaction processing – required for US O2C transactions 3. Vendor master address (ship-from, main vendor address) – required for US P2P transactions 4. P2P one-time overrides during transaction processing – required for US P2P transactions 5. Other system addresses as prioritized a. Company b. Site/Warehouses/PlantsDepending on the implementation modules, only parts of above will apply.Address Validation TriggerFor records in question as listed in the description, a check has to be implemented that triggers an address validation request to a specificallydesigned SOAP request for this purpose. The trigger should be based on one or more of the following entities: Only make an address validation call for entities relevant to external tax This could be based on the tax schedule, tax area, tax code, etc. which would be IDT or ONESOURCE Based on the country code of the address – US Create or update to any relevant addressAddress Validation SOAPA SOAP endpoint is provided specifically for address validation, the URL is as follows:URL Commnethttps://prefix.subdomain.thomsonreuters.com/avs/sav.wsdl Generic sample; replace prefix.subdomain with the hosting system you integrate withhttps://partnerdev2-uat.hostedtax.thomsonreuters.com/avs/sav.wsdl Current URL for all partners to useThe SOAP has a simple request with the following fields provided: Username Password RequestId ExternalCompanyId ReturnInputData LogLevel Address1 Address2 Address3 City Region PostalCode CountryThe response contains the flowing fields:
Status (of request) Description Status (of address) Address1 Address2 Address3 City Region PostalCode CountryNote: Address validation will only be performed for US addresses. The ONESOURCE address validation service does no support non-USaddresses.Address Validation ProcessA new process is to be created for each entity as listed in the description above that are relevant for address validation. The system will need totrack if an address validation is required or not, and if the user ultimately did validate the address or not. The purpose of the flag is to have aninternal pointer to know if Address Validation is still to be done (true), if it was done successfully (false), or if the user decided to exit the processwithout Address Validation (initial). This flag is set to true when specific tax-related address fields are modified, they are: 1. Address Line 1 2. Address Line 2 3. Address Line 3 4. City 5. State 6. Country 7. Zip Code 8. Tax Schedule, Tax ID, Tax Area, Tax code (if present)***explain more about using a flag in the system to track if an address has previously been validated or not. We need to say they need to create aflag associated with each address like IS_Validated, if True then they have already done a validation if False it needs to be validated. In event ofan update to the flag it should switch to false and start the process over again.***The purpose of the flag is to have an internal pointer to know if AV has still to be done (true), if it was done successfully (false), or if the userdecided to exit the process without AV (initial).***The flag in NetSuite is actually the reverse of that. Unvalidated = false, validated = true. The ID of the flag is custrecord_idt_validated and thelabel is “Validated.”If the user moves off the address or latest when the user triggers the save procedure for the record in question and the flag is set to true, the usershould be presented with an option of how to proceed. The options should be to validate the updated address record, save the record withoutvalidating it or cancel the save process and be returned to the original form. A user option like the one below serves as an example:If the user selects Cancel, return to the original form and maintain any changes to the data. Maintain the value of the flag as true.If the user selects Continue Save, close this form and save the record without validating the changes, reset the flag to its initial state.If the user selects Validate, a new form should be presented to perform the address validation (AV). The new window will have 3 buttons –Accept, Cancel, and Validate. The new window will also contain on the left-hand side editable address information based on the currently enteredinformation. The right-hand side shows read-only ONESOURCE validated address.The form below serves as an example:
Here are the events: 1. Clicking the Accept button: update the address fields in the master/transaction record with the address information shown on the right-hand side and then close window. Set the flag to false. 2. Clicking the Cancel button: close the window. Keep the flag set as true. 3. Clicking the Validate button: validate the address fields entered on the left-hand side by calling ONESOURCE AV web service and update the right pane with ONESOURCE validated address.The purpose of the flag is to have an internal pointer to know if AV has still to be done (true), if it was done successfully (false), or if the userdecided to exit the process without AV (initial).The code design should be as modular as possible to achieve highest level of code reuse. For example: use a common procedure to update flagsso that it can be called by other processes. Use a common procedure to open the AV window that will accept the caller type as one of itsparameters so it can update the fields on the right window. Also, use a common procedure to call AV service.General Process Flow
ERP Testing
Test Cases
Search
Read the Text Version
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
- 26
- 27
- 28
- 29
- 30
- 31
- 32
- 33
- 34
- 35
- 36
- 37
- 38
- 39
- 40
- 41
- 42
- 43
- 44
- 45
- 46
- 47
- 48
- 49
- 50
- 51
- 52
- 53
- 54
- 55
- 56
- 57
- 58
- 59
- 60
- 61
- 62
- 63
- 64
- 65
- 66
- 67
- 68
- 69
- 70
- 71
- 72
- 73
- 74
- 75
- 76
- 77
- 78
- 79
- 80
- 81
- 82
- 83
- 84
- 85
- 86
- 87
- 88
- 89
- 90
- 91
- 92
- 93
- 94
- 95
- 96
- 97
- 98
- 99
- 100
- 101
- 102
- 103
- 104
- 105
- 106
- 107
- 108
- 109
- 110
- 111
- 112
- 113
