--------------------------------------------------------------
Last Modified : 19 Mar 2022
***********************************************************************************
Contents:
A. SUMMARY
B. FILE STRUCTURE
C. INSTALLATION INSTRUCTION
D. HOW IT WORKS
E. CONFIGURATION SETTINGS CHANGED
F. DATABASE TABLES MODIFIED
G. LANGUAGE SETTINGS CHANGED
H. CHANGE LOGS
I. TROUBLESHOOTING
J. COPYRIGHT NOTICE
K. TERMS AND CONDITIONS
***********************************************************************************
A. SUMMARY
==========
This module provides automatic sales tax calculations within your cart, streamlining the tax compliance process while saving time, reducing errors, and cutting costs.
For more details about Avalara Tax, please visit https://www.avalara.com/
NOTE : This addon is also compatible with onepage checkout.
***********************************************************************************
B. FILE STRUCTURE
===================
Files included in the zip are:
- $avalaratax900_readme.html
- shopavalarataxaspjson1.17.asp
- shopavalarataxbase64hash.asp
- shopavalarataxconfig.asp
- shopavalarataxsub.asp
- shopavalarataxxmlhttp.asp
- shoponepage_updateavalara.asp
- admin/avalaratax_setup.asp
- admin/avalaratax_setup_config.asp
- admin/avalaratax_setup_process.asp
- admin/shopa_avalaratax_subs.asp
- admin/help/shoph_producthelp.asp
- admin/sqlscripts/avalaratax/access.txt
- admin/sqlscripts/avalaratax/mysql.txt
- admin/sqlscripts/avalaratax/sqlserver.txt
- plugins/stylesheets/avalaratax.css
***********************************************************************************
C. INSTALLATION INSTRUCTION
============================
1. Upload the below files to VPCart root folder.
- shopavalarataxaspjson1.17.asp
- shopavalarataxbase64hash.asp
- shopavalarataxconfig.asp
- shopavalarataxsub.asp
- shopavalarataxxmlhttp.asp
- shoponepage_updateavalara.asp
1a. Upload the below file to plugins\stylesheets folder :
- avalaratax.css
1b. Upload the below files to your ADMIN folder. If you have renamed your ADMIN folder, then this must be placed in the renamed folder.
- admin/sqlscripts/avalaratax/access.txt
- admin/sqlscripts/avalaratax/mysql.txt
- admin/sqlscripts/avalaratax/sqlserver.txt
- admin/avalaratax_setup.asp
- admin/avalaratax_setup_config.asp
- admin/avalaratax_setup_process.asp
- admin/shopa_avalaratax_subs.asp
- admin/help/shoph_producthelp.asp
2. Download the files below from your server via FTP and follow the instructions below to modify the files.
- shop$db.asp
- shop_load_othercss_subs.asp
- shop_load_otherjs_subs.asp
- shopcartformat.asp
- shopcreateorder.asp
- shopmysqlsubs.asp
- shopcheckout_subs.asp
- admin/shopa_addproduct.asp
2.1 Open the file shop$db.asp with your favorite editor
2.1a. Locate below line, estimate line 2948
UpdateField "ocurrencyrate", GetSess("Conversionvalue")
2.1b. Below this code, please insert : 'Avalara Tax - v9
if GetConfig("xavalarataxenable")= "Yes" then
UpdateField "avalararesponsestatus", GetSess("avalararesponsestatus")
end if
2.1c. Save the file
2.2 Open the file shop_load_othercss_subs.asp with your favorite editor
2.2a. Locate very bottom code below :
%>
2.2b. Before this code, please insert :'Avalara Tax - v9
sub load_avalaratax_error_css
if lcase(getconfig("xavalarataxenable")) <> "yes" then exit sub
%>
<link rel="stylesheet" type="text/css" href="plugins/stylesheets/avalaratax.css" />
<%
end sub
2.2c. Save the file
2.3 Open the file shop_load_otherjs_subs.asp with your favorite editor
2.3a. Locate very bottom code below :
%>
2.3b. Before this code, please insert :'Avalara Tax - v9
sub load_avalaratax_error_js
if lcase(getconfig("xavalarataxenable")) <> "yes" then exit sub
%>
<script type="text/javascript">
<!--
// Get the modal
var modal = document.getElementById('myModal');
document.getElementById('myBtn').setAttribute('class','btnmodal-validate submitbtn');
// Get the button that opens the modal
var modalbtns = document.querySelectorAll('.btnmodal-validate')
// Get the <span> element that closes the modal
var span = document.getElementsByClassName("close-avalara")[0];
// When the user clicks on <span> (x), close the modal
span.onclick = function() {
modal.style.display = "none";
}
// When the user clicks the button, open the modal
for( var i = 0; i < modalbtns.length; i++){
modalbtns[i].addEventListener('click', function(event){
event.preventDefault();
modal.style.display = "block";
})
}
// When the user clicks anywhere outside of the modal, close it
window.onclick = function(event) {
if (event.target == modal) {
modal.style.display = "none";
}
}
-->
</script>
<%
end sub
2.4 Open the file shopcartformat.asp with your favorite editor
2.4a. Locate below line, estimate line 5,
<!--#include file="shopcartformatdesign.asp"-->
2.4b. Below this code, please insert :<!-- 'Avalara Tax - v9-->
<!--#include file="shopavalarataxsub.asp"-->
CartFormatTax
2.4d. Please replace to :'Avalara Tax - v9
if instr(lcase(request.ServerVariables("SCRIPT_NAME")),"shopcheckout.asp") > 0 and getconfig("xavalarataxenable") ="Yes" then
CartFormatTaxAvalara
else
CartFormatTax
end if
2.4e. Save the file
2.5 Open the file shopcustomerdesign.asp with your favorite editor.
2.5a. Locate below code, estimate line 373 (inside sub AddSubmitButton)
ShopButton GetConfig("xbuttoncontinue"),trim(GetLang("langCommonContinue")),""
2.5b. Please replace to : 'Avalara Tax - v9
session("AvalaraError") = ""
'validate avalara address
avalaraValidateAddress
if GetConfig("xavalarataxenable") = "Yes" and session("AvalaraError") <> "" then
load_avalaratax_error_css
%>
<button id="myBtn" class="submitbtn"><%=GetLang("langCommonContinue")%></button>
<!-- The Modal -->
<div id="myModal" class="modal-avalara">
<!-- Modal content -->
<div class="modal-content-avalara">
<div class="modal-header-avalara">
<span class="close-avalara">x</span>
<h2>Checkout Error</h2>
</div>
<div class="modal-body-avalara">
<p><%=GetLang("langAvalaraError") & "<BR><BR>" & GetLang("langAvalaraErrorDetails") & getsess("AvalaraError")%></p>
</div>
</div>
</div>
<%
load_avalaratax_error_js
else
ShopButton GetConfig("xbuttoncontinue"),trim(GetLang("langCommonContinue")),""
end if
2.5c. Save the file
2.6 Open the file shopmysqlsubs.asp with your favorite editor
2.6a. Locate below line , estimate line 1286
mysqlnumbfield sqlo, "taxfree", strtaxfree
2.6b. Below this code, please insert :'Avalara Tax - v9
UpdateMySQLAvalaraTaxFields sqlo
2.6c. Save the file
2.7 Open the file admin/shopa_addproduct.asp with your favorite editor
2.7a. Locate below line , estimate line 12
<!-- #include file="shopa_upsell_subs.asp" -->
2.7b. Below this code, please insert :<!-- 'Avalara Tax - v9 -->
<!--#include file="shopa_avalaratax_subs.asp"-->
2.7c. Locate below line in the sub GetFormData routine, estimate line 441
strtaxfree = request("strtaxfree")
2.7d. Below this code, please insert : 'Avalara Tax - v9
GetRequestAvalaraTax
2.7e. Locate below line, estimate line 1150
FormateditfullrowBooleanAdmin GetLang("LangTaxfree"), "strtaxfree", strtaxfree, yesnos, yesnocount, "document.all.help_taxfree"
2.7f. Below this code, please insert :'Avalara Tax - v9
GenerateAvalaraTaxForm
2.7g. Locate below line, estimate line 1871
CorrectBooleanProgram_admin strtaxfree
2.7h. Below this code, please insert :'Avalara Tax - v9
GetAvalaraTaxFromDB getobjrs
2.7i. Locate below line, estimate line 3043
pUpdateField "taxfree", strtaxfree
2.7j. Below this code, please insert :'Avalara Tax - v9
UpdateAvalaraTaxFields
2.7k. Save the file
2.8 Open the file shoponepagecheckout_common_subs.asp with your favorite editor
2.8a. Locate below line , estimate line 205
session("onepagepostprocess") = ""
2.8b. Below this code, please insert : 'Avalara Tax - v9
session("avalarataxonepage") = ""
2.8c. Save the file
2.9 Open the file shoponepagecheckout_cart_subs.asp with your favorite editor
2.9a. Locate below line , estimate line 5
<!-- #include file="shopsurchargecalc.asp"-->
2.9b. Below this code, please insert : <!-- 'Avalara Tax - v9 -->
<!--#include file="shopavalarataxsub.asp"-->
2.9c. Locate below line , estimate line 342 (inside sub CartFormatTax_onepage)
CalculateTax cartsubtotal, carttotal, cartshipcost, Taxes, pst
2.9d. Please replace to : 'Avalara Tax - v9
if GetConfig("xavalarataxenable")<>"Yes" then
CalculateTax cartsubtotal, carttotal, cartshipcost, Taxes, pst
else
avalaraCalculateTax
taxes = getsess("avalarataxonepage")
end if
2.9e. Save the file
2.10 Open the file plugins/checkout/onepagecheckout.js with your favorite editor
2.10a. Locate below line , estimate line 325-340
//'800 - 2015.05.28 - Onepage checkout: Better presentation on cart summary with tax and others
//'800 - 2018.02.08 - Onepage checkout: To work with tax by county
$(document).on('change keyup','#strstate,#strcountry',function(){
//2019.12.20 - Onepage checkout: Better hanlding on state changes for tax and shipping process
if ( $('[name="shipmethodType"]').length <= 0 ){
var strstate_onepage = $('#strstate').val();
var strcountry_onepage = $('#strcountry').val();
//'800 - 2018.02.08 - Onepage checkout: To work with tax by county
var strpostcode_onepage = $('#strpostcode').val();
applytax_onepage (strstate_onepage,strcountry_onepage,strpostcode_onepage);
//2019.12.20 - Onepage checkout: Better hanlding on state changes for tax and shipping process
}
});
// Avalara Tax - v9
$(document).on('change keyup','#shipaddress,#shiptown,#shipstate,#shipzip,#strcountry',function(){
var straddress_onepage = $('#shipaddress').val();
var strcity_onepage = $('#shiptown').val();
var strstate_onepage = $('#shipstate').val();
var strzip_onepage = $('#shipzip').val();
var strcountry_onepage = $('#strcountry').val();
applyavalara_onepage (straddress_onepage,strcity_onepage,strstate_onepage,strzip_onepage,strcountry_onepage);
});
2.10c. Go to very bottom of the file and insert this code :
// Avalara Tax -
function applyavalara_onepage (addressvalue,cityvalue,statevalue,postalcodevalue,countryvalue){
var target = "onepage_prices_wrapper";
//'800 - 2015.07.01 - change all spiner to bootstrap font spiner
$("#"+ target +"").html("<i class='fa fa-spinner fa-spin'></i> "+ langprocessing +"");
var checkingurl="shoponepage_updateavalara.asp";
var pars="source=avalara&paddress="+ encodeURI(escape(addressvalue)) +"&pcity="+ encodeURI(escape(cityvalue)) +"&pstate="+ encodeURI(escape(statevalue)) +"&ppostalcode="+ encodeURI(escape(postalcodevalue)) +"&pcountry="+ encodeURI(escape(countryvalue)) +"";
$.ajax({
type:'POST',
url : checkingurl,
data : pars,
success: function(data){
$('#' + target).html(data);
}
});
}
<%
2.11b. Before this code, please insert :<!-- 'Avalara Tax - v9-->
<!--#include file="shopavalarataxsub.asp"-->
CartFormatprice_checkout GetLang("langProductTax"), rs("otax"), xdecimalpoint,"computation_wrapper_nobordertop"
2.11d. Please replace to : 'Avalara Tax - v9
if instr(lcase(request.ServerVariables("SCRIPT_NAME")),"shopcheckout.asp") > 0 and getconfig("xavalarataxenable") ="Yes" then
CartFormatTaxAvalara
else
CartFormatprice_checkout GetLang("langProductTax"), rs("otax"), xdecimalpoint,"computation_wrapper_nobordertop"
end if
2.11e. Save the file
3. Upload all amended files above to your server.
4.
Log into VPCart Admin.
5. Execute setup file, eg: https://www.yourdomain.com/yourshoppingcartfolder/youradminfolder/avalaratax_setup.asp.
6. After setup the module, would be redirected to Module configuration page to configure the module.
Please fill in the required fields :
Enable? : Set to Yes to enable this module.
Account Number : Enter your Avalara account number.
License Key : Enter your Avalara license key.
Company Code : Enter your company code.
Avalara get tax rate URL :
Enter Avalara Tax URL to get tax rate.
For testing enter : https://development.avalara.net/1.0/tax/get
For production enter : https://avatax.avalara.net/1.0/tax/get
Avalara validate address URL :
Enter Avalara Tax URL to validate address.
For testing enter : https://development.avalara.net/1.0/address/validate
For production enter : https://avatax.avalara.net/address/validate
Default Avalara tax code:
Enter the default Avalara tax code (if all products are having the same tax code).
Please refer to https://taxcode.avatax.avalara.com/.
If all products do not have same tax code, then leave this field empty, and you will need to edit each of your product to enter value for field "Avalara Tax Code".
Document Type :
The document type specifies the category of the document. Default value is SalesOrder.
Debug mode? :
Set to Yes, if you want to see debugging code of Avalara Tax send and receive status during checkout.
7. You need to define Tax Code
for each product or else system will get the global setting from the config: xavalaradefaulttaxcode
Step 1. Login to Admin and go to Store > Products
Step 2. Locate the product that you want to define a Tax Code then click on the icon under Edit column.
Step 3. At Product Setup page, locate a field "Avalara Tax Code" under section "Pricing and Stock Control"
Step 4. Enter a Tax Code. e.g. PC040065
For Tax Code value please refer to https://taxcode.avatax.avalara.com/
Step 5. Click on the Update record button to save.
***********************************************************************************
D. HOW IT WORKS
===============
Avalara tax at the front end.
Step 1. Visit the front store & add item to shopping cart as normal
Step 2. At page shopcustomer.asp, fill up all the customer and shipping information & click "Continue" button.
Or if you are using onepage checkout, fill up all the customer and shipping information and after that the tax will automatically be displayed.
Step 3. At this point, VPCart will send two requests to Avalara server :
- Validate address
- Request tax rate
If address is valid and order information is correctly passed to Avalara server then it will return a tax rate and display at shopcheckout.asp or will show automatically on onepage checkout page.
Step 4. At page shopcheckout.asp, click on Order Now button to process to payment.
If customers enter invalid address, it will popup warning message when clicking Proceed to Checkout button.
If merchant enter invalid Avalara account details, it will also popup warning message when clicking Proceed to Checkout button.
Your customers will be unable to checkout if the warning message is still exist.
Avalara tax at back end.
In the administration, you can configure the Avalara settings by going to the Modules > Modules Manager
Locate avalaratax record and click Edit.
Beside using this modules manager, to change those settings, you can also use software configuration search by going to:
Advanced Settings > Software Configuration
And enter keyword into the search box : avalara
Then click Search button.
It will the list all of the Avalara related configs for you to edit.
You can change the settings anytime you want.
In the add or edit products administration, merchant can enter Tax Code for every products.
Go to : Store > Products
Add/Edit the existing product record you want.
Then locate "Avalara Tax Code" field.
Please refer to https://taxcode.avatax.avalara.com/ to get your product Tax Code.
Also, merchant can check each order record for any response message returned by Avalara for the order during checkout when retrieving tax.
This can be checked by going to :
Store > Orders
Then locate the order record you want and click Edit.
And then locate the field "avalararesponsestatus" near the bottom.
In the backend, you can also change the Avalara captions to suit your own language liking.
a. Go to : Advanced Settings > International
b. Click Language tab and click Edit Language
c. In the Selection Criteria, choose "keyword", "equals".
d. In the textbox next to it, please enter : langAvalaraTaxCode or langAvalaraError or langAvalaraErrorDetails
e. Click Display.
f. A result will be displayed, click Edit.
g. In the "caption" field, you can change the value to your desired text.
h. Click Update record.
i. Click Back To Languages.
j. Click Reset Language.
k. Select your default language e.g. English, and click Continue.
Avalara Tax setting in your Avalara Merchant account
Merchants can set from their Avalara merchant account at https://admin.avalara.com and determine which states they want to take sales tax.
Below is the screenshot of Avalara merchant account setting for Sales Tax Nexus:
In the screenshot, for example we set state MA and TX to apply for sales tax.
With the above example setup, if your VPCart site has Avalara Tax module installed, and a customer from state MA or TX purchase items in your store, they will be charged for sales tax.
You can read more about this at:
https://www.avalara.com/us/en/learn/nexus.html
***********************************************************************************
E. CONFIGURATION SETTINGS CHANGED
New configrations added :
- xavalarataxenable
-
xavalarataxaccountnumber
- xavalarataxlicensekey
- xavalarataxcompanycode
-
xavalarataxgettaxurl
- xavalarataxvalidateaddressurl
-
xavalarataxdoctype
-
xavalaradefaulttaxcode
-
xavalarataxdebugmode
***********************************************************************************
F. DATABASE TABLES MODIFIED
===========================
1. Products table :
New field: avalarataxcode
2. Orders table :
New field: avalararesponsestatus
***********************************************************************************
G. LANGUAGE SETTINGS CHANGED
============================
New Languages:
- langAvalaraTaxCode - Avalara Tax Code
- langAvalaraError - Oops! There has been a problem retrieving tax rate for your address. Please recheck your address details and if you still cannot check out let us know by going to <a href=shopcustcontact.asp>Contact Us</a> page.
- langAvalaraErrorDetails - Response from tax provider
***********************************************************************************
H. CHANGE LOGS
============================
2016.11.04 - Added Address validation
2016.11.02 - Better error handling using modal popup
2016.10.27 - Get Avalara Tax rate routine
2016.12.06 - Support onepage checkout
2018.05.02 - Compatible with v9
I. TROUBLESHOOTING
============================
Troubleshootting is much more easier now using this Avalara Tax module as if any error msg will be showing in modal popup during checkout and reason of the error msg is displayed for customers.
For merchant, if there is issue with this Avalara Tax, you can try to turn on Debug mode from the modules manager for this module and try to checkout and it will display the debugging message on send request and response from Avalara.
Also, in Orders table, merchant can refer to field avalararesponsestatus value if you need to check the status of Avalara Tax response for the order record you want.
J. COPYRIGHT NOTICE
============================
Copyright (c) 1999-2023 Rocksalt International Pty. Ltd.
All rights reserved.
This software and documentation constitute a published work and
contains valuable trade secrets and proprietary information
belonging to Rocksalt International Pty. Ltd. .
None of the foregoing material may be copied,
duplicated or disclosed without the express written permission
of Rocksalt International Pty. Ltd. .
LICENSEE ACCEPTS VP-ASP Shopping Cart "AS IS" "WITH ALL FAULTS",
Rocksalt International Pty. Ltd. accepts no responsibility for the
operation or performance of the VP-ASP Shopping Cart.
The entire risk of use and consequences of use of the
VP-ASP Shopping Cart falls completely on the Licensee
and Rocksalt International Pty. Ltd. shall not be liable in any respect
for any claims, loss or injury alleged to have resulted
from use of or in reliance on VP-ASP Shopping Cart.
Licensee acknowledges that it has read the foregoing
disclaimers of warranty and limitation of liability
and understands that Licensee assumes
the entire risk of using VP-ASP Shopping Cart.
***********************************************************************************
K. TERMS AND CONDITIONS
============================
ROCKSALT INTERNATIONAL GRANTS TO THE LICENSEE A NON-EXCLUSIVE,
NON-SUB LICENSABLE, NONTRANSFERABLE LICENSE
TO INSTALL AND USE THIS APPLICATION ON A SINGLE DOMAIN FOR
A SINGLE SHOP.
THE CODE IN THE APPLICATION MAY BE MODIFIED FOR USE IN
SETTING UP A SINGLE SHOPPING SITE ON THE WORLD WIDE WEB.
LICENSEE MAY MAKE A COPY OF THE APPLICATION FOR
BACK-UP AND ARCHIVAL PURPOSES, PROVIDED THAT ANY COPY
MUST CONTAIN ALL PROPRIETARY NOTICES INCLUDED
WITH THE APPLICATION.
LICENSEE IS PROHIBITED FROM SELLING OR DISTRIBUTING
THE APPLICATION IN ANY MANNER.
LIMITATION OF LIABILITY.
ROCKSALT INTERNATIONAL AND ITS LICENSORS SHALL
NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE OR ANY
THIRD PARTY AS A RESULT OF USING OR DISTRIBUTING THIS
APPLICATION.
IN NO EVENT WILL ROCKSALT INTERNATIONAL OR ITS LICENSORS
BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA,
OR FOR DIRECT, INDIRECT, SPECIAL,
CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES,
HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LI
ARISING OUT OF THE USE OF OR INABILITY TO USE THE SOFTWARE,
EVEN IF ROCKSALT INTERNATIONAL HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.