Avalara AvaTax Cloud - Configuration

Owned by Mahnoor Khan (Deactivated)
Last updated: Apr 11, 2024 by Micah Gallant
10 min read

Summary

An overview of AvaTax Cloud and related articles can be found in the Avalara AvaTax Cloud Integration article. This article covers how to setup the AvaTax Cloud EngageIP integration and how to test taxation.

Requirements

In order to configure and use the AvaTax cloud integration you will need:

  • A high bandwidth internet connection

  • EngageIP version 9.1.0 or higher

  • Access to the EngageIP app server and database

  • Avalara AFC SaaS Pro Tax service login credentials (provided by Avalara)

Base Configuration

This section explains how to configure AvaTax cloud in EngageIP. If you are presently using the on-prem AvaTax integration in EngageIP you should reference the Avalara Billsoft article instead.

EngageIP and AvaTax cloud integrate through RESTful API, so unlike the older on-prem billsoft solution configuration is simplified. The AvaTax cloud configuration does not require tax vendor scripts or action scripts.

Base Configuration Steps:

  1. Import Service TaxTypes (These will be the 'Service Tax Categories' associated to your services on setup)

    1. click Setup on the left sidebar

    2. under Data Management click Import

    3. import the following service tax types XML: TaxTypes-Import.xml  (The 'TaxType' element should be 'name' for the final xml import, example per image below)

    4. the result should indicate success



  2. Optional: setup or import Account Tax Categories (AvaTax supports the following tax categories – Residential, Residential Incorporated, Business, Business Incorporated)

    1. click Setup on the left sidebar

    2. under Data Management click Import

    3. import the service tax types XML (see the AccountTaxCategoryXMLImport.xml file below this list)
      Note: you need to update owner in the XML file to match your system

      Residential Incorporated

      Residential

      Business Incorporated

      Business

      SeniorCitizen

      Industrial

      SeniorCitizen Incorporated

      Industrial Incorporated

  3. If Service Tax Category was not setup in step #1, you can add them manually: setup Service Tax Categories

  4. Populate the Tax Type Mapping table

    1. access the EngageIP Database

    2. run the EZTaxTaxTypeMappingInsertScript script found at the bottom of this list

    3. ensure there are no errors and that the EZTaxTaxTypeMapping table is populated

  5. Add a Tax Vendor for AvaTax

    1. click Setup on the left sidebar

    2. under the Taxes heading select Tax Vendor

    3. if the Default tax vendor does not exist click Add

    4. in the TaxVendor Type list select AvaTax

       

    5. Populate the Tax Vendor settings (credentials provided by Avalara)

       

      • Enable taxation on invoice close select the 'Invoice Level Taxing' option here. It's recommended that this option always be selected / used 

  6. Ensure a Default tax code is setup in the AdminPortal

    a. click Setup on the left sidebar
    b. under the Taxes heading select Tax Codes
    c. if the Default tax code does not exist click Add
    d. ensure the tax code is Name is 'Default' with a capital 'D' (as the name is case sensitive) and that
    the Tax Vendor is set to the AvaTax tax code you setup above

  7. Test to ensure that taxation is functioning: see the Post Configuration Testing section below

  8. Optional: enable UDR (usage) taxing and other required features described below


AccountTaxCategoryXMLImport.xml

EZTaxTaxTypeMappingInsertScript

Tax Exemption Configuration

XML Import file: TaxExemptTypes

Tax Exempt Levels which are valid for Avatax (different for Billsoft) include the following (any extras in the database should be removed if coming from a prior configuration):

  • Federal

  • State

  • County

  • Local

Tax Inclusive Configuration

For inclusive taxing, you can add the 'inclusive tax' component to the service.

  • A void will reverse the tax as expected for inclusive taxing.

  • Only config needed other than the main Avatax configuration is the inclusive tax component, no service restarts necessary here

Inclusive taxing does not work for credits, usage or reversed transactions. Usage taxing will continue to tax on top of the existing charge. 

 

Line Based Taxing

