TM 00111 AFC Saa S Standard User Manual Telecom

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 61

AvaTax for Communications
SaaS Standard User Manual
Release: 9.20.1812.1
Document: TM_00111_0047
Date: 11/21/2018
All trade names referenced herein are either trademarks or registered trademarks of their respective companies.
© Avalara, Inc. 2018. CONFIDENTIAL
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
Customer Portal
https://communications.avalara.net
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
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.
03/01/2016
0025
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.
04/05/2016
0026
Updates to Section 3.3.4 Handling Optional Files and Section 3.5 Results to
include use of Custom Sort utility.
05/05/2016
0027
Updates to Section 3.5 Results related to the ability to view output files in
CSV format.
06/13/2016
0028
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.
06/30/2016
0029
Updated NTL filename to match input filename in Section 3.5.2. Added
customsort_log.sta to status files in Section 3.5.3.
08/09/2016
0030
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.
11/15/2016 0031 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.
12/05/2016
0032
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.
02/13/2017
0033
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
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.
04/24/2017 0035 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.
05/19/2017
0036
Updated Section 8.8.11 Specifying Sale Type. Release number and version
updates.
08/28/2017 0037 Added note related to timestamp/invoice date passed in
Section 8.8.7
Specifying Transaction Date
.
Release number and version updates.
10/25/2017 0038 Updated Avalara contact information (address and support site). Removed
Appendix D – Avalara Product Names.
02/23/2018
0039
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.
04/25/2018
0040
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.
5/25/2018
0041
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.
6/25/2018
0042
Made release number and version updates.
7/25/2018
0043
Made release number and version updates.
8/24/2018
0044
Updated section 8.2 Exemption File. Made release number and version
updates.
9/25/2018
0045
Updated Avalara contact information. Made release number and version
updates.
10/25/2018
0046
Made release number and version updates.
11/21/2018
0047
Made release number and version updates.
AFC SaaS Standard User Manual | i
Copyright 2018 Avalara, Inc.
Table of Contents
1. Introduction .................................................................................................................. 1
2. Naming Files .................................................................................................................. 1
2.1 Compliance Month ................................................................................................................... 2
3. 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
AFC SaaS Standard User Manual | ii
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
AFC SaaS Standard User Manual | iii
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
AFC SaaS Standard User Manual| 1 of 54
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 .xls,.xlsx
o Comma-Separated .csv ABC151116AA.CSV
• Fixed Format
o Customer Detail File .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.
AFC SaaS Standard User Manual| 2 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
AFC SaaS Standard User Manual| 3 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 PK-
Zip/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.
AFC SaaS Standard User Manual| 4 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
Reference
Override File
.ovr
• 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.
Exemption File
.exm
• 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.
Bundle File
.bdl
• 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.
AFC SaaS Standard User Manual| 5 of 54
Copyright 2018 Avalara, Inc.
Supported Optional Files
Type
Extension
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.
Exclusion File
.exc
•
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.
CustomSort
Configuration File
customsort.cfg
•
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.
AFC SaaS Standard User Manual| 6 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).
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.
When successfully
connected to the AFC
FTP site and changed to
your company's file-
transfer directory, you
can send your ftp.zip file
for processing. You can
ignore the index files.
AFC SaaS Standard User Manual| 7 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
Tax Inclusive Transaction/Service Jurisdiction Report (as applicable).
Produced if client has requested the rtr report.
KML150117AA._audit.rtr.csv***
KML150117AA _ASCIILOG.CSV
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.
AFC SaaS Standard User Manual| 8 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.
AFC SaaS Standard User Manual| 9 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
Enter the username in the Username field.
3
Enter the password in the Password field.
4
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.
AFC SaaS Standard User Manual| 10 of 54
Copyright 2018 Avalara, Inc.
Step
Action/Result
5
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.
4.1 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
Action/Result
1
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.
AFC SaaS Standard User Manual| 11 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.
AFC SaaS Standard User Manual| 12 of 54
Copyright 2018 Avalara, Inc.
Step
Action/Result
4
Once completed, the output files or results will appear (such as the one highlighted in blue in the
screenshot.)
4.2 Retrieving Files
Please follow the steps provided below in order to retrieve or review files.
Step
Action/Result
1
View the completed files processed and locate the file with appropriate date and timestamp.
2
Highlight or double-click the file you wish to open.
AFC SaaS Standard User Manual| 13 of 54
Copyright 2018 Avalara, Inc.
Step
Action/Result
3
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-Developer-
Content/tree/master/afc_saasstd_tax/support_docs
AFC SaaS Standard User Manual| 14 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.
AFC SaaS Standard User Manual| 15 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
*Required
Value List
Reference
Request Type
R
CalcTaxes
CalcAdj
CalcIncl
CalcInclAdj
Specifying Request Type
BillTo PCode
Origination PCode
Termination PCode
OR
Specifying Jurisdiction 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
OR
Specifying Jurisdiction Address
BillTo Fips Code
Origination Fips Code
Termination Fips Code
OR
Specifying Jurisdiction Fips Code
BillTo NpaNxx
Origination NpaNxx
Termination NpaNxx
OR
Specifying Jurisdiction NpaNxx
Transaction Type
R Specifying Transaction / Service Pair
Service Type
R Specifying Transaction / Service Pair
Date
R YYYYMMDD Specifying Transaction Date
Charge
R
Specifying Transaction Charge
AFC SaaS Standard User Manual| 16 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 Specifying Level Exemptions
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
AFC SaaS Standard User Manual| 17 of 54
Copyright 2018 Avalara, Inc.
*Required:
• R = Required
• OR = Only One Required (Remaining optional)
Field
*Required
Value List
Reference
Discount Type
D
None (Default)
Retail Product
Manufacturer Product
Account Level
Subsidized
Goodwill
Specifying Discount Type
Exemption Type
D
Specifying Exemption Type
Adjustment Method
D
Default (Default)
Least
Most
Specifying Adjustment Method
IsPrivateLine
PrivateLineSplit
D
Percentage allocation
specified as a decimal in
the range 0 to 1.
Specifying Private Line or Point-to-Point
IsProRated
ProRatedPct
D
Percentage allocation
specified as a decimal in
the range 0 to 1.
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
VoIP New (Override Fed TAM)
Cellular Old (Original Fed TAM)
O
TAM value specified as
decimal between 0 and
1.
Specifying Safe Harbor Overrides for Traffic
Studies
Cellular New (Override Fed TAM)
Paging Old (Original Fed TAM)
O
TAM value specified as
decimal between 0 and
1.
Specifying Safe Harbor Overrides for Traffic
Studies
Paging New (Override Fed TAM)
AFC SaaS Standard User Manual| 18 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:
• 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.
8.2 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
AFC SaaS Standard User Manual| 19 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 non-
billable taxes. The new flag ExemptNB must be set to true if a client wishes to include non-
billable 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
AFC SaaS Standard User Manual| 20 of 54
Copyright 2018 Avalara, Inc.
Exemption Fields
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.
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
-or-
Text Scope Value(s)
Specifying Exemption Scope
Domain
Numeric Tax Level ID
-or-
Text Domain Value
Specifying Exemption Domain
ExemptNB
Flag – Boolean
Specifying Exemption Exempt Non-billable Flag
ExemptLvl
Flag – Boolean
Specifying Exemption Exempt Non-level-exemptible Flag
Customer Number
LinkTo
Tax Type
Domain
Customer 1
BillTo
18
0
AFC SaaS Standard User Manual| 21 of 54
Copyright 2018 Avalara, Inc.
• 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
Country
State
County
Locality
Zip Code
Tax
Type
Domain
Customer 1
USA
18
0
Customer 1
FL
64
1
Customer 1
USA
FL
Brevard
Cocoa
Beach
32931
64
3
Customer 2
USA
169
Federal
Customer 2
CA
18
Federal
Customer 2
USA
CA
San
Francisc
o
San
Francisc
o
94102
16
Local
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
Default
Special Condition
Include
Nonbillable
True
False
Valid tax type specified
Wildcard for tax type used
Scope
Tax Level or Domain
Domain
Tax Level
One or the other is required for Tax Type exemptions.
Domain overrides tax level if both are provided
Force Lvl Exempt
True
Wildcard for tax type used
Category defaults (where applicable)
Field
Default
Special Condition
Customer 1
Origination
64
1
Customer 1
Termination
64
3
AFC SaaS Standard User Manual| 22 of 54
Copyright 2018 Avalara, Inc.
Include
Nonbillable
False
Scope
State+County+City
All
If State or lower level jurisdiction
If Country level jurisdiction
Domain
State
Federal
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). Non-
billable 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 non-
billable
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
ExemptLvl
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
AFC SaaS Standard User Manual| 23 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
ExemptLvl
0
USA, PR
128 (Federal)
true
0 (Federal)
false
8.3 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
Business
Lines
0
Sale
TRUE
Incorporated
TRUE
Federal Exempt
FALSE
State Exempt
FALSE
County Exempt
FALSE
Local Exempt
FALSE
Regulated
FALSE
Minutes
0
Debit
FALSE
Service Class
Local
Lifeline
FALSE
Facilities
TRUE
Franchise
TRUE
Business Class
CLEC
AFC SaaS Standard User Manual| 24 of 54
Copyright 2018 Avalara, Inc.
8.4 Transaction File Sample
The order of columns is not important, but column headers are required.
Request
Type
Origination
PCode
Customer
Type
Date
Charge
Lines
Trans-
action
Type
Service
Type
Sale
Incorpor-
ated
Customer
Number
CalcTaxes
540000
Business
20150715
100
0
19
6
True
True
Customer 1
CalcTaxes
540000
Business
20150715
100
0
19
30
True
True
Customer 1
CalcTaxes
540000
Business
20150715
100
0
19
37
True
True
Customer 1
CalcTaxes
540000
Business
20150715
100
0
19
577
True
True
Customer 1
CalcTaxes
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
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
Local
False
False
False
CLEC
8.6 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
AFC SaaS Standard User Manual| 25 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
Uses Origination
Orig, Orig, Term
Origination
Uses BillTo
BillTo, BillTo, Term
Termination
Uses BillTo
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
AFC SaaS Standard User Manual| 26 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.
AFC SaaS Standard User Manual| 27 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.
AFC SaaS Standard User Manual| 28 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
Special Handling Notes
AS
American Samoa
FM
Fed St of Micronesia
GU
Guam
Leave County blank
MH
Marshall Islands
MP
Northern Mariana Islands
PR
Puerto Rico
Leave County blank
PW
Palau
VI
US Virgin Islands
AFC SaaS Standard User Manual| 29 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
Alberta
BC
British Columbia
MB
Manitoba
NB
New Brunswick
NL or NF
Newfoundland
AB
Alberta
NS
Nova Scotia
NT
Northwest Territories
NU
Nunavut
ON
Ontario
PE
Prince Edward Island
QC or PQ
Quebec
SK
Saskatchewan
YT
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
Description
Country
3 character ISO abbreviation
State
State Abbreviation
County
County name
Locality
City name
ZipCode
ZIP Code (5 digit USA, 6 digit Canada)
ZipP4
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
AFC SaaS Standard User Manual| 30 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
FIPS State Code
CCC
FIPS County Code
PPPPP
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.
AFC SaaS Standard User Manual| 31 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
Examples
1500
1500.00
1,500.00
$1,500
$1,500.00
-1500
-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.
AFC SaaS Standard User Manual| 32 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
Value
Description
0
Residential
When transactions are made by a customer for home use.
1
Business
When transactions are made at a place of business
2
Senior Citizen
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.
3
Industrial
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
Description
Lines
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
Value
Description
0
Resale
Only Resale/Wholesale taxes apply
1
Sale (Default)
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
AFC SaaS Standard User Manual| 33 of 54
Copyright 2018 Avalara, Inc.
Value
Description
True (Default)
Jurisdiction is inside an incorporated location.
False
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
True
State PCode
2502500
If the desire is to exempt all state taxes, then the following would be used:
Field
Value
State Exempt
True
State PCode
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
Value
Description
Regulated Flag
True
Company is rate-regulated
False (Default)
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
AFC SaaS Standard User Manual| 34 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
Description
Minutes
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
Description
True
Perform a debit call tax calculation.
False (Default)
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
Value
Description
0
Local (Default)
Primary Local Service providers are carriers vending their services with over 50% of
the gross business activities in Local Service revenue.
1 Long Distance 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
Description
True
Has the effect of turning off the calculation of taxes that are not collected from
Lifeline recipients.
False (Default)
Collects all taxes.
AFC SaaS Standard User Manual| 35 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
Description
True (Default)
Seller is facilities based.
False
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
Description
True (Default)
Seller has a franchise agreement with jurisdiction.
False
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
Value
Description
0
ILEC
Customer is an ILEC company.
1
CLEC (Default)
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.
AFC SaaS Standard User Manual| 36 of 54
Copyright 2018 Avalara, Inc.
Reporting Fields
Column Name
Description
Customer Identifier
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
Description
Customer Number
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
Description
Invoice Number
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.
AFC SaaS Standard User Manual| 37 of 54
Copyright 2018 Avalara, Inc.
Discount Type
ID
Value
Description
0
None (Default)
Discount Type not applicable.
1
Retail Product
An amount subtracted from the original price to arrive at a lower price.
2
Manufacturer Product
A credit applied to the total amount reimbursed to either the retailer or
the customer by the manufacturer.
3
Account Level
A stand-alone discount that is not applied against any service but instead
as a stand-alone product.
4
Subsidized
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.
5
Goodwill
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
Value
Description
0
None (Default)
Exemption Type not applicable.
1
Fed Sales Supremacy
Sales to the Federal government exempt based on supremacy.
2
State Local Gov Sales
Sales to the State or Local government in the state that you operate in.
3
Sales for Resale
Sales that are designated for resale.
4
Fed Coupons WIC
Vouchers
Sales at retail for which Federal government coupons or vouchers under
the supplemental feeding for women, infants and children program are
used as payment.
5
Reduced Food Rate
Tax imposed on food that is taxed at a reduced rate.
6
Non Profit Sales
Sales made by or to not-for-profit civic, social, service or fraternal
organizations.
7
Public
Scho
ol Sales Sales made by or to all elementary and secondary schools operated at
public expense in their educational functions and activities.
8
Religious Charitable
Sales
Sales made by or to religious and charitable organizations and
institutions in their religious, charitable or educational functions and
activities.
9
Prescription Drug
Sales
Drugs which may be legally dispensed by a licensed pharmacist only upon
a lawful prescription of a practitioner licensed to administer those items.
10
Prostho Ortho
Devices
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.
11
Insulin Sales
All sales of insulin.
12
Interstate Foreign
Sales
Sales in commerce between various states or between any foreign
country (Export Sales).
AFC SaaS Standard User Manual| 38 of 54
Copyright 2018 Avalara, Inc.
Exemption Type
ID
Value
Description
13
Ingredient
Component Parts
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
Description
Default (Default)
Standard Tax Brackets applied for transaction.
Least Favorable Rate
Tax brackets applied to produce smallest tax refund.
Most Favorable Rate
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
Description
IsPrivateLine
True/False
PrivateLineSplit
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.
AFC SaaS Standard User Manual| 39 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
Description
IsProRated
True/False
ProRatedPct
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
Description
Optional
Optional4
Optional5
Optional6
Optional7
Optional8
Optional9
Optional10
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).
OptionalAlpha1
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.
AFC SaaS Standard User Manual| 40 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
AFC SaaS Standard User Manual| 41 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
Description
Customer Number
Ties exemption(s) to input file transactions with matching Customer
Number. Refer to Specifying Customer Number for more details on the field.
Company Identifier
Ties exemption(s) to input file transactions with matching Company
Identifier
. Refer to Specifying Company Identifier for more details on the
field.
OptionalAlpha1
Ties exemption(s) to input file transactions with matching OptionalAlpha1.
Refer to Specifying Optional Reporting Fields for more details on the field.
Exemption Type
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)
Values List
Description
Link To
BillTo
Origination
Termination
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.
PCode
Numeric
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.
Country
State
County
Locality
ZipCode
ZipP4
Address
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.
Fips Code
10 digit number
The Fips Code should be the same level or
lower than the targeted tax level. Refer to
AFC SaaS Standard User Manual| 42 of 54
Copyright 2018 Avalara, Inc.
Exemption Jurisdiction Table
Column Header(s)
Values List
Description
Specifying Jurisdiction Fips Code for more
details on the field.
NpaNxx
6 digit number
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
Value
Description
0
Federal
Matches at the Federal or Country level.
1
State
Matches at the State, Province or Territory level.
2
County
Matches at the County level.
3
Local
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
Description
Numeric value
Numeric mask representing summarized scope values.
Text value
Text representing combined scope values.
Description of values
Scope Base
Numeric Value
Scope Base
Text Value
128
Federal
256
State
512
County
1024
Local
To get combinations, add up the numeric values or combine the text values with + as the separator.
Examples:
AFC SaaS Standard User Manual| 43 of 54
Copyright 2018 Avalara, Inc.
Scope Numeric Value
Scope Text Value Options
1920
All
Federal+State+County+Local
F+S+C+L
1792
State+County+Local
S+C+L
384
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
Value
Description
0
Federal
Exemption applies to Federal taxes.
1
State
Exemption applies to State taxes.
2
County
Exemption applies to County taxes.
3
Local
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
Name
0
No Category Description
1
Sales and Use Taxes
2
Business Taxes
3
Gross Receipts Taxes
4
Excise Taxes
5
Connectivity Charges
6
Regulatory Charges
7
E-911 Charges
8
Utility User Taxes
9
Right of Way Fees
10
Communications Services Tax
AFC SaaS Standard User Manual| 44 of 54
Copyright 2018 Avalara, Inc.
Tax Categories
Category ID
Name
11
Cable Regulatory Fees
12
Reserved
13
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 wild-
card exemptions.
Facilities Flag
Value
Description
True
Include non-billable taxes as candidates for exemption.
False (Default)
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
Description
True (Default)
Include non-level exemptible taxes as candidates for exemption.
False
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.
AFC SaaS Standard User Manual| 45 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
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
Universal Lifeline
Telephone
Service Charge (VoIP)
State
0.055
75
4.125
100
25
CA
90001
100
VoIP/Access
Charge
CASF (VoIP)
State
0.00464
75
0.348
100
25
CA
90001
100
VoIP/Access
Charge
CA Teleconnect Fund
(VoIP)
State
0.0108
75
0.81
100
25
CA
90001
100
VoIP/Access
Charge
CA High Cost Fund A
(VoIP)
State
0.0035
75
0.2625
100
25
CA
90001
100
VoIP/Access
Charge
TRS (VoIP)
State
0.005
75
0.375
100
25
CA
90001
100
VoIP/Access
Charge
E911 (VoIP)
State
0.0075
75
0.5625
100
25
CA
90001
100
VoIP/Access
Charge
FUSF (VoIP)
Federal
0.174
25
4.35
100
75
CA
90001
100
VoIP/Access
Charge
FCC Regulatory Fee
(VoIP)
Federal
0.00371
25
0.09275
100
75
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
AFC SaaS Standard User Manual| 46 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.
*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.
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
AFC SaaS Standard User Manual| 47 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
Description
True
Will attempt to locate the best match for the data provided
False (Default)
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.
AFC SaaS Standard User Manual| 48 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
Country
State
County
City
2604100
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
10001
FALSE
AFC SaaS Standard User Manual| 49 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
Country
State
County
City
2604100
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
Description
Limit Results
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.
AFC SaaS Standard User Manual| 50 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
Sec
Data Description
Type
Len
Positions
Default
Note
R J Origination N 10 0-9
Originating NPANXX if
flag=N
Originating PCode if flag=P
Originating State code if
flag=S (numeric value)
R J Origination Flag A 1 10
Set to N if using NPANXX, P
if using PCode, or S if using
State code
R J Termination N 10 11-20
Terminating NPANXX if
flag=N
Terminating PCode if flag=P
Terminating State code if
flag=S (numeric value)
R J Termination Flag A 1 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 B
Business, Residential
Customer, Industrial, or
Senior Citizen
R
T
Invoice Date
N
8
34-41
Format "CCYYMMDD"
AFC SaaS Standard User Manual| 51 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
O C
Customer Number
(Primary Output
Key)
A/N 20 84-103 Defines primary Key for
Client Summary Data
R CO Regulated /
Unregulated Flag A 1 104 R
Reseller is Regulated or
Unregulated in the state of
sale
AFC SaaS Standard User Manual| 52 of 54
Copyright 2018 Avalara, Inc.
CDF Client Input Data Specification
Opt/Req
Sec
Data Description
Type
Len
Positions
Default
Note
R T Call Duration (in
minutes) N 11.1 105-115
Format "99999999999"
Zero-Filled, 1 decimal place,
no decimal point
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)
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
Message/Description
0
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.
AFC SaaS Standard User Manual| 53 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.
AFC SaaS Standard User Manual| 54 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.

Navigation menu