AvaTax for Communications SaaS Standard file format guidelines

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
• 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 submit a support case.

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?
  • For more information, see AFC Tax Types and Category Definitions.
  • An array of exemptions can be created if multiple tax types and/or categories apply.
  • 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?
  • This defines the Scope. Regions are Federal (Country), State/Province, County, City.
  • You can define multiple regions for Scope such as (State + County + Local)
• When - At what level must the exemption match the taxing jurisdiction?
  • This defines the Domain. Domain can be one of (Federal, State, County, Local)
  • 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
  • Exemptions can be tied to transactions by one of the following:
    • Customer Number
    • Company Identifier
    • Optional Alpha1
    • Exemption Type

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.

  Customer Number	LinkTo	Tax Type	Domain
  Customer 1	BillTo	18	0
  Customer 1	Origination	64	1
  Customer 1	Termination	64	3

• Using Customer Number and Address

  The data within lines 2 – 5 of the previous input file are associated with the sample exemption file provided below.

  Customer Number	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 Francisco	San Francisco	94102	16	Local

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):

The following table of populating missing jurisdiction from jurisdictions is provided.

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

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):

For example, if a transaction has both an OriginationPCode and an OriginationNpaNxx specified, the OriginationPCode value will be used for the Origination Jurisdiction.

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

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.

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.

A breakdown of the address fields are below. The Column Name should be prefixed with either BillTo, Origination or Termination (as applicable).

ZipAddress

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 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

Specifying Jurisdiction NPANXX

NPANXX 6 digit numbers may be used for specifying a jurisdiction. There are issues to be considered with using the NPANXX.

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 TM_00115_AFC Transaction and Service Types for a complete list of all T/S pair mappings.

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.

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 charges or negative credit/refund amounts.

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.

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

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

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

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

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:

If the desire is to exempt all state taxes, then the following would be used:

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.

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 seconds added should be in decimal format. For example, 20 minutes and 30 seconds would be 20.5 minutes.

Transaction Fields

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

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

Specifying Lifeline Flag

The Lifeline flag is used to indicate if a customer is a Lifeline participant.

Lifeline Flag

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

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

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

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.

Reporting Fields

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

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

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 for more information on calculating adjustments.

Discount Type

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

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

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

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.

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

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

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.

The general guidelines adding Extended Optional Fields in AFC SaaS Standard are as follows:

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.

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

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

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

Specifying Exemption Scope

Exemptions are designed to be applied for one or more specific tax types. The tax type is required.

Exemption Scope

Description of values

To get combinations, add up the numeric values or combine the text values with + as the separator. Examples:

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

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.

See Category Definitions for a current list of tax categories in AFC SaaS Standard.

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.

Exempt Non-billable

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.

Exempt Non-level exemptible

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 submit a support case in order to set the override at the account level versus transaction level.

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.

Zip Lookup Results

The following zip files would be produced if a file with the base name KML150117AA is uploaded.

Zip Lookup Specific Transaction Specifications