Line based taxing will work with Avatax. Tax on invoice close is required and the use of the bulk quantity component on the package. When a package is created with bulk quantity and the service has a Service Tax Category that is for line taxing, Avatax will return tax based on the bulk quantity number.

  1. Create zero dollar service

  2. Add Service Tax Category for line based taxes (e.g. VoIP Lines, VoIP Wireless Lines, VoIPA Lines .... etc.)

  3. Add a package and associate the service in #2 to it

  4. Add ‘Bulk Package’ component on the package

  5. Add package to account, set bulk quantity as needed

  6. Bill package

  7. Close invoice

  8. Validate that taxes are valid

NOTE: For line based taxes, no prorated refunds are provided. If the package is canceled, the complete tax will be refunded whether for a full period or not

Configuring UDR / Usage Taxing

Notice: All EngageIP Windows Services should be stopped before configuring UDR batch taxing.

Once the base configuration described above has been completed and tested you can configure taxing on usage. There are several options available for UDR taxing, these include:

  • Taxing per record (UDR) during rating

  • Taxing usage (UDRs) in batches for improved performance

  • Taxing usage when the invoice is closed

The sections below covers these three configurations.

Usage Taxation Requirements

  • The mediation code must have TaxThisUDR, TaxServiceType, TaxTerminationType & TaxTransactionType set, otherwise normal sales tax will be applicable to the usage instead of usage specific taxes

  • The EngageIP option CDRLevelTax needs to exist in the EngageIPOption table for per UDR and batch UDR billing to function. If CDRLevelTax is not present in the table then usage taxing will occur when usage is billed

Configuring Taxing Per Record (UDR)

  1. Ensure your mediation code is configured to tax the appropriate tax types (see the usage requirements section above)

  2. Ensure the CDRLevelTax EngageIP option exists in the EngageIP database / EngageIPOptions table. If not add it with the insert statement below

    INSERT INTO EngageIPOption (Name,VALUE) VALUES ('CDRLevelTax','true')

  3. Ensure normal usages charges (without tax) are applied for test usage (i.e. usage feeds, UUIH, rates, rate groups, rate plans, tax code setup the service tax category)

  4. On the Setup page under UDR Feeds click the relevant feed to edit it

  5. Under the Processors section click Add

  6. Select SetUDRTaxing, choose a sort order and click Save

  7. Setup a service with a service tax category (in order to apply usage specific taxes)

  8. Ensure a tax code is configured with the service tax category and the tax code's tax vendor is set to the avatax vendor

  9. Add the service with the service tax category to a test package and ensure the package is configured with a UDR Rate Plan containing the proper usage rates

  10. Configure a test account, test user-package and test usage data to ensure usage taxing is working. See the Per Transaction Testing section below for steps

Configuring Batch Taxing Records (UDR)

  1. Enable batch taxing on the Configuration page

  2. Load the Tax Vendor and set the UDR Batch Size (this setting only appears if the 'Batch Taxing On Usage' option described above is enabled)

    Note: A maximum batch size of 1,000 is recommended by Avalara as performance degrades above that size

  3. Optional: Access the EngageIP app server and load the EngageIP\Services\UDRBatchTaxService.exe.config file. In the config file verify/adjust the settings to suit your environment:

    • the frequency that the usage taxes should be processed (pollingDelayInSeconds)

    • the number of threads to use (MinThread, MaxThread)

    • how long to retain data on taxes that have been processed (UDRBatchPendingTaxRecordRetentionPeriodInDays)

  4. Follow the same configuration as described in the Configuring Taxing Per Record (UDR) section above

  5. Start the Batch Taxing service

  6. Test to ensure taxes are applied in the batch size and time interval you configured. See the Testing Batch Usage Taxation section below for steps

Configuring Usage Taxing on Invoice Close

  1. Ensure Invoice Level Taxing is enabled on the Tax Vendor (credentials are provided by Avalara)

  2. Follow the same configuration as described in the Configuring Taxing Per Record (UDR) section above

  3. Test to ensure usage is taxed with the appropriate taxes and rates when a test account's invoice is closed. See the Testing Invoice Level Taxation section below for steps

Configuring Usage Taxing on Billing/Invoice Close

To enable taxing on billing or invoice close (whichever occurs first) you simply have to delete the CDRLevel tax entry in the EngageIPOption table. Otherwise the configuration instructions are identical to the Configuring Taxing Per Record (UDR) section above.

Configuring Tax Overrides

