TM 00111 AFC Saa S Standard User Manual Telecom
User Manual:
Open the PDF directly: View PDF .
Page Count: 61
Download | |
Open PDF In Browser | View PDF |
AvaTax for Communications SaaS Standard User Manual Release: Document: Date: 9.20.1812.1 TM_00111_0047 11/21/2018 Avalara for Communications - Contact Information Address Avalara, Inc. 512 South Mangum Street, Suite 100 Durham, North Carolina, 27701 Email CommunicationSupport@avalara.com Help Center https://help.avalara.com/Avalara_for_Communications Toll Free (877) 780-4848 Corporate Web Site http://communications.avalara.com/ Communications https://communications.avalara.net Customer Portal All trade names referenced herein are either trademarks or registered trademarks of their respective companies. © Avalara, Inc. 2018. CONFIDENTIAL Document Revision History The Revision History log lists the date and description of the most recent revisions or versions of the document. Date Version Description 02/15/2016 0024 03/01/2016 0025 04/05/2016 0026 05/05/2016 0027 06/13/2016 0028 06/30/2016 0029 08/09/2016 0030 11/15/2016 0031 12/05/2016 0032 02/13/2017 0033 Avalara branding updates to reflect the transition to the new company and product names have been incorporated into this document. Please see Appendix D – Avalara Product Names for specific changes in product references and descriptions. New Section 3.3.4 Handling Optional Files to address handling of optional files which can be embedded and/or persisted such as exclusion, override, exemption and bundle files. New Section 8.2 Specific Exemption File, and new Section 8.8.29 Proration. Updates to Section 3.3.4 Handling Optional Files and Section 3.5 Results to include use of Custom Sort utility. Updates to Section 3.5 Results related to the ability to view output files in CSV format. Updates and new additions throughout Section 8.2 Exemption File to include Category Exemptions and Section 8.8.35 Exemptions by Tax Category. Update to date formats in Section 8.8.7 Specifying Transaction Date. Updated NTL filename to match input filename in Section 3.5.2. Added customsort_log.sta to status files in Section 3.5.3. Updated Section 3.5.2 with audit versions of TSR and RTR reports. Updated Section 8.8.30 Specifying Optional Reporting Fields and added new Section 8.8.30.1 Default Optional Fields and Section 8.8.30.2 Extended Optional Fields. Updated Section 2 Naming Files with note regarding maximum allowed length for file name. Updated the title to Section 3.5 Tax Calculation Results to include zip look up results. Updated table in Section 8.1 Input File to include zip look up calculation data. Removed Request Type as a default from the table in Section 8.3 Default Values. Updated description in Section 8.8.12 Specifying Incorporated. Updated Section 8.8.30 Specifying Default Optional Reporting Fields and Section 8.8.31 Specifying Extended Optional Reporting Fields. Added note regarding federal level exemptions to 8.8.34 Specifying Exemption Tax Level. Added Section 8.9 Zip Lookup Requests. Updated Section 8.1 Input File to include additional columns for safe harbor overrides for traffic studies functionality. Also, added Section 8.8.37 Specifying Safe Harbor Overrides for Traffic Studies. Updated Section 3.3.4 Handling of Optional Files, Section 3.5.2 Report Files and added Section 8.10 Bridge Conference File to support the ability to calculate taxes for conference bridges. All references to ‘reverse’ tax calculations in AFC SaaS Standard have been updated and renamed to reflect the current naming convention which is ‘tax inclusive’ calculations. As a result, all request type values in Section 8.1 Input File and 8.8.1 Specifying Request Type have been updated and renamed. Updated Section 8.8.8 Specifying Transaction Charge with details related to support for Excel’s currency/numeric format in the charge field/column. Date Version Description 03/09/2017 0034 04/24/2017 0035 05/19/2017 0036 08/28/2017 0037 10/25/2017 0038 02/23/2018 0039 04/25/2018 0040 5/25/2018 0041 6/25/2018 7/25/2018 8/24/2018 0042 0043 0044 9/25/2018 0045 10/25/2018 11/21/2018 0046 0047 Added note in Section 8.8.28 Private Line (Point-to-Point) to address support of adjustment calculations with private line feature. Updated Section 8.2.1 Specifying Exemption and Section 8.8.34 Specifying Exemption Tax Type with note regarding availability of wildcard character for tax types. Release number and version updates. Added notes to Section 4.1 Uploading the ftp.zip and Section 8.8.24 Specifying Invoice Number. Updates throughout tables in Section 3.5 Tax Calculation Results. Release number and version updates. Updated Section 8.8.11 Specifying Sale Type. Release number and version updates. Added note related to timestamp/invoice date passed in Section 8.8.7 Specifying Transaction Date. Release number and version updates. Updated Avalara contact information (address and support site). Removed Appendix D – Avalara Product Names. Updated Section 8.8.10 Specifying Lines to include rounding information for subscription line count values. Updated information throughout Section 8.2.2 Category Exemptions and added Section 8.8.38 Specifying Exemption by Tax Category Scope. Made release number and version updates. Updated information throughout Section 8.2.2 Category Exemptions and removed Section 8.8.38 Specifying Exemption by Tax Category Scope. Made release number and version updates. Added URL for accessing public resources in sections 1. Introduction and 5. Transaction Mapping Guidelines. Updated table in section 3.5.2 KMLR150117AA.zip - Report Files. Updated values in several tables throughout section 8.8 Transaction Specifications. Added error codes -41 through -48 in section 10. Appendix B – AFC Error Codes. Made release number and version updates. Made release number and version updates. Made release number and version updates. Updated section 8.2 Exemption File. Made release number and version updates. Updated Avalara contact information. Made release number and version updates. Made release number and version updates. Made release number and version updates. Table of Contents 1. Introduction .................................................................................................................. 1 2. Naming Files .................................................................................................................. 1 2.1 3. Compliance Month ................................................................................................................... 2 AFC FTP Site................................................................................................................... 2 3.1 Accessing the FTP Site .............................................................................................................. 2 3.2 Logging on to the FTP Site......................................................................................................... 2 3.3 Submitting a Request................................................................................................................ 3 Primary File – Transaction Batch Data ............................................................................... 3 Extended Format – Excel, CSV ........................................................................................... 4 Fixed Format – CDF ........................................................................................................... 4 Handling of Optional Files ................................................................................................. 4 3.4 Transferring Files To and From the FTP Site............................................................................... 6 3.5 Tax Calculation Results ............................................................................................................. 7 KMLS150117AA.zip - Compliance Files .............................................................................. 7 KMLR150117AA.zip - Report Files...................................................................................... 7 KMLE150117AA.zip - Status Files ....................................................................................... 8 4. Web Interface ................................................................................................................ 9 4.1 Uploading the ftp.zip .............................................................................................................. 10 4.2 Retrieving Files ....................................................................................................................... 12 4.3 Notifications ........................................................................................................................... 13 5. Transaction Mapping Guidelines ....................................................................................... 13 6. Frequently Asked Questions............................................................................................. 14 7. Support ....................................................................................................................... 14 8. Appendix A – Extended Format: Excel and CSV.................................................................... 15 8.1 Input File ................................................................................................................................ 15 8.2 Exemption File........................................................................................................................ 18 Exemption File Updates .................................................................................................. 18 Overview of Exemptions ................................................................................................. 19 Exemption Fields............................................................................................................. 20 8.3 Transaction Default Values ..................................................................................................... 23 AF C S aaS S t a n d a r d U s e r M a n u a l |i Copyright 2018 Avalara, Inc. 8.4 Transaction File Sample .......................................................................................................... 24 8.5 Default File Sample................................................................................................................. 24 8.6 Specifying a Tax Jurisdiction.................................................................................................... 24 Jurisdiction Hierarchy...................................................................................................... 25 Jurisdiction Data Types.................................................................................................... 25 Jurisdiction Data Type Hierarchy ..................................................................................... 26 8.7 Getting the Right Tax Jurisdiction for Local Taxation................................................................ 27 8.8 Transaction Specifications....................................................................................................... 27 Specifying Request Type.................................................................................................. 27 Specifying Jurisdiction PCode .......................................................................................... 28 Specifying Jurisdiction Address ........................................................................................ 28 Specifying Jurisdiction FIPS Code ..................................................................................... 29 Specifying Jurisdiction NPANXX ....................................................................................... 30 Specifying Transaction / Service Pair................................................................................ 30 Specifying Transaction Date ............................................................................................ 31 Specifying Transaction Charge......................................................................................... 31 Specifying Customer Type ............................................................................................... 32 Specifying Lines............................................................................................................... 32 Specifying Sale Type........................................................................................................ 32 Specifying Incorporated .................................................................................................. 32 Specifying Level Exemptions............................................................................................ 33 Specifying the Regulated Flag .......................................................................................... 33 Specifying Minutes.......................................................................................................... 33 Specifying Debit Flag ....................................................................................................... 34 Specifying Service Class ................................................................................................... 34 Specifying Lifeline Flag .................................................................................................... 34 Specifying Facilities Flag .................................................................................................. 35 Specifying Franchise Flag................................................................................................. 35 Specifying Business Class................................................................................................. 35 Specifying Company Identifier ......................................................................................... 35 Specifying Customer Number .......................................................................................... 36 AF C S aaS S t a n d a r d U s e r M a n u a l | ii Copyright 2018 Avalara, Inc. Specifying Invoice Number .............................................................................................. 36 Specifying Discount Type................................................................................................. 36 Specifying Exemption Type.............................................................................................. 37 Specifying Adjustment Method ....................................................................................... 38 Specifying Private Line (Point-to-Point)............................................................................ 38 Specifying Proration ........................................................................................................ 39 Specifying Default Optional Reporting Fields ................................................................... 39 Specifying Extended Optional Reporting Fields ................................................................ 39 Specifying Exemption Cross Reference Key ...................................................................... 41 Specifying Exemption Jurisdiction.................................................................................... 41 Specifying Exemption Domain ......................................................................................... 42 Specifying Exemption Scope............................................................................................ 42 Specifying Exemption Tax Level (Deprecated – Use Domain instead)................................ 43 Specifying Exemption Category ....................................................................................... 43 Specifying Exemption Exempt Non-billable Flag ............................................................... 44 Specifying Exemption Exempt Non-level-exemptible Flag ................................................ 44 Specifying Safe Harbor Overrides for Traffic Studies ........................................................ 44 8.9 Zip Lookup Requests ............................................................................................................... 46 Zip Lookup Input File....................................................................................................... 46 Zip Lookup Results .......................................................................................................... 47 Zip Lookup Specific Transaction Specifications ................................................................. 47 8.10 Bridge Conference File............................................................................................................ 49 9. Appendix A – Fixed Format: CDF....................................................................................... 50 10. Appendix B – AFC Error Codes .......................................................................................... 52 AF C S aaS S t a n d a r d U s e r M a n u a l | iii Copyright 2018 Avalara, Inc. 1. Introduction AvaTax for Communications (AFC) SaaS Standard is a tax-rating service bureau. It provides the necessary link to allow you to transfer files to and from Avalara for processing by the AFC server. AFC SaaS Standard provides two ways to connect to the AFC server - by using a file-transfer protocol (FTP) connection through an existing account and typing ‘ftp.billsoft.com’ at the prompt within the FTP session or by connecting to the web interface at https://ftp.billsoft.com. For sample files and ftp scripts, see the samples folder and other resources at this URL: https://github.com/Avalara/Communications-Developer-Content/tree/master/afc_saasstd_tax. Once your file has been uploaded to the server, AFC begins immediate processing of your data. AFC SaaS Standard and the AFC server are online - 24 hours a day, 7 days a week - to process your data. 2. Naming Files Uploaded files MUST be named using the following naming conventions for the base name of the file. KML150117AA.{ext} • • • • • • KML: 3 letter company code 15: Year the file is to be uploaded 01: Month in which you are processing 17: The day of the month the file was created AA: Unique identifier that allows for better tracking and maintaining of these files T: Special Designator indicating the file is a test run and should not be included in compliance filing. This is not required but is a good practice as it allows production reports and test reports to be distinguished. Note: In addition to the naming convention guidelines, please be aware that the maximum allowed length for a file name is 19 bytes. The following formats / extensions are supported: • • Extended Formats o Excel o Comma-Separated Fixed Format o Customer Detail File .xls,.xlsx .csv ABC151116AA.CSV .cdf When uploading your file to the online ftp site (see Uploading the ftp.zip), it must be compressed (i.e., “zipped”) into a file named ftp.zip in order to be processed automatically. AF C S aaS S t a n d a r d U s e r M a n u a l | 1 of 54 Copyright 2018 Avalara, Inc. 2.1 Compliance Month The filename is generally the best approach for identifying which tax month the request applies to. If the billing cycle is for October 2015, then the name ABC1510NN would allow multiple submissions to be aggregated together for compliance filing. General Rules: • • Do not mix transactions from different billing cycles in the same request. Designate test data by adding a T to the filename. For example, if ABC1510NN is the normal designation, use ABC1510NNT for testing. 3. AFC FTP Site 3.1 Accessing the FTP Site AFC SaaS Standard provides two ways to connect to the AFC FTP server - by using a secure file-transfer protocol (SFTP) or file-transfer protocol (FTP) connection through an existing account and typing ‘ftp.billsoft.com’ at the prompt within the FTP session or by connecting to the web interface at https://ftp.billsoft.com. Note Concerning FTP Client Software Please be aware that web browsers (Microsoft Internet Explorer, Firefox, etc.) cannot be used for uploading and downloading files via FTP to the AFC FTP site. A FTP client application must be used to transfer files to and from the AFC FTP site when using our service as FTP. Windows users: Microsoft does not currently include convenient FTP client software in its operating systems. It is assumed you either own a third-party FTP client application such as WS_FTP (a shareware version of which can be downloaded from http://www.ipswitch.com), or that you are comfortable accessing FTP sites using command-line syntax. Linux users: If using a Linux system to transfer your call-data files, you can use any number of free FTP clients to contact the AFC FTP site, such as WXFTP, or you can use command-line syntax. 3.2 Logging on to the FTP Site To log on to the AFC FTP site, you will need the following information: HOSTNAME/ADDRESS: ‘ftp.billsoft.com’ within a FTP session or via the web at https://ftp.billsoft.com AF C S aaS S t a n d a r d U s e r M a n u a l | 2 of 54 Copyright 2018 Avalara, Inc. USER ID: Your User ID is created and provided to you. Please refer to the Welcome to Avalara email or contact communicationsupport@avalara.com for your organization’s assigned User ID. PASSWORD: Your organization’s login password is also provided by your Avalara technical support contact. For future reference, you may make note of your login details in spaced provided below. User ID: _____________________________ Password: _____________________________ Company Code: _____________________________ 3.3 Submitting a Request A single ftp.zip file will be submitted containing one and only one primary file and one or more optional files. General Submission Rules • • • Files submitted must be at the root-level within the zip file and cannot contain any other folders. The data must be compressed before you upload it for processing. The AFC FTP server uses PKZip/PK-Unzip version 2.04 for compressing and decompressing files. If you prefer using a Windows-based compression utility, you can use a product such as WinZip, which is compatible with the version 2.04 of PK-Zip/PK-Unzip. An account can only process a single request at a time. If additional requests are received before the first request has been completed, they will be rejected. Primary File – Transaction Batch Data The primary file contains all transactions to be processed and can be either Fixed Format (.cdf) or Extended Format (.csv/Excel). The naming convention for the primary file must be named correctly and uniquely. Submitting the same file name will cause the file to be rejected. • • • • • • • The 1st through the 3rd characters in the filename should begin with your company's three-letter code. The 4th and 5th characters in the filename should be the current year (2-digits). The 6th and 7th characters are the current month. The 8th and 9th characters are the current day. The 10th through the 13th characters are your unique files identifiers. Please note that ‘T’ is reserved for test files. The final character must be ‘T’ if this a test file. (optional or preferred) The file extension must be a supported extension. AF C S aaS S t a n d a r d U s e r M a n u a l | 3 of 54 Copyright 2018 Avalara, Inc. Thus, an example of a correctly named file is KML150117AA.CSV, where KML is the three-letter code for the company, 15 is the year, 01 is the month and 17 is the day. AA indicates it is the first file uploaded that day, and .CSV indicates it is a comma delimited file for processing by AFC. Refer to the Compliance Month section for additional details on compliance processing as well as the importance of naming for compliance purposes. Extended Format – Excel, CSV Extended format supports Excel and CSV (Comma-Separated Values) files. The contents and columns are identical and are discussed in Appendix A – Extended Format: Excel and CSV File Format for additional details. Fixed Format – CDF The fixed format, or CDF format, supports a limited number of transaction options and is intended for basic transaction processing. Please refer to Appendix B – Fixed Format: CDF File Format for additional details. Handling of Optional Files Both Extended and Fixed format processing supports several different types of optional files that can be embedded in the zip file ftp.zip or persisted in your account. Supported Optional Files Type Extension Override File .ovr Exemption File .exm Bundle File .bdl Reference • Specify a filename by naming the file with an .ovr extension. • To make the Override File a persisted file, please contact communicationsupport@avalara.com to proceed. • To embed an Override File, place the Override File into your ftp.zip file along with an Extended Format input file. • Also, contact communicationsupport@avalara.com for more information on the RLM (Rate and Logic Modifier) Tool for creating and/or maintaining override files. • Specify a filename by naming the file with an .exm extension. • To make the Exemption File a persisted file, please contact communicationsupport@avalara.com to proceed. • To embed an Exemption File, place the Exemption File into your ftp.zip file along with an Extended Format input file. • Refer to Exemption File for additional details. • Specify a filename by naming the file with a .bdl extension. • To make the Bundle File a persisted file, please contact communicationsupport@avalara.com to proceed. AF C S aaS S t a n d a r d U s e r M a n u a l | 4 of 54 Copyright 2018 Avalara, Inc. Supported Optional Files Type Extension Exclusion File .exc CustomSort Configuration File customsort.cfg Reference • To embed a Bundle File, place the Bundle File into your ftp.zip file along with an Extended Format input file. • Contact communicationsupport@avalara.com for more information on the Bundler Tool for creating and/or maintaining bundle files. • Specify a filename by naming the file with an .exc extension. • To make the Exclusion File a persisted file, please contact communicationsupport@avalara.com to proceed. • To embed an Exclusion File, place the Exclusion File into your ftp.zip file along with an Extended Format input file. • Refer to TM_00556_Exclusion File Formats for additional information or details. • To make the customsort.cfg file a persisted file, please contact communicationsupport@avalara.com to proceed. Note: Persisting the customsort.cfg file is the preferred method of generating the Custom Sort report. • To embed customsort.cfg, place the customsort.cfg file into your ftp.zip file along with the input file. • Refer to Section 1.2 of TM_00405_AFC Custom Sort Utility User Manual for additional information or details. A request can be made to add a persisted optional file from an authorized representative of the owner of the account. Please send the request, along with the file, to communicationsupport@avalara.com. Your account will be updated with the persisted file, and it will apply to all future batch processing. An embedded optional file is only applied to the current set of transactions contained within the ftp.zip file. Order of handling – Persisted vs Embedded When both a persisted optional file exists and the same type of optional file is embedded in the zip file, the embedded file will be used. This is designed to support clients testing new files or having special processing for certain batch files without having to update the persisted file. Note: All optional files (embedded and persisted) used in the transactions are returned in the report zip. AF C S aaS S t a n d a r d U s e r M a n u a l | 5 of 54 Copyright 2018 Avalara, Inc. 3.4 Transferring Files To and From the FTP Site Once you are connected to the AFC FTP site, you should change to the directory that has the same name as your company’s three-character code. You are now ready to send your file (which, again, must be named ftp.zip) for processing (see image below). When successfully connected to the AFC FTP site and changed to your company's filetransfer directory, you can send your ftp.zip file for processing. You can ignore the index files. Your uploaded file should begin processing within 30 seconds after you finish putting it on the FTP site. When your file has finished processing, you can either download the output (or "result" file) from the AFC FTP or get it from the https://ftp.billsoft.com site. This feature of the AFC SaaS Standard process allows your technical personnel to upload via FTP and your destination personnel (accountant, etc.) to download the result files via the web interface. The result file will have a similar name to the input file you uploaded, except that the first character after the three letter company code (in the file name) will be an "R" - indicating it is a result file. For example, if your uploaded ftp.zip file contained a file called KML150117AA.CSV, the result file (for downloading) would be called KMLR150117AA.ZIP. If the input file you upload is small, you can simply remain connected to the FTP site and wait for the file to be processed. Otherwise, you should repeat the above steps to connect and log on to the FTP site, and you can then get your result file. AF C S aaS S t a n d a r d U s e r M a n u a l | 6 of 54 Copyright 2018 Avalara, Inc. 3.5 Tax Calculation Results The following zip files would be produced if a file with the base name KML150117AA is uploaded. KMLS150117AA.zip - Compliance Files Compliance Files File Name Description KML150117AA.ssf* Summarized standard billable tax report. KML150117AA.nba* Summarized Non-billable tax report (as applicable). KML150117AA.nca* Summarized Non-compliance tax report (as applicable). *This output file is also available in CSV format; however, the option to generate the CSV format or version must be turned on. To request this option, please contact communicationsupport@avalara.com for assistance. Please note that the CSV formats are available in the Report Files output zip file (section 3.5.2) KMLR150117AA.zip - Report Files Report Files File Name Description KML150117AA.csf Summarized fixed position customer info report. Produced for clients configured for standard compliance reporting. KML150117AA.tsr* Transaction/Service Jurisdiction Report. By default, all clients will receive the tsr report. KML150117AA.tsr.csv** KML150117AA._audit.tsr.csv*** KML150117AA.rtr KML150117AA._audit.rtr.csv*** KML150117AA _ASCIILOG.CSV Tax Inclusive Transaction/Service Jurisdiction Report (as applicable). Produced if client has requested the rtr report. Contents of the tax data log converted to a comma-delimited text file with header row included. Refer to Section 5.3.1 asciilog.exe in TM_00101_AFC User Manual Telecom.pdf for more information on this report. Note: Clients wishing to receive this report must submit a request to communicationsupport@avalara.com for configuration to add this to the list of reports. EZTax.license.rpt Detailed version of the Transaction Count Report. Provides a count of transactions processed by transaction/service pair. KML150117AA.ntl Transaction/Service data that was processed but did not generate any taxes. {output_filename_format}.rpt Custom Sort report metrics. Provides details of the Custom Sort processing. {output_filename_format} is defined in customsort.cfg. {output_filename_format}_nca.csv Non-compliance Custom Sort Report (as applicable based on customsort.cfg settings). {output_filename_format} is defined in customsort.cfg. AF C S aaS S t a n d a r d U s e r M a n u a l | 7 of 54 Copyright 2018 Avalara, Inc. Report Files File Name Description {output_filename_format}_nba.csv Non-billable Custom Sort Report (as applicable based on customsort.cfg settings). {output_filename_format} is defined in customsort.cfg. {output_filename_format}_ssf.csv Compliance Custom Sort Report. {output_filename_format} is defined in customsort.cfg. KML150117AA.csv Request in comma delimited format. KML150117AA_Default.csv Request defaults in comma delimited format (as applicable). KML150117AA_conversion.rpt Conversion report. Generated if input file is in Excel format. Convert excel to comma delimited. KML150117AA_dtl.rpt Detailed log report. This matches SaaS Pro detailed log report. KML150117AA.CDF_dtl.csv KML150117AA_dtl.rpt.csv** KML150117AA_error.rpt Processing error report. Produced if errors occur during processing. Report captures the specific error message and the input line that failed processing. KML150117AA_summary.rpt Processing summary report. KML150117AA.ssf.csv** Summarized standard billable tax report. KML150117AA.nba.csv** Summarized Non-billable tax report (as applicable). KML150117AA.nca.csv** Summarized Non-compliance tax report (as applicable). *This output file is also available in CSV format; however, the option to generate the CSV format or version must be turned on. To request this option, please contact communicationsupport@avalara.com for assistance. **This CSV format version of the file is generated and sent in addition to the existing output format version only if the option has been activated. ***The audit version of the report contains two additional columns, Start Date and End date, which provide a timestamp for the report and headers for each column of data are included as well. Note: All optional files (embedded and persisted) used in the transactions are returned in the report zip. Please reference Handling of Optional Files for additional information and details. KMLE150117AA.zip - Status Files Status Files File Name Description Read_err.sta Reports problems encountered while reading the input file. Problems might relate to invalid transaction/service type pairings or an invalid input file. Taxer.sta Reports status during taxing routines. Status messages pertaining to successful or unsuccessful insertion of overrides or jurisdiction not found. AF C S aaS S t a n d a r d U s e r M a n u a l | 8 of 54 Copyright 2018 Avalara, Inc. Status Files File Name Description Sorter.sta Reports status during sorting routines. Status messages pertaining to successful or unsuccessful sort after taxation has occurred. KML150117AA_converter.sta Applies to excel input files. If an error occurs during conversion from Excel to csv format, this file will be generated with the error message. KML150117AA_batch.sta Status from batch processor. Outputs column mappings and any informational, warning or error level messages. Customsort_log.sta Reports status during custom sort processing. Contains processing steps for the sort and any errors that may have occurred. 4. Web Interface AFC SaaS Standard is accessible via web interface at https://ftp.billsoft.com. Please follow the steps provided to log in. Step Action/Result 1 Type https://ftp.billsoft.com in the web browser. The home page appears. 2 3 4 Enter the username in the Username field. Enter the password in the Password field. Click Sign In. Once logged in, the File Manager window appears. You will be able to see all of the online products which your organization is currently subscribing to. AF C S aaS S t a n d a r d U s e r M a n u a l | 9 of 54 Copyright 2018 Avalara, Inc. Step 5 4.1 Action/Result Select and click the appropriate client folder such as DMO, which is the example within the screenshot. All previous output files ran in previous days or sessions will also be visible after clicking on the folder. You can confirm this by viewing the date or timestamp for each. Uploading the ftp.zip Once on the web interface, follow the steps below to upload the ftp.zip file. Note: Please be aware that some functions or options are disabled and cannot be clicked or selected. Disabled options are grayed-out in appearance and users do not have rights to access or utilize those particular functions. Step 1 Action/Result Click the green Add files option to open the Choose File to Upload window to your local directory or the location where the ftp.zip you previously created is stored. AF C S aaS S t a n d a r d U s e r M a n u a l | 10 of 54 Copyright 2018 Avalara, Inc. Step Action/Result 2 Highlight and double-click the filename or click Open. 3 Click the blue Start upload or the blue Start option. The upload process will begin and status of your upload will appear as well as verification that the upload was successful near the top of the window shaded in green. AF C S aaS S t a n d a r d U s e r M a n u a l | 11 of 54 Copyright 2018 Avalara, Inc. Step 4 4.2 Action/Result Once completed, the output files or results will appear (such as the one highlighted in blue in the screenshot.) Retrieving Files Please follow the steps provided below in order to retrieve or review files. Step 1 2 Action/Result View the completed files processed and locate the file with appropriate date and timestamp. Highlight or double-click the file you wish to open. AF C S aaS S t a n d a r d U s e r M a n u a l | 12 of 54 Copyright 2018 Avalara, Inc. Step 3 Action/Result Select the Save or Save as option in the window. Note: The file must be saved. If the file is opened and closed without being saved, it will no longer be available on the FTP site to download and save for your records. 4.3 Notifications The system is set up to automatically provide email notification of updated files and status; however, please contact communicationsupport@avalara.com with any questions or for additional assistance with this feature. 5. Transaction Mapping Guidelines AFC uses a system of numbers to represent the Transaction Types and Service Types for the service you wish to tax. Passing valid combinations of Transaction Type / Service Type pairs provides AFC part of the information necessary to produce the appropriate taxes for a specific jurisdiction. For more information about mapping guidelines, see the document AFC Telecom Mapping Guidelines.pdf, which is available for download at this URL: https://github.com/Avalara/Communications-DeveloperContent/tree/master/afc_saasstd_tax/support_docs AF C S aaS S t a n d a r d U s e r M a n u a l | 13 of 54 Copyright 2018 Avalara, Inc. 6. Frequently Asked Questions I have a back log of data files I need processed. Can I send them all at once? No. You can send only one file at a time, and you must wait for that data to be processed before uploading another file. Otherwise, you face the risk of the data from one file appending or even overwriting the data from another file. I uploaded my file quite a while ago, and I still don't see any result file. What's wrong? The most likely reason for this is an incorrect filename or an incorrect file format. The file must be in the correct format for the system to process it. Likewise, the file must be named correctly for the system to recognize it (see the appropriate sections in this manual regarding the naming of files). The filename can be especially tricky: the actual .CSV or Excel file and .ZIP file (as they appear on your system’s hard drive) must be named according to the afore-mentioned file-naming convention. Solution: if, after verifying your file is both formatted and named correctly, you are still having problems - call or email your Avalara technical support contact. I’ve connected to the AFC FTP server, but I cannot view the contents of my directory. If you’re unable to change directories, or if you are unable to list the contents of your transfer directory or transfer files to/from the FTP server, you are most likely being denied access to the AFC SaaS Standard server by a firewall or proxy server. 7. Support Avalara strives to provide the very best in customer support. If you should need assistance or further information when contacting the AFC FTP site or transferring files, please contact us at communicationsupport@avalara.com. If you have an urgent matter outside of the hours of 8 AM to 5 PM CST Monday through Friday, please leave a message on the Avalara Technical Support contact's voice mail at (913) 221-7320. AF C S aaS S t a n d a r d U s e r M a n u a l | 14 of 54 Copyright 2018 Avalara, Inc. 8. Appendix A – Extended Format: Excel and CSV 8.1 Input File The columns in the Excel and CSV file formats are the same in each format. Column headers are the first row in each file which describe the data in that particular field or column. Field Request Type BillTo PCode Origination PCode Termination PCode BillTo Country BillTo State BillTo County BillTo Locality BillTo ZipCode BillTo ZipP4 Origination CountryI Origination State Origination County Origination Locality Origination ZipCode Origination ZipP4 Termination Country Termination State Termination County Termination Locality Termination ZipCode Termination ZipP4 BillTo Fips Code Origination Fips Code Termination Fips Code BillTo NpaNxx Origination NpaNxx Termination NpaNxx *Required Value List Reference R CalcTaxes CalcAdj CalcIncl CalcInclAdj Specifying Request Type OR Specifying Jurisdiction PCode OR Specifying Jurisdiction Address OR Specifying Jurisdiction Fips Code OR Specifying Jurisdiction NpaNxx Transaction Type R Specifying Transaction / Service Pair Service Type R Specifying Transaction / Service Pair Date R Charge R YYYYMMDD Specifying Transaction Date Specifying Transaction Charge AF C S aaS S t a n d a r d U s e r M a n u a l | 15 of 54 Copyright 2018 Avalara, Inc. Field *Required Value List Reference Customer Type SR Business (default) Residential Industrial Senior Citizen Specifying Customer Type Lines D Integer (default is 0) Specifying Lines Sale D Sale (default) Resale Specifying Sale Type Incorporated D True (default) False Specifying Incorporated Federal Exempt Federal PCode State Exempt State PCode County Exempt County PCode Local Exempt Local PCode D Regulated D True (default) False Specifying Regulated Flag Minutes D Number (default is 0) Specifying Minutes Debit D True False (default) Specifying Debit Flag Service Class D Local (default) Long Distance Specifying Service Class Lifeline D True False (default) Specifying Lifeline Flag Facilities D True (default) False Specifying Facilities Flag Franchise D True (default) False Specifying Franchise Flag Business Class D CLEC (default) ILEC Specifying Business Class Company Identifier D Specifying Company Identifier Customer Number D Specifying Customer Number Invoice Number D Specifying Invoice Number Specifying Level Exemptions AF C S aaS S t a n d a r d U s e r M a n u a l | 16 of 54 Copyright 2018 Avalara, Inc. Field *Required Value List Reference Discount Type D None (Default) Retail Product Manufacturer Product Account Level Subsidized Goodwill Specifying Discount Type Exemption Type D Adjustment Method D IsPrivateLine PrivateLineSplit IsProRated ProRatedPct D D Specifying Exemption Type Default (Default) Least Most Percentage allocation specified as a decimal in the range 0 to 1. Percentage allocation specified as a decimal in the range 0 to 1. Specifying Adjustment Method Specifying Private Line or Point-to-Point Specifying Proration Optional Optional4 Optional5 Optional6 Optional7 Optional8 Optional9 Optional10 OptionalAlpha1 D Specifying Optional Reporting Fields Key:{header} O Specifying Extended Optional Reporting Fields VoIP Old (Original Fed TAM) O TAM value specified as decimal between 0 and 1. Specifying Safe Harbor Overrides for Traffic Studies O TAM value specified as decimal between 0 and 1. Specifying Safe Harbor Overrides for Traffic Studies O TAM value specified as decimal between 0 and 1. Specifying Safe Harbor Overrides for Traffic Studies VoIP New (Override Fed TAM) Cellular Old (Original Fed TAM) Cellular New (Override Fed TAM) Paging Old (Original Fed TAM) Paging New (Override Fed TAM) *Required: • • R = Required OR = Only One Required (Remaining optional) AF C S aaS S t a n d a r d U s e r M a n u a l | 17 of 54 Copyright 2018 Avalara, Inc. • • SR = Strongly Recommended (Default, if applicable) O = Optional (No Default) D = Optional (Default, if applicable) • Please see Default Values for additional information on default parameters. Notes: • • • 8.2 Spacing is ignored in a field name. For example, [Request Type] and [RequestType] would be considered identical. Matching will ignore additional fields or characters beyond the listed value. Example: [Lines] and [Lines Count] would be considered identical. [Line Count] however would not be considered a valid column identifier, as it is missing the character [s]. Column headers are required and must be included in Excel and CSV format. Exemption File The exemption file is an optional input file that identifies tax type exemptions, category exemptions, or both. The name of the file is user defined, but the extension must be .exm. Note: While both a tax type and category exemption can be applied to the same transaction within the input file, the separate exemptions must be specified on individual rows within the exemption file. Please refer to Handling of Optional Files for additional information. Exemption File Updates New Fields – Effective September 2018 Scope – union, user supplied • One or more of the set { Federal, State, County, Local } Include Nonbillable – flag, user supplied • • True – nonbillable taxes can be exempted False – nonbillable taxes should not be included in exemption Domain – discrete, user supplied • • • Defines the level the taxing jurisdiction must match exemption jurisdiction One of the set { Federal, State, County, Local } Does not need to correlate to the tax level of the tax being exempted Ignore Level Exemptible - flag, user supplied • True (Default) - Tax type wildcard exemptions will exempt taxes tagged not level exemptible AF C S aaS S t a n d a r d U s e r M a n u a l | 18 of 54 Copyright 2018 Avalara, Inc. • False - Tax type wildcard exemptions will exclude taxes tagged not level exemptible from consideration The exemption handling has been redesigned to allow more flexibility in how they are used. Wherever possible backwards compatibility was maintained with the following exception: Category exemptions and wildcard tax type exemptions by default will no longer exempt nonbillable taxes. The new flag ExemptNB must be set to true if a client wishes to include nonbillable taxes. This change was made to protect clients from applying exemptions beyond the scope of the exemption certificate(s) for which the customer qualifies. If you have additional questions on why Avalara changed the default, please contact CommunicationSupport@avalara.com. Overview of Exemptions Setting up exemptions allows for exempting clients from taxes that would normally apply for a given product for either a specific jurisdiction or a jurisdictional region. Checklist for creating an exemption • • • • What - Is the exemption for a specific tax or for a category of taxes? o Listing of tax types and associated categories can be found in the Mapping Guideline. o An array of exemptions can be created if multiple tax types and/or categories apply. o Values of 0 or All defines wildcard for both tax type and categories.. Where - Does the exemption apply to a specific jurisdiction or to a jurisdiction region? o This defines the Scope. Regions are Federal (Country), State/Province, County, City. o You can define multiple regions for Scope such as (State + County + Local) When - At what level must the exemption match the taxing jurisdiction? o This defines the Domain. Domain can be one of (Federal, State, County, Local) o For example, if you wish to exempt Federal taxes only if the taxing jurisdiction is in Puerto Rico, then the Domain would be State and the Exemption would be defined for Puerto Rico. The federal taxes would then only be exempt when the taxing jurisdiction was in Puerto Rico. Who – Define the cross-reference for who the exemption will be applied to o Exemptions can be tied to transactions by one of the following: Customer Number Company Identifier Optional Alpha1 Exemption Type AF C S aaS S t a n d a r d U s e r M a n u a l | 19 of 54 Copyright 2018 Avalara, Inc. Exemption Fields Field Value List Reference [Cross Reference Key] Specifying Exemption Cross Reference Key [Jurisdiction] Specifying Exemption Jurisdiction TaxType Numeric Tax Type ID Or “All” Specifying Exemption Tax Type TaxCategory Numeric Category ID Or “All” Specifying Exemption Category Scope Numeric Scope Value -orText Scope Value(s) Specifying Exemption Scope Domain Numeric Tax Level ID -orText Domain Value Specifying Exemption Domain ExemptNB Flag – Boolean Specifying Exemption Exempt Non-billable Flag ExemptLvl Flag – Boolean Specifying Exemption Exempt Non-level-exemptible Flag Tax Type Exemption Sample File The samples provided show tax type exemption files processed and properly cross-referenced by the following key columns: • • Using Company Identifier and PCode The data within lines 2 – 3 of the previous input file are associated with the sample exemption file provided below. Company Identifier PCode Tax Type Domain Scope Company A 540000 18 0 Federal Company A 540000 64 1 Federal+State Using Customer Number and LinkTo The data within lines 2 – 3 of the previous input file are associated with the sample exemption file provided below. Customer Number LinkTo Tax Type Domain Customer 1 BillTo 18 0 AF C S aaS S t a n d a r d U s e r M a n u a l | 20 of 54 Copyright 2018 Avalara, Inc. • Customer 1 Origination 64 1 Customer 1 Termination 64 3 Using Customer Number and Address The data within lines 2 – 5 of the previous input file are associated with the sample exemption file provided below. Customer Number Customer 1 Country County Locality Zip Code USA Customer 1 FL Customer 1 USA Customer 2 USA Customer 2 Customer 2 State FL Cocoa Beach Brevard 32931 CA USA CA San Francisc o San Francisc o 94102 Tax Type 18 0 64 1 64 3 169 Federal 18 Federal 16 Local Domain Application of Jurisdiction for Exemptions The exemption jurisdiction should be defined at least to the Domain level specified. If it is not, the Domain will automatically shift upward to the level the exemption jurisdiction is defined at. So for example, if the Domain level is specified at city level, but the exemption jurisdiction provided is for the state of Colorado, the Domain level will shift to State and produce a match if the transaction taxing jurisdiction is in Colorado. Exemption Default Values Tax Type defaults (where applicable) Field Include Nonbillable Scope Domain Default True False Tax Level or Domain Tax Level Force Lvl Exempt True Special Condition Valid tax type specified Wildcard for tax type used One or the other is required for Tax Type exemptions. Domain overrides tax level if both are provided Wildcard for tax type used Category defaults (where applicable) Field Default Special Condition AF C S aaS S t a n d a r d U s e r M a n u a l | 21 of 54 Copyright 2018 Avalara, Inc. Include Nonbillable Scope False State+County+City All State Federal Domain If State or lower level jurisdiction If Country level jurisdiction If State or lower level jurisdiction If Country level jurisdiction Exemption Use Case Scenarios Scenario 001 - apply exemption to all cities within a state - billable only Client wants all tax categories of type 1 (Sales) exempt at local level for the state of Colorado (billable only). Scope local will exempt only local taxes. Domain state will match jurisdiction at the state level (CO). Nonbillable taxes will be excluded from consideration. TaxCategory Jurisdiction Scope ExemptNB Domain ExLvl 1 USA, CO, Boulder, Boulder 1024 (Local) false 1 (State) n/a Scenario 002 - apply exemption to all states, counties and cities within a country - include nonbillable Client wants all tax categories of type 5 (Connectivity Charges) exempt at state, county and local level for all states in the USA, billable or non-billable. Scope will exempt State, County and Local taxes. Domain Federal will match jurisdiction at the Federal level (USA). Non-billable taxes will be subject to exemption. TaxCategory Jurisdiction Scope ExemptNB Domain ExLvl 5 USA, TX 1792 (State+County+Local) true 0 (Federal) n/a Scenario 003 - apply multiple exemptions to all locations within a state Client wants billable Sales tax (1) and Use tax (49) exempt at state, county and city level for Washington. Scope will exempt State, County and Local taxes. Domain State will match jurisdiction at the State level (WA). TaxType Jurisdiction Scope ExemptNB Domain 1 USA, WA 1792 (State+County+Local) n/a 1 (State) n/a 49 USA, WA 1792 (State+County+Local) n/a 1 (State) n/a AF C S aaS ExemptLvl S t a n d a r d U s e r M a n u a l | 22 of 54 Copyright 2018 Avalara, Inc. Scenario 004 - exempt Federal tax only if taxing jurisdiction is within a state Client wants FUSF tax (18) exempt at Federal level but only if transaction is in Puerto Rico. Scope will exempt Federal taxes. Domain State will match jurisdiction at the State level (PR). TaxType Jurisdiction Scope ExemptNB Domain ExemptLvl 18 USA, PR 128 (Federal) n/a 1 (State) n/a Scenario 005 - exempt all taxes at Federal level except non-level exemptible Client wants all Federal taxes exempt at Federal level except those marked non-level exemptible. Scope will exempt Federal taxes. Domain will match at Federal level. Non-billable will be included. Taxes that are not level-exemptible will be excluded from consideration. TaxType Jurisdiction Scope ExemptNB Domain 0 USA, PR 128 (Federal) true 0 (Federal) false 8.3 ExemptLvl Transaction Default Values Clients that use the Excel or CSV format for the input file have the option of including a default file that will be used to specify what default values should be used. The file must be named Default.{ext} with the extension being either a valid Excel extension or csv for comma delimited. The default value for each column specified will be used when the input file does not include the column. If a customer-provided Default file is not uploaded, the following default values will be used. Field Default Customer Type Lines Sale Incorporated Federal Exempt State Exempt County Exempt Local Exempt Regulated Minutes Debit Service Class Lifeline Facilities Franchise Business Class Business 0 TRUE TRUE FALSE FALSE FALSE FALSE FALSE 0 FALSE Local FALSE TRUE TRUE CLEC AF C S aaS S t a n d a r d U s e r M a n u a l | 23 of 54 Copyright 2018 Avalara, Inc. 8.4 Transaction File Sample The order of columns is not important, but column headers are required. Lines Transaction Type Service Type Sale Incorporated Customer Number 100 0 19 6 True True Customer 1 20150715 100 0 19 30 True True Customer 1 Business 20150715 100 0 19 37 True True Customer 1 Business 20150715 100 0 19 577 True True Customer 1 446400 Business 20150715 100 0 19 6 True True Customer 2 CalcTaxes 446400 Business 20150715 100 0 19 30 True True Customer 2 CalcTaxes 446400 Business 20150715 100 0 19 37 True True Customer 2 CalcTaxes 446400 Business 20150715 100 0 19 577 True True Customer 2 Request Type Origination PCode Customer Type Date Charge CalcTaxes 540000 Business 20150715 CalcTaxes 540000 Business CalcTaxes 540000 CalcTaxes 540000 CalcTaxes 8.5 Default File Sample The order of columns is not important, but column headers are required. There should only be a single line of data indicated what default values to use. You need only define default values for columns that are not otherwise defined or that are different from the default values used by the service. Regulated Debit Service Class Lifeline Facilities Based Franchise Business Class True False False False 8.6 Local False CLEC Specifying a Tax Jurisdiction For AFC to calculate taxes for transactions correctly, it must first determine the taxing jurisdiction for the transaction in question. The tax laws of various jurisdictions complicate this. AFC currently supports multiple unique rules for determination of the correct tax jurisdiction. Jurisdiction determination is usually based upon three inputs to AFC: 1. The Service Address or the Bill To Number (BTN). 2. The termination location of the transaction (for telephone calls only) to be taxed. The number called, also known as the "To Number" or the "Termination number" usually specifies this. 3. The origination location of the transaction to be taxed. For telephone calls this is usually specified by the number called from, also known as the “From Number” or Origination number. The jurisdiction, for many telecommunications taxes applied by AFC, is determined by the Goldberg or "2 out of 3" rule. With this particular rule, the three jurisdiction inputs pointed out above are compared. If 2 of the 3 jurisdictions supplied match, that is the jurisdictions for which taxes are generated. It is slightly AF C S aaS S t a n d a r d U s e r M a n u a l | 24 of 54 Copyright 2018 Avalara, Inc. more complicated since there are four authority levels for which jurisdictions determination must be made (i.e. federal, state, county, and local), however; this brief discussion illustrates the concept. Remember, the Goldberg Rule although the most common, is only one of 10 rules specified for jurisdiction determination by taxing jurisdictions in the United States. Jurisdiction information can be supplied to the system in different ways. It can be supplied using a permanent jurisdiction code (PCode), using a FIPS Code, using an NPANXX, or using zip code and address information. AFC allows the user to identify the jurisdictions by any of these methods, thereby providing maximum flexibility. AFC allows the specification of jurisdiction information using any combination of these methods during the same session. Jurisdiction Hierarchy Clients have the option of specifying one, two or all three jurisdictions for a single transaction. If only one jurisdiction is specified, it will be used for all three. If two jurisdictions are specified, the following hierarchy will be used for determining which jurisdiction will be used to populate the missing jurisdiction. High Level Jurisdiction Order of Preference (by Transaction): 1. BillToPCode 2. Origination 3. Termination The following table of populating missing jurisdiction from jurisdictions is provided. Missing Jurisdiction Hierarchy Application Resulting Jurisdictions Used BillTo Origination Termination Uses Origination Uses BillTo Uses BillTo Orig, Orig, Term BillTo, BillTo, Term BillTo, Orig, BillTo Jurisdiction Data Types PCode PCodes are permanent jurisdiction codes which Avalara provides and allow AFC software users to populate their databases with jurisdiction information. With PCodes, AFC clients can populate their customer records with jurisdiction information and never worry about changes of jurisdiction codes. If a jurisdiction code changes, AFC re-maps the PCodes so clients are not affected. This allows AFC clients to populate client records with a PCode. For more information refer to Specifying Jurisdiction PCode. Address AF C S aaS S t a n d a r d U s e r M a n u a l | 25 of 54 Copyright 2018 Avalara, Inc. The accuracy of the ZIP code method depends upon the amount of data provided for the address as well as the user’s ability to choose the correct taxing jurisdiction zip code and address. AFC databases contain numerous duplicate zip codes that cross not only taxing jurisdiction boundaries, but boundaries of localities as well. Providing a complete address along with the zip code insures the best match possible. When address information is missing, AFC returns taxes based upon the first match of the provided input information. It is appropriate to use the zip code interface or PCode methods for transactions where the jurisdiction can be positively identified by the calling application. Examples of this type of transaction are product sales and Internet usage. For more information refer to Specifying Jurisdiction Address. FIPS Code FIPS Codes are issued by the National Institute of Standards and Technology (NIST). AFC provides internal translation tables from FIPS Codes to PCodes, so that using FIPS Codes is almost as fast and accurate as using PCodes. Some special taxing districts are not identified in separate FIPS codes, so there is some loss of accuracy, but the majority of transactions will produce the same tax results with FIP Codes as with PCodes. For more information refer to Specifying Jurisdiction Fips Code. NPANXX The NpaNxx is the first 6 digits of a phone number. For more information refer to Specifying Jurisdiction NpaNxx. Jurisdiction Data Type Hierarchy If a client supplies more than one data type for a single jurisdiction, the following hierarchy will be used to determine which jurisdiction data type is used for that jurisdiction. Jurisdiction Data Type Order of Preference (by Jurisdiction): 1. PCode 2. Address 3. FIPs Code 4. NpaNxx For example, if a transaction has both an OriginationPCode and an OriginationNpaNxx specified, the OriginationPCode value will be used for the Origination Jurisdiction. AF C S aaS S t a n d a r d U s e r M a n u a l | 26 of 54 Copyright 2018 Avalara, Inc. 8.7 Getting the Right Tax Jurisdiction for Local Taxation It is important to get the end users location correct for local taxation. People tend to know what they are charged for local taxes. These taxes also have a tendency to change from one neighborhood to the next. Avalara provides a comma delimited ASCII file to aid with entry of customers in your system and to help insure the correct taxing jurisdiction is setup. The file is "all_adr.txt". This comma delimited ASCII files is provided to allow Avalara clients to populate database tables in their system with this information. The all address (all_adr.txt) file is a cross-reference of locations to PCodes. The format of the files is illustrated below. The "all_adr.txt" file format and example follows: Pcode,P/A,Country,State,County,City,"Zip code range start","Zip code range end" 3346800,0,USA,PA,LANCASTER,BART,17503,17503 3346900,0,USA,PA,LANCASTER,BAUSMAN,17504,17504 3347000,0,USA,PA,LANCASTER,BIRD IN HAND,17505,17505 3347100,0,USA,PA,LANCASTER,BOWMANSVILLE,17507,17507 3347200,0,USA,PA,LANCASTER,CHRISTIANA,17509,17509 3347300,0,USA,PA,LANCASTER,CHURCHTOWN,17555,17555 3347400,0,USA,PA,LANCASTER,CONESTOGA,17516,17516 3347500,0,USA,PA,LANCASTER,DRUMORE,17518,17518 3347600,0,USA,PA,LANCASTER,EAST EARL,17519,17519 3347700,0,USA,PA,LANCASTER,ELM,17521,17521 3347800,0,USA,PA,LANCASTER,GAP,17527,17527 8.8 Transaction Specifications Specifying Request Type The request type tells the engine what type of calculation should be performed on the transaction data. The request type is independent of the jurisdiction type, and supports all jurisdiction specifications. Please refer to the table below to view the request types which are supported. Request Type Value Description CalcTaxes Perform a standard tax calculation. CalcAdj Calculate an adjustment for a standard tax calculation. All transaction data, including charge and transaction date, should be identical to the standard calculation. Supports Specifying Adjustment Method and Specifying Discount Type. CalcIncl Perform a tax inclusive calculation. The desired total (charge + taxes) should be placed in the “Charge” column. The tax calculation method will determine the “base charge” that is needed such that (base charge + taxes calculated = desired total). Notes: • The desired total must be a positive value sufficiently large to cover any fixed taxes that may apply. AF C S aaS S t a n d a r d U s e r M a n u a l | 27 of 54 Copyright 2018 Avalara, Inc. Request Type Value Description • The calculated base charge will be stored in the optional field as an unsigned long where: optional = (unsigned long)(base charge * 100) • Clients using tax inclusive calculations should not use the optional field or the data in the optional field will be overwritten. • The standard TSR report uses the calculated base charge. To add the original charge passed in, a request needs to be made to receive the RTR (Reconciliation Transaction/Service Report). CalcInclAdj Calculates an adjustment for a tax inclusive calculation. All transaction data, including charge and transaction date, should be identical to the tax inclusive calculation. Refer to CalcIncl Request Type for more details on tax inclusive calculations. Supports Specifying Adjustment Method and Specifying Discount Type. Specifying Jurisdiction PCode A PCode is a persisted numeric identifier for a taxing jurisdiction. It can represent anything from a country to a special taxing jurisdiction within a local taxing district, such as the Salado Public Library District in Bell, Texas. The value can be obtained from either using our Avalara Geo for Communications (AFC Geo) product or from parsing the PCode from the all_adr.txt file. Getting the Right Tax Jurisdiction for Local Taxation has more information on the format and contents of this file. Specifying Jurisdiction Address When using an address to specify the taxing jurisdiction, the more complete the information provided the more accurate the lookup will be. For most foreign nations, other than Canada and Brazil, the country is sufficient for taxation purposes. For USA and Canada, at a minimum the Country, State and Zip Code must be provided. If the address is for a USA Territory, it can be handled the same as a USA state by using the provided two byte state abbreviation. Supported USA Territory abbreviations are provided in the following table. Code Territory AS FM GU MH MP PR PW VI American Samoa Fed St of Micronesia Guam Marshall Islands Northern Mariana Islands Puerto Rico Palau US Virgin Islands Special Handling Notes Leave County blank Leave County blank AF C S aaS S t a n d a r d U s e r M a n u a l | 28 of 54 Copyright 2018 Avalara, Inc. For Canada, you may populate the 6 digit Postal Code in the Zip Code field (with or without a dash or space). Zip plus 4 (ZipP4) is for USA only. Supported Canadian Province and Territory abbreviations are provided in the following table. Code Territory AB BC MB NB NL or NF AB NS NT NU ON PE QC or PQ SK YT Alberta British Columbia Manitoba New Brunswick Newfoundland Alberta Nova Scotia Northwest Territories Nunavut Ontario Prince Edward Island Quebec Saskatchewan Yukon Territory A breakdown of the address fields are below. The Column Name should be prefixed with either BillTo, Origination or Termination (as applicable). ZipAddress Column Name Country State County Locality ZipCode ZipP4 Description 3 character ISO abbreviation State Abbreviation County name City name ZIP Code (5 digit USA, 6 digit Canada) ZIP Code extension (4 digit) The all_adr.txt file can be used to verify zip address data. Getting the Right Tax Jurisdiction for Local Taxation has more information on the format and contents of this file. Optionally, the Viewer in the AFC Manager can also be used for manual verification. Note: The country will default to USA if no country is specified. Specifying Jurisdiction FIPS Code “The Federal Information Processing Standards codes (FIPS codes) are a standardized set of numeric or alphabetic codes issued by the National Institute of Standards and Technology (NIST) to ensure uniform identification of geographic entities through all federal government agencies. The entities covered include: states and statistically equivalent entities, counties and statistically equivalent entities, named AF C S aaS S t a n d a r d U s e r M a n u a l | 29 of 54 Copyright 2018 Avalara, Inc. populated and related location entities (such as, places and county subdivisions), and American Indian and Alaska Native areas”. A FIPS Code may be used to identify a jurisdiction, but must follow the 10-digit numeric code with the following format: FIPS CODE FORMAT SSCCCPPPPP SS CCC PPPPP FIPS State Code FIPS County Code FIPS Place Code Specifying Jurisdiction NPANXX NPANXX 6 digit numbers may be used for specifying a jurisdiction. There are issues to be considered with using the NPANXX. 1. The first six digits of a toll free number do not constitute an NPANXX. Rather, these numbers are associated with a “ring to” number which is the number that is actually reached when the toll free number is dialed. The NPANXX of the “ring to” number should be used as the NPANXX for the toll free number. This replacement must be made before the information is passed to the AFC system. 2. Switches are capable of producing CDRs with account codes in place of a “Bill To” number, which is not related to an actual NPANXX. The user is required to convert this number to the actual NPANXX using data from the billing system before interfacing with AFC. 3. Use of NPANXX for determination of a taxing jurisdiction is generally considered not sufficient for local service. There is often an unacceptable rate of foreign exchanges that incorrectly map customers to the wrong local tax jurisdiction resulting in the wrong local taxes being calculated. NPANXXs exist for the U.S., Barbados, Canada, Guam, Mexico, Northern Mariana Islands, Puerto Rico, Trinidad & Tobago and the US Virgin Islands. These countries are on the North American dialing plan. Specifying Transaction / Service Pair AFC stipulates a unique pair of numbers for each Transaction and Service Type. The first number defines the Transaction Type and the second number defines the Service Type. Transaction Types and Service Types are combined (or “paired”) to uniquely describe a Valid Transaction / Service Pair for a transaction. Refer to the document TM_00505_AFC Telecom Mapping Guidelines.pdf for a complete list of all t/s pair mappings and product mapping guidelines. AF C S aaS S t a n d a r d U s e r M a n u a l | 30 of 54 Copyright 2018 Avalara, Inc. Specifying Transaction Date The Date field is normally populated with the bill date, invoice date or call date (as applicable) and may appear in any of the Standard Date and Time Format Strings for .NET Framework shown in the table below. Date Format Sample yyyymmdd 20160601 mm/dd/yyyy 06/01/2016 m/d/yyyy 6/1/2016 mm-dd-yyyy 06-01-2016 m-d-yyyy 6-1-2016 yyyy-mm-dd 2016-06-01 yyyy-m-d 2016-6-1 yyyy-mm-ddThh:MM:ss 2016-06-01T13:45:30 yyyy-m-dThh:MM:ss 2016-6-1T13:45:30 AFC compares this date to the effective date of each tax that applies to the transaction. Historical rates and effective dates are maintained and updated within AFC and it will return the correct tax information based upon the transaction date. The monthly updates assure that the rates and effective dates are current. Note: The invoice date passed to the server in the transaction by default is preserved as is. For example, if the date 1/1/2017 is passed, Avalara does not convert the time and will use 1/1/2017. It is recommended that clients not use modifiers on the invoice date. Specifying Transaction Charge For standard calculations, the Charge field specifies the amount of the transaction to be taxed and it may appear in any of the numeric or currency formats supported in Microsoft Excel. Please refer to the table shown below for specific examples of positive or negative charge amounts. Charge 1500 -1500 Examples 1500.00 1,500.00 $1,500 $1,500.00 -1500.00 -1,500.00 (1500.00) (1,500.00) ($1,500.00) For Tax Inclusive calculations, this field specifies the desired total (base charge + taxes). Please refer to Specifying Request Type for additional details on adjustments or tax inclusive calculations. AF C S aaS S t a n d a r d U s e r M a n u a l | 31 of 54 Copyright 2018 Avalara, Inc. Specifying Customer Type This field is used to specify the type of customer involved in the transaction. The customer type is selected from one of the following four Customer Types. Customer Type ID 0 1 2 Value Residential Business Senior Citizen 3 Industrial Description When transactions are made by a customer for home use. When transactions are made at a place of business When transactions are made by a customer who meets the jurisdiction requirements to be considered a senior citizen and qualify for senior citizen tax breaks. When transactions are made at an industrial business. Specifying Lines When local service is provided, a transaction should be generated with the Lines field populated with the number of lines the customer subscribes to. AFC uses this information for generation of per line taxes usually associated with local E911 charges and local telecommunications relay service taxes and other assorted taxes. Transaction Fields Column Name Lines Description Numeric : integer >= 0 (rounded to nearest integer using the half round up method) Specifying Sale Type Sale should be used for retail transactions. Resale should be used for wholesale transactions. Telecommunication companies are taxed on transactions made by their clients, which in some cases can be passed on or “resold” to their customers in part or in total. Resale is used to indicate whether the product or service transaction is final or if it is to be resold. To have exempt taxes available for reporting, exemption type 3 (Sales For Resale) should be used in combination with Resale. Sale Type ID 0 1 Value Resale Sale (Default) Description Only Resale/Wholesale taxes apply Standard taxes apply Specifying Incorporated The Incorp field is used to specify whether the customer involved in this transaction is inside or outside of the Local level designated as their location. The tax may or may not be affected by this designator depending upon whether or not the local level has taxes which would apply to the transaction/service type pair. Marking transactions as Incorporated = False will usually result in no local taxes returned. If not sure, the value True is the recommended setting to be used. Incorporated Flag AF C S aaS S t a n d a r d U s e r M a n u a l | 32 of 54 Copyright 2018 Avalara, Inc. Value True (Default) False Description Jurisdiction is inside an incorporated location. Jurisdiction is outside an incorporated location. Specifying Level Exemptions The tax logic has a flag that indicates whether it is level exemptible or not. Only those taxes which have been flagged to be level exemptible can be exempted through specifying a level exemption. The exemption PCode is the PCode associated with the jurisdictional level of the taxing authority that defines the tax. It is used to exempt all federal, state, county and / or local taxes. If the exemption PCode fields are not specified then all taxes are exempt at that level. The Exempt Level field to be used (set to True) should be chosen based upon the level of the tax to be exempted. Examples: If the desire is to exempt all New York state taxes, but not New Jersey (or other states), then the following would be used: Field Value State Exempt State PCode True 2502500 If the desire is to exempt all state taxes, then the following would be used: Field State Exempt State PCode Value True 0 Specifying the Regulated Flag The Regulated Flag is used to specify whether the telecommunication company and its services are regulated by the regulatory commission in the state of the service. Unless the seller is registered with the state regulatory commission as a rate-regulated, incumbent provider, all transactions should be Regulated = False. Field Regulated Flag Value True False (Default) Description Company is rate-regulated Company is not rate-regulated Specifying Minutes The Minutes (Call Duration) Field specifies the length of phone call in minutes, with one tenth of a minute precision capability. AFC uses this field for generation of taxes that are specified as per minute flat fees in some taxing jurisdictions and stores the value in the AFC log database. The number is a double so any AF C S aaS S t a n d a r d U s e r M a n u a l | 33 of 54 Copyright 2018 Avalara, Inc. seconds added should be in decimal format. For example, 20 minutes and 30 seconds would be 20.5 minutes. Transaction Fields Column Name Minutes Description Numeric : floating point >= 0.0 Specifying Debit Flag Setting the value to True triggers a special prepaid taxing routine. In general, unless you are a prepaid seller and understand the impact of setting the debit flag, the value of False should be used. Contact Avalara Support for more information if you are not sure if setting this flag to True is applicable to your business. Debit Flag Value True False (Default) Description Perform a debit call tax calculation. Debit does not apply. Specifying Service Class The Service Class Indicator is provided to delineate the Primary activity of an organization as either Long Distance or Local Service. The service class only impacts Telecom transactions in certain jurisdictions, such as New York. Service Class ID 0 Value Local (Default) 1 Long Distance Description Primary Local Service providers are carriers vending their services with over 50% of the gross business activities in Local Service revenue. Primary Long Distance providers are carriers vending their services with over 50% of the gross business activities in Long Distance revenue. Specifying Lifeline Flag The Lifeline flag is used to indicate if a customer is a Lifeline participant. Lifeline Flag Value True False (Default) Description Has the effect of turning off the calculation of taxes that are not collected from Lifeline recipients. Collects all taxes. AF C S aaS S t a n d a r d U s e r M a n u a l | 34 of 54 Copyright 2018 Avalara, Inc. Specifying Facilities Flag The Facilities flag specifies the tangible facilities used by a company to deliver the service. This designation applies to Seller. If the carrier delivering the service uses company-owned facilities to provide the service, then it is facilities-based. If the carrier does not own the facilities, it is non-facilities based. Facilities Flag Value True (Default) False Description Seller is facilities based. Seller is not facilities based. Specifying Franchise Flag The Franchise flag indicates that the company provides services sold pursuant to a franchise agreement between the carrier and the jurisdiction. This designation applies to the Seller. Note: Marking the transaction as Franchise = False will often result in no franchise fees or taxes being returned. Franchise Flag Value True (Default) False Description Seller has a franchise agreement with jurisdiction. Franchise fees and taxes do not apply to seller. Specifying Business Class The Business Class Indicator field is used to specify whether the business making the transaction is an Incumbent Local Exchange Company (ILEC) or a Competitive Local Exchange Company (CLEC). This designation applies to the Customer. This setting can also be considered as, “You are ILEC” or, “You are not ILEC.” If neither class applies, use the default value CLEC. The business class only impacts Telecom transactions in certain jurisdictions, such as Oregon. Business Class ID 0 1 Value ILEC CLEC (Default) Description Customer is an ILEC company. Customer is not an ILEC company. Specifying Company Identifier The company identifier does not impact taxation, but is useful in reporting. Normally this field would only be used if you need to distinguish transactions for different companies. AF C S aaS S t a n d a r d U s e r M a n u a l | 35 of 54 Copyright 2018 Avalara, Inc. Reporting Fields Column Name Customer Identifier Description Alpha-numeric field. Supports up to 20 bytes. Specifying Customer Number The customer number does not impact taxation, but is useful in reporting. Normally this field would only be used if you need to distinguish transactions for different customers. Reporting Fields Column Name Customer Number Description Alpha-numeric field. Supports up to 20 bytes. Specifying Invoice Number The invoice number does not impact taxation, but is useful in reporting. Normally this field is only used if you need to distinguish transactions for different invoices. Reporting Fields Column Name Invoice Number Description Unsigned long value. Should be >= 0. The max value is different for different platforms, but in general supports values at least up to 4294967295 (232 -1). Note: All numerical values entered into fields, such as Invoice Number, are considered integers and cannot be greater than the maximum value previously noted in this table. Any numbers larger than this value cannot be passed in AFC SaaS Standard and will produce an error message indicating the value is too large. Specifying Discount Type AFC has an additional table that stores discount types by state with an “allow ability” indicator. The adjustment functions have arguments for the discount type which look up the discount type from the table to determine whether to apply taxes or not. Discounts may or may not be taxed within each state. When a discount is taxed, the customer receives a tax benefit commensurate with the amount of the discount (i.e., if the customer gets $5 off on a transaction subject to a 5% tax, the customer pays $0.25 less in tax than they would have). When a discount is not taxed, the customer receives non tax benefit from the discount. Whether a discount is taxed or not depends on the type of discount and the rules in a particular tax jurisdiction. Discount types only apply to adjustment transactions. Refer to Section 4.1.7 Discount Adjustments in TM_00101_AFC User Manual_Telecom.pdf for more information on calculating adjustments. AF C S aaS S t a n d a r d U s e r M a n u a l | 36 of 54 Copyright 2018 Avalara, Inc. Discount Type ID 0 1 2 Value None (Default) Retail Product Manufacturer Product 3 Account Level 4 Subsidized 5 Goodwill Description Discount Type not applicable. An amount subtracted from the original price to arrive at a lower price. A credit applied to the total amount reimbursed to either the retailer or the customer by the manufacturer. A stand-alone discount that is not applied against any service but instead as a stand-alone product. A credit for telephone service where the telephone provider provides a service to a lifeline eligible customer. The credit will be applied to the subscriber line charge. A credit applied to customer invoices for the purpose of engendering customer goodwill. For example, compensation for a service outage. Specifying Exemption Type • Specifying the exemption type is for reporting purposes only and does not impact tax calculations. Spaces and capitalization do not matter in Exemption Type value. The bolded text is sufficient, additional characters are ignored. The optional numeric ID can be used. For example: Non Profit Sales = nonprofitsales = nonprofit = 6 Fed Coupons WIC Vouchers = Fed Coupons = FEDCOUPONS = 4 • • • Exemption Type ID 0 1 2 3 4 Value None (Default) Fed Sales Supremacy State Local Gov Sales Sales for Resale Fed Coupons WIC Vouchers 5 6 Reduced Food Rate Non Profit Sales 7 Public School Sales 8 Religious Charitable Sales 9 Prescription Drug Sales Prostho Ortho Devices 10 11 12 Insulin Sales Interstate Foreign Sales Description Exemption Type not applicable. Sales to the Federal government exempt based on supremacy. Sales to the State or Local government in the state that you operate in. Sales that are designated for resale. Sales at retail for which Federal government coupons or vouchers under the supplemental feeding for women, infants and children program are used as payment. Tax imposed on food that is taxed at a reduced rate. Sales made by or to not-for-profit civic, social, service or fraternal organizations. Sales made by or to all elementary and secondary schools operated at public expense in their educational functions and activities. Sales made by or to religious and charitable organizations and institutions in their religious, charitable or educational functions and activities. Drugs which may be legally dispensed by a licensed pharmacist only upon a lawful prescription of a practitioner licensed to administer those items. Prosthetic or orthopedic devices as defined on January 1, 1980, by the Federal Medicare program pursuant to Title XVIII of the Social Security Act of 1965. All sales of insulin. Sales in commerce between various states or between any foreign country (Export Sales). AF C S aaS S t a n d a r d U s e r M a n u a l | 37 of 54 Copyright 2018 Avalara, Inc. Exemption Type ID 13 Value Ingredient Component Parts Description Sale of ingredient or component parts. Specifying Adjustment Method In certain cases, when the rate of a tax will change based upon the charge or the number of lines in the transaction, clients may wish to make an adjustment at a different rate than would normally apply for the transaction. For example, if the client purchased 20 lines at a rate of $0.67 per line and the credit or adjustment is for 5 lines at a rate of $1.25 per line, then usage of LEAST for the adjustment method would refund the 5 lines at the least favorable rate for the brackets making sure the client was not over compensated. If unsure, use the value “Default”. Adjustment Method Value Default (Default) Least Favorable Rate Most Favorable Rate Description Standard Tax Brackets applied for transaction. Tax brackets applied to produce smallest tax refund. Tax brackets applied to produce largest tax refund. Specifying Private Line (Point-to-Point) Private line, or Point-to-Point (PTP) as it is often referred to, allows a transaction to be split between the A point and Z point. If “IsPrivateLine” is set to true, then the “PrivateLineSplit” must also be provided. If all transactions have the same split, the default file can be used to set the PrivateLineSplit. Private Line or Point-to-Point Column Name IsPrivateLine PrivateLineSplit Description True/False Percentage allocation specified as a decimal in the range 0 to 1. Example: For a 40% - 60% split, the value 0.4 would be specified. 40% would be applied to the A point, and 60% to the Z point. The Origination Jurisdiction will be used for the A point, and the Termination Jurisdiction will be used for the Z point. Note: This feature is only supported with processing of tax calculations and adjustments which are not Tax Inclusive. It is not supported for use with Tax Inclusive calculations. AF C S aaS S t a n d a r d U s e r M a n u a l | 38 of 54 Copyright 2018 Avalara, Inc. Specifying Proration The Proration feature provides clients with the ability to calculate prorated taxes on a transaction that represents a partial month of service. Percentage-based taxes are prorated by way of the charge amount passed. However, fixed and per line taxes are subject to special prorating rules and procedures. Some tax authorities allow sellers to pro-rate fixed and per line taxes for partial months, but many insist on receiving the full amount. AFC will apply these rules automatically if the prorating feature is used. . A number between 0 and 1 is passed to specify the percentage of the month the service was active. The prorating functionality checks the logic of each tax in the appropriate jurisdiction to determine if prorating is allowed. If prorating is not allowed, the full amount is taxed. If prorating is allowed, the fixed or per line tax applicable to the service will be returned multiplied by the fraction supplied. If the proration is being used for an adjustment credit rather than a partial charge, the ratio of the percentage applied should reflect the portion of the month in which the service was not active. Proration Column Name IsProRated ProRatedPct Description True/False Percentage allocation specified as a decimal in the range 0 to 1. If IsProRated is true and a prorated percentage is not provided, the default value of 1 will be applied. Specifying Default Optional Reporting Fields AFC SaaS Standard provides up to 9 Default Optional Fields. The optional fields do not impact taxation, but can be useful in reporting. As noted in Specifying Request Type, the field Optional should not be used when performing tax inclusive calculations. Reporting Fields Column Name Optional Optional4 Optional5 Optional6 Optional7 Optional8 Optional9 Optional10 OptionalAlpha1 Description Unsigned long value. Should be >= 0. The max value is different for different platforms, but in general supports values at least up to 4294967295 (232 -1). Alpha-numeric field. Supports up to 20 bytes. Specifying Extended Optional Reporting Fields AFC SaaS Standard provides up to 10 Extended Optional Fields. The optional fields do not impact taxation, but can be useful in reporting. As noted in Specifying Request Type, the field Optional should not be used when performing tax inclusive calculations. AF C S aaS S t a n d a r d U s e r M a n u a l | 39 of 54 Copyright 2018 Avalara, Inc. The general guidelines adding Extended Optional Fields in AFC SaaS Standard are as follows: 1. Add the Extended Optional Fields by assigning values to each in the input file. 2. The column header for each field must be entered in the format of Key:[header]. Note: Only up to 10 Extended Optional Fields may be added and the value for each field can be no longer than 150 characters. Sample Input File (only showing the optional fields) For the error handling, invalid columns are ignored. In the sample input file provided, Column P and R are invalid and Column Z is ignored. Note: The data below is the output of the sample input file and can be found in the status report. Only the valid columns of data will be shown in the detail log report. Mapping 26 columns Warning: column 0:[Key:] is unmapped Unmapped 0:Key: Mapped 1:Date Mapped 2:BillTo Country ISO Mapped 3:BillTo State Mapped 4:BillTo County Mapped 5:BillTo Locality Mapped 6:BillTo ZipCode Mapped 7:Charge Mapped 8:Transaction Type Mapped 9:Service Type Mapped 10:Sale Mapped 11:Incorporated Mapped 12:Customer Number Mapped 13:Key:Seller Mapped 14:Key:Cross Reference Warning: column 15:[Key:] is unmapped Unmapped 15:Key: Mapped 16:Key:Null Test Warning: column 17:[Key5:Bad Format] is unmapped Unmapped 17:Key5:Bad Format Mapped 18:Key:Too Long 12345678901234567890123456789012345678901234567890123456789012345678901234567890123456 78901234567890123456789012345678901234567890123456789012345678901234567890123456789012 34567890123456789012345678901234567890123456789012345678901234567890123456789012345678 901234567890123456789012345678901234567890 Mapped 19:Key:Discount Mapped 20:Key:Exemption Reason Mapped 21:Key:Project Mapped 22:Key:Schedule Mapped 23:Key:Activity Mapped 24:Key:Testing Mapped 25:Key:Warning Column mapping complete - mapped 23 / unmapped 3 AF C S aaS S t a n d a r d U s e r M a n u a l | 40 of 54 Copyright 2018 Avalara, Inc. Specifying Exemption Cross Reference Key The exemption file requires the name of the first column to be the one of the appropriate cross reference keys that ties the exemption to the applicable transactions. The value of the cross reference key should match exactly the value of the applicable transaction column in the input file. The following table shows valid options for the column header names which may are used to represent the cross reference key. (Please note that only one option for column name may be selected.) Cross Reference Key Column Name Customer Number Company Identifier OptionalAlpha1 Exemption Type Description Ties exemption(s) to input file transactions with matching Customer Number. Refer to Specifying Customer Number for more details on the field. Ties exemption(s) to input file transactions with matching Company Identifier. Refer to Specifying Company Identifier for more details on the field. Ties exemption(s) to input file transactions with matching OptionalAlpha1. Refer to Specifying Optional Reporting Fields for more details on the field. Ties exemption(s) to input file transactions with matching Exemption Type. Refer to Specifying Exemption Type for more details on the field. Specifying Exemption Jurisdiction The exemption jurisdiction can be specified through any of the jurisdiction types in the Exemption Jurisdiction Table. Only one of the jurisdiction options should be chosen for a given exemption. Exemption Jurisdiction Table Column Header(s) Link To Values List BillTo Origination Termination PCode Numeric Country State County Locality ZipCode ZipP4 Address Fips Code 10 digit number Description Linked jurisdictions are useful for when the jurisdiction of the taxes to be exempted can be defined by one of the input transaction jurisdictions. When the tax calculation occurs, the exemption will be updated with the correct corresponding jurisdiction from the transaction. If all three jurisdictions in the input transaction are the same, the linked exemption would always apply. The PCode should be the same level or lower than the targeted tax level. Refer to Specifying Jurisdiction PCode for more details on the field. The address can be Country Only, State Only (for USA), or any valid address. Refer to Specifying Jurisdiction Address for more details on the address fields. The Fips Code should be the same level or lower than the targeted tax level. Refer to AF C S aaS S t a n d a r d U s e r M a n u a l | 41 of 54 Copyright 2018 Avalara, Inc. Exemption Jurisdiction Table Column Header(s) Values List NpaNxx 6 digit number Description Specifying Jurisdiction Fips Code for more details on the field. Refer to Specifying Jurisdiction NpaNxx for more details on the field. Specifying Exemption Domain Domain determines the jurisdiction level at which the exemption jurisdiction must match the taxing jurisdiction. The domain will automatically shift upwards if the exemption jurisdiction is defined at a higher level than the domain. The domain value can be specified either by numeric id or the equivalent text representation. Capitalization is ignored (FEDERAL = Federal = 0). Exemption Type ID 0 1 2 3 Value Federal State County Local Description Matches at the Federal or Country level. Matches at the State, Province or Territory level. Matches at the County level. Matches at the Local or City level. Specifying Exemption Scope Exemptions are designed to be applied for one or more specific tax types. The tax type is required. Exemption Scope Value Numeric value Text value Description Numeric mask representing summarized scope values. Text representing combined scope values. Description of values Scope Base Numeric Value 128 256 512 1024 Scope Base Text Value Federal State County Local To get combinations, add up the numeric values or combine the text values with + as the separator. Examples: AF C S aaS S t a n d a r d U s e r M a n u a l | 42 of 54 Copyright 2018 Avalara, Inc. Scope Numeric Value 1920 1792 384 Scope Text Value Options All Federal+State+County+Local F+S+C+L State+County+Local S+C+L Federal+State F+S Specifying Exemption Tax Level (Deprecated – Use Domain instead) The tax level can be specified either by numeric id or the equivalent text representation. Capitalization is ignored (FEDERAL = Federal = 0). Exemption Type ID 0 1 2 3 Value Federal State County Local Description Exemption applies to Federal taxes. Exemption applies to State taxes. Exemption applies to County taxes. Exemption applies to Local taxes. Note: Most Federal taxes are only exempted when selling to a reseller who is registered, reporting, and remitting to the regulating agency. For this reason, a wholesale exemption or a tax type exemption must be used to exempt taxes at the Federal level. Specifying Exemption Category Exemptions may also be applied by tax category in AFC SaaS Standard. Clients may enter the appropriate tax category ID instead of a tax type ID. Please reference the table below for a current list of tax categories in AFC SaaS Standard. Tax Categories Category ID 0 1 2 3 4 5 6 7 8 9 10 Name No Category Description Sales and Use Taxes Business Taxes Gross Receipts Taxes Excise Taxes Connectivity Charges Regulatory Charges E-911 Charges Utility User Taxes Right of Way Fees Communications Services Tax AF C S aaS S t a n d a r d U s e r M a n u a l | 43 of 54 Copyright 2018 Avalara, Inc. Tax Categories Category ID 11 12 13 Name Cable Regulatory Fees Reserved Value Added Taxes Specifying Exemption Exempt Non-billable Flag The Exempt non-billable flag indicates whether non-billable taxes should be included as candidates for exemption. This is not required if a specific tax type is being exempted, but only for Category exemptions and wildcard exemptions. Facilities Flag Value True False (Default) Description Include non-billable taxes as candidates for exemption. Exclude non-billable taxes as candidates for exemption. Specifying Exemption Exempt Non-level-exemptible Flag The exempt non-level exemptible flag indicates whether taxes tagged as non-level exemptible should be included as candidates for exemption. This is not required if a specific tax type is being exempted or if it is a category exemption, but only for tax type wild-card exemptions. Facilities Flag Value True (Default) False Description Include non-level exemptible taxes as candidates for exemption. Exclude non-level exemptible taxes as candidates for exemption. Specifying Safe Harbor Overrides for Traffic Studies The results of percentages from a traffic study can be applied by administering traffic study TAM overrides. The TAM values for Cellular, VoIP and Paging are adjusted to reflect the percentages in the traffic study. Please contact communicationsupport@avalara.com in order to set the override at the account level versus transaction level. AF C S aaS S t a n d a r d U s e r M a n u a l | 44 of 54 Copyright 2018 Avalara, Inc. 1. Cellular Examples: Original Cellular Safe Harbor: 37.1% Federal / 62.9% State State City Zip Charge Products Tax Type Level Rate TM Tax Charge Exempt NY Manhattan 10001 100 Cellular/Access Charge Fed USF Cellular Federal 0.174 37.1 6.4554 100 62.9 Cellular Traffic Study Override: 15.0% Federal / 85.0% State State City Zip Charge Products Tax Type Level Rate TM Tax Charge Exempt NY Manhattan 10001 100 Cellular/Access Charge Fed USF Cellular Federal 0.174 15 2.61 100 85 2. VoIP Examples: Original VoIP Safe Harbor: 64.9% Federal / 35.1% State State Zip Charge Products Tax Type Level Rate TM Tax Charge Exempt CA 90001 100 VoIP/Access Charge Universal Lifeline Telephone Service Charge (VoIP) State 0.055 35.1 1.9305 100 64.9 CA 90001 100 VoIP/Access Charge CASF (VoIP) State 0.00464 35.1 0.16286 100 64.9 CA 90001 100 VoIP/Access Charge CA Teleconnect Fund (VoIP) State 0.0108 35.1 0.37908 100 64.9 CA 90001 100 VoIP/Access Charge CA High Cost Fund A (VoIP) State 0.0035 35.1 0.12285 100 64.9 CA 90001 100 VoIP/Access Charge TRS (VoIP) State 0.005 35.1 0.1755 100 64.9 CA 90001 100 VoIP/Access Charge E911 (VoIP) State 0.0075 35.1 0.26325 100 64.9 CA 90001 100 VoIP/Access Charge FUSF (VoIP) Federal 0.174 64.9 11.2926 100 35.1 CA 90001 100 VoIP/Access Charge FCC Regulatory Fee (VoIP) Federal 0.00371 64.9 0.24078 100 35.1 VoIP Traffic Study Override: 25.0% Federal / 75.0% State State Zip Charge Products Tax Type Level Rate TM Tax Charge Exempt CA 90001 100 VoIP/Access Charge State 0.055 75 4.125 100 25 CA 90001 100 State 0.00464 75 0.348 100 25 CA 90001 100 0.0108 75 0.81 100 25 90001 100 State 0.0035 75 0.2625 100 25 CA 90001 100 CA Teleconnect Fund (VoIP) CA High Cost Fund A (VoIP) TRS (VoIP) State CA State 0.005 75 0.375 100 25 CA 90001 100 E911 (VoIP) State 0.0075 75 0.5625 100 25 CA 90001 100 FUSF (VoIP) Federal 0.174 25 4.35 100 75 CA 90001 100 VoIP/Access Charge VoIP/Access Charge VoIP/Access Charge VoIP/Access Charge VoIP/Access Charge VoIP/Access Charge VoIP/Access Charge Universal Lifeline Telephone Service Charge (VoIP) CASF (VoIP) FCC Regulatory Fee (VoIP) Federal 0.00371 25 0.09275 100 75 AF C S aaS S t a n d a r d U s e r M a n u a l | 45 of 54 Copyright 2018 Avalara, Inc. 8.9 Zip Lookup Requests Zip Lookup Input File The columns in the Excel and CSV file formats are the same in each format. Column headers are the first row in each file which describe the data in that particular field or column. Field *Required Value List Reference Request Type R ZipLookup Specifying Request Type Country State County Locality ZipCode ZipP4 OR Specifying Jurisdiction Address Best Match D True False (default) Specifying Best Match Flag Limit Results D Number (default is 100) Specifying Limit Results Value Key:{header} O Specifying Extended Optional Reporting Fields *Required: • • • • • R = Required OR = Only One Required (Remaining optional) SR = Strongly Recommended (Default, if applicable) O = Optional (No Default) D = Optional (Default, if applicable) Notes: • • • • Spacing is ignored in a field name. For example, [Request Type] and [RequestType] would be considered identical. Matching will ignore additional fields or characters beyond the listed value. Example: [Country] and [Country] would be considered identical. [Zip] however would not be considered a valid column identifier, as it must be either [ZipCode] or [ZipP4] to distinguish which value applies. Column headers are required and must be included in Excel and CSV format. The key column should be used to tie input data to the results. AF C S aaS S t a n d a r d U s e r M a n u a l | 46 of 54 Copyright 2018 Avalara, Inc. Zip Lookup Results The following zip files would be produced if a file with the base name KML150117AA is uploaded. KMLR150117AA.zip - Report Files Zip Lookup Report Files File Name Description KML161015AA.csv Request in comma delimited format. KML161015AA_ziplookup.csv Results in comma delimited format. KML161015AA_conversion.rpt Conversion report. Generated if input file is in Excel format. Convert excel to comma delimited. KML161015AA_error.rpt Processing error report. Produced if errors occur during processing. Report captures the specific error message and the input line that failed processing. KML161015AA_summary.rpt Processing summary report. KMLE161015AA.zip - Status Files Extended and Fixed Format Status Files File Name Description Read_err.sta Reports problems encountered while reading the input file. Problems might relate to invalid transaction/service type pairings or an invalid input file. KML161015AA_converter.sta Applies to excel input files. If an error occurs during conversion from Excel to csv format, this file will be generated with the error message. KML161015AA_batch.sta Status from batch processor. Outputs column mappings and any informational, warning or error level messages. Zip Lookup Specific Transaction Specifications Specifying Best Match Flag Best Match Flag Value True False (Default) Description Will attempt to locate the best match for the data provided All data provided must match exactly to the values in the address file By default, the Zip Lookup algorithm requires an exact match of all fields provided with the following considerations: 1. Punctuation in city names will be ignored 2. Whitespace will be ignored For example, the city name LAND O' LAKES will match LAND O LAKES or LANDOLAKES as both the punctuation and spacing will be ignored for purposes of matching. AF C S aaS S t a n d a r d U s e r M a n u a l | 47 of 54 Copyright 2018 Avalara, Inc. If Best Match is set to true, some limited variable search algorithms will be used to find the best match for the data provided. Examples using Manhattan in New York are as follows: 1. Sample Request with one exact match Request 1 - Match exact on Country, State, County, City and Zip Code Request Type Country State County Locality ZipCode Best Match ZipLookup USA NY New York Manhattan 10001 FALSE Result PCode 2604100 Country State County City USA NY NEW YORK MANHATTAN 2. Sample Request with multiple exact matches Request 1 – Match exact on Country, State, County and Zip Code Request Type Country State County Locality ZipCode Best Match ZipLookup USA NY New York 10001 FALSE Request 2 – Match exact on Country and Zip Code (Blank Country defaults to USA) Request Type Country State County Locality ZipCode Best Match ZipLookup 10001 FALSE Result - Both match 5 addresses (All have same Country, State, County and Zip) PCode Country State County City 2604100 USA NY NEW YORK EMPIRE STATE 2604100 USA NY NEW YORK GREELEY SQUARE 2604100 USA NY NEW YORK ONE HUNDRED THIRTY EIGHTH 2604100 USA NY NEW YORK MANHATTAN 2604100 USA NY NEW YORK NEW YORK 3. Sample Request – Match exact on invalid address Request 1 – Match exact on Country, State, County, City and Zip Code Request Type Country State County Locality ZipCode Best Match ZipLookup USA NY Westchester Manhattan AF C S aaS 10001 FALSE S t a n d a r d U s e r M a n u a l | 48 of 54 Copyright 2018 Avalara, Inc. Result – No matches, not a valid address PCode Country State County City 4. Sample Request – Best match on invalid address Request 1 – Best match on Country, State, County, City and Zip Code Request Type Country State County Locality ZipCode Best Match ZipLookup USA NY Westchester Manhattan 10001 FALSE Result – County was disregarded PCode 2604100 Country State County City USA NY NEW YORK MANHATTAN Specifying Limit Results Value The limit results field is used to limit the number of matches returned. Limit Results Column Name Limit Results Description Numeric : integer >= 0 • Default = 100, Maximum Limit = 1000 • If zero is entered as the value, the default limit will be used. • If the value entered is greater than the maximum, the maximum limit will be used. 8.10 Bridge Conference File The Bridge Conferencing feature is currently in development at this time. Please refrain from using this feature as well as the proposed solutions and files until further notice. AF C S aaS S t a n d a r d U s e r M a n u a l | 49 of 54 Copyright 2018 Avalara, Inc. 9. Appendix A – Fixed Format: CDF The CDF file format is currently available. Please reference the table provided below for additional details on this format. CDF Client Input Data Specification Opt/Req R R R R Sec J J J J Data Description Origination Origination Flag Termination Termination Flag Type N A N A Len 10 1 10 1 Positions Default Note 0-9 Originating NPANXX if flag=N Originating PCode if flag=P Originating State code if flag=S (numeric value) 10 Set to N if using NPANXX, P if using PCode, or S if using State code 11-20 Terminating NPANXX if flag=N Terminating PCode if flag=P Terminating State code if flag=S (numeric value) 21 Set to N if using NPANXX, P if using PCode, or S if using State code R J Service Address N 10 22-31 Service (BTN) NPANXX if flag=N Service PCode if flag=P Service State code if flag=S (numeric value) R J Service Address Flag A 1 32 Set to N if using NPANXX, P if using PCode, or S if using State code R C Customer Type A 1 33 R T Invoice Date N 8 34-41 AF C S aaS B Business, Residential Customer, Industrial, or Senior Citizen Format "CCYYMMDD" S t a n d a r d U s e r M a n u a l | 50 of 54 Copyright 2018 Avalara, Inc. CDF Client Input Data Specification Opt/Req Sec Data Description Type Len Positions Default Note R T Taxable Amount Sign A 1 42 Format "+", "-", “p” or “m” R T Taxable Amount N 11.5 43-53 Format "99999999999" Zero-Filled, 5 decimal places, no decimal point R T Lines N 6 54-59 0 6-character integer R T Location N 6 60-65 0 6-character integer R T/S Transaction Type A/N 6 66-71 See Table of Transaction Types and Service Types R T/S Service Type A/N 6 72-77 See Table of Transaction Types and Service Types R T Client Resale Flag A 1 78 S Call subject to Sale or Resale R C Inc-Code A 1 79 I Customer is Inside or Outside an incorporated city area R C Fed. Exempt A 1 80 Blank Call is exempt from Federal taxes R C State Exempt A 1 81 Blank Call is exempt from State taxes R C County Exempt A 1 82 Blank Call is exempt from County taxes R C Local Exempt A 1 83 Blank Call is exempt from Local taxes A/N 20 84-103 Defines primary Key for Client Summary Data 104 Reseller is Regulated or Unregulated in the state of sale Customer Number O R C CO (Primary Output Key) Regulated / Unregulated Flag A 1 AF C S aaS R S t a n d a r d U s e r M a n u a l | 51 of 54 Copyright 2018 Avalara, Inc. CDF Client Input Data Specification Opt/Req Sec Data Description Type Len Positions Default Note Format "99999999999" Zero-Filled, 1 decimal place, no decimal point R T Call Duration (in minutes) R T Telecom Type A 1 116 C C – Calls (telcom), D-Debit Card Calls, P-Point of sale R C service class indicator A 1 117 D Long Distance or Local primary (D or L) O C Lifeline flag A 1 118 Blank L - lifeline customer (Blank or l) R CO facilities-based flag A 1 119 N Facilities-based or Non Facilities-based (F or N) R CO franchise flag A 1 120 N Franchise or Non-Franchise (F or N) R C business class indicator A 1 121 C CLEC or ILEC (C or I) N 11.1 105-115 10. Appendix B – AFC Error Codes A list of AFC error codes and descriptions for each are provided in the table below. AFC Error Code 0 Message/Description Backend System Error. Error details will be included in the error message. -11 JCode not found. -12 PCode not found. -13 Zip code not found. AF C S aaS S t a n d a r d U s e r M a n u a l | 52 of 54 Copyright 2018 Avalara, Inc. AFC Error Code Message/Description -14 NPANXX not found. -15 Address not found. -16 County, State, Zip not found. -17 Session not initialized. -18 JCode database not open. -19 PCode database not open. -20 ZipCode database not open. -21 NPANXX database not open. -22 Address database not open. -23 Jurisdiction not found. -24 FIPS not found. -25 FIPS (to PCode) cross-reference database not open. -26 PCode (to FIPS) cross-reference database not open. -27 Invalid transaction date. -28 Invalid transaction/service pair. -29 Log name not set. -32 Transaction/service pair is not supported by the API call. -34 Transaction/Service pair is not licensed for user. -35 System error allocating memory for internal tables. -36 Split for private line transaction if either < 0 or > 1. -37 Insufficient charge supplied to cover taxes generated. -38 Tax-on-tax exceeded maximum iterations. -39 Custom log size exceeds max allowed size. -40 Exclusion is invalid. -41 Bridge conference data is invalid. AF C S aaS S t a n d a r d U s e r M a n u a l | 53 of 54 Copyright 2018 Avalara, Inc. AFC Error Code Message/Description -42 Safe Harbor Type is invalid. -43 Safe Harbor federal fraction is invalid. -44 Total distinct tax items for bundled package exceeded. -45 Total of fixed charges exceeds bundle charge. -46 Transaction/Service pair not in bundle table. -47 Bundle Transaction/Service pair has bad syntax. -48 Cannot determine call type for International calls. AF C S aaS S t a n d a r d U s e r M a n u a l | 54 of 54 Copyright 2018 Avalara, Inc.
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.6 Linearized : No Author : Alicia Combs Comments : Company : Avalara, Inc. Create Date : 2018:11:21 10:30:09-05:00 Modify Date : 2018:11:21 10:31:26-05:00 Source Modified : D:20181120152342 Subject : Language : EN-US Tagged PDF : Yes XMP Toolkit : Adobe XMP Core 5.6-c015 91.163280, 2018/06/22-11:31:03 Metadata Date : 2018:11:21 10:31:26-05:00 Creator Tool : Acrobat PDFMaker 19 for Word Document ID : uuid:bb373a53-3626-49b0-8e6b-42f99209fa11 Instance ID : uuid:8436b9b6-8917-424b-b112-8b589fbc9401 Format : application/pdf Title : Description : Creator : Alicia Combs Producer : Adobe PDF Library 19.8.103 Keywords : Page Layout : OneColumn Page Count : 61EXIF Metadata provided by EXIF.tools