Tax overrides are configured in the AvaTax Admin Console. If you have issues accessing or using the Admin Console please contact Avalara.

Configuring Tax Bundles

Bundles can be configured on Avatax and used within EngageIP.

Requirements

  • Tax Vendor configuration is updated with profile ID in Avatax that is configured with the bundle. Usually 1 if there is only one profile configured

  • EZTaxTaxTypeMapping table must be added to with TS pair matching the TS pair specified on Avatax and using a name that matches a Service Tax Category in EngageIP

  • The Service Tax Category must be associated to a service

  • IIS Restart and service restarts are required to use these new configurations

  1. Run the queries below to add the custom bundle name into the database for use in the UI

    Insert into EZTaxTaxTypeMapping (Name, Module, TransactionType, ServiceType)values ('CustomEzTaxBdl1', 'Custom', 20000, 20001)

     

Post Configuration Testing

Per Transaction Testing

  1. Create a test account in the AdminPortal

  2. Setup a valid address on the billing contact

  3. After the address is loaded click on the address on the contact and a Jurisdiction Code should be displayed


    Note: if a Jurisdiction Code is not added check the Event Log Report to see if there are any errors in relation to adding the JCode

  4. Check the account's Overview page to ensure the Default Tax Code is listed

  5. Add a package to the test account and bill it (i.e. leave the Bill Now checkbox enabled)
    Configure a Service with valid TaxType, if Service is not configured with TaxType, then Default TaxType: Sales Product is used (i.e. TransactionType: 10 and ServiceType: 15).

  6. Load the Transactions page and the taxed amount should be shown

  7. Clicking the ID column on the Transactions page (not shown in the image above) will provide additional details. Specifically the Tax Code used to apply the tax and the specific tax and rate applied will be displayed

Testing Usage Taxation

  1. Create a test account and add an address to the billing contact

  2. Ensure the Jurisdiction Code is added to the billing contact's address after the address is added

  3. Add the test package to the test account and ensure the usage identifier (UUIH) value is populated when configuring the user-package

  4. If not already running, start the EngageIP rating and billing Windows services

  5. Add test usage / a usage record relating to the test service's UUIH and ensure it the usage record is processed without a rating exception

  6. On the Tools page bill the account and ensure the Date and DateEnd range you enter covers the time the usage occurred / the date specified in the test usage record

  7. Check the account's Transactions page and locate the usage
    Note: the transactions may not appear for a minute or two depending on how busy the EngageIP app server is with queued events/jobs 

  8. Click on the usage charge to edit it and the Transactions section will list the taxes that have been applied. The expected taxes and rates for the usage in question should be displayed

Testing Batch Usage Taxation

  1. Follow the Testing Usage Taxation steps above

  2. Verify that the batch taxing occurs when the pollingDelayInSeconds (configured frequency) is reached. Even if only one usage record needs to be taxed the data will be sent to the Avalara server for tax calculation (the system will not wait until the batch size is reached)

  3. Generate enough test usage to exceed the UdrBatchSize. When the polling time is reached check the Event Log to verify that the UdrBatchSize is broken up into more than one batch (Event Log 'Action' column can be filtered by 'ProcessBatchUDRTaxes' to find the batch taxing events. The total number of batches and records will be shown in the 'Result' column)

  4. If you wish to see the transactions and taxes applied to the test account, load the account and bill it via Tools / Bill Account. Ensure the date range you bill for covers the date the usage occurred on

Testing Invoice Level Taxation

This process is very similar to the per transaction test steps above, you simply have to add the step of closing the invoice once the package has been billed on the test account. After the invoice is closed taxes will appear on the Transactions tab as described above.

Note: Taxing at an invoice level as configured on the Tax Vendor config on setup will tax based on the invoice date (transaction date is not considered when applying tax in this fashion). When the invoice is closed, the invoice date is calculated based on bill group settings for invoice close date, and at that time, it calculates the tax using the invoice date that is set on the invoice.

Logs and Reports

  • The Tax Log contains a high level of detail on taxes that have been applied

  • The Event Log captures system event details and is useful for verifying which events have occurred or failed. For instance, if jurisdiction codes are not being added to contact addresses the event log should contain failure messages indicating the cause (e.g.

  • Custom Report – Missing Billsoft Jurisdiction Codes