Introduction

Taxrates.io delivers 14,000 US sales tax, VAT rate GST, rate directly to you via API. Built for Scale & High Availability, our simple, composable APIs are perfect for cross-border enterprises. Using our API removes the risk if using an incorrect tax rate and frees up time from monitoring global tax rate and so you can spend more time on product development. Click on any methods name on the right side to see details of request, parameters and response.

Authentication (oAuth2 Bearer)

Authenticate your account when using the API by including your API Client ID and API Client Secret in the request. You can check your API keys in the Dashboard when you sign up for an account. All accounts have 30 days Free usage of our API requests, if you need more time please contact us - support@taxrates.io Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth. To use API, you need call two enpoints:

  1. GET /oauth/token - to obtain your one time token - check in API reference
    
    /**
    * Javascript code example
    * Taxrates.io API - get token
    **/
    var taxrates_key = localStorage.getItem("Taxrates_API_Client_Key");
    var taxrates_secret = localStorage.getItem("Taxrates_API_Client_Secret");
    var taxrates_api_url = 'https://api.taxrates.io/api/v1/';
    var taxrates_endpoint = 'oauth/token';
    var taxrates_params = {'domain':'api.taxrates.io','clientid':taxrates_key,'clientsecret':taxrates_secret,'clientscope':'api_member'};
    var taxrates_url = taxrates_api_url + taxrates_endpoint;
    jQuery.support.cors = true;
    jQuery.ajax({
           url: taxrates_url,
           type: "get",
           method: "get",
           async: false,
           data: taxrates_params,
           dataType: "json",
           headers: {
                  "accept": "application/json"
              },
              success: function (data) {
              	localStorage.setItem("Taxrates_API_Token", data.token);
              }
    }).fail(function(xhr) {
    	//use to track errors
        return false;
    });
    if(localStorage.getItem("Taxrates_API_Token")){
    	return true;
    }else{
    	//use to track errors
    	return false;
    }
    									
  2. GET /oauth/dialog - to obtain your Bearer authorization header - the Bearer authorization string is something you will have to include in every API request. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authorization header will also fail. - check in API reference
    
    /**
    * Javascript code example
    * Taxrates.io API - authorize token
    **/
    var taxrates_key = localStorage.getItem("Taxrates_API_Client_Key");
    var taxrates_secret = localStorage.getItem("Taxrates_API_Client_Secret");
    var taxrates_token = localStorage.getItem("Taxrates_API_Token");
    var taxrates_url = 'https://api.taxrates.io/api/v1/';
    var taxrates_endpoint = 'oauth/dialog';
    var taxrates_params = {'domain':'api.taxrates.io', 'token':taxrates_token, 'clientscope':'api_member'};
    if (taxrates_token){
    	jQuery.support.cors = true;
    	jQuery.ajax({
    		url: taxrates_url+taxrates_endpoint,
            type: "get",
            method: "get",
            async: false,
            data: taxrates_params,
            dataType: "json",
            headers: {
                   "accept": "application/json"
               },
               success: function (data) {
               	localStorage.setItem("Taxrates_API_Bearer", data.Authorization);
               	localStorage.setItem("Taxrates_API_Session", data.Session);
               }
    	}).fail(function(xhr) {
    		//Maintain errors here
    		var httpStatus = (xhr.status);
            var ajaxError = 'There was an requesting the call back. HTTP Status: ' + httpStatus;
            console.log('Auth ajaxError: ' + ajaxError);
            return false;
    	});
    }else{
    	//No token - storage problem?
    	//Maintain errors here
    	return false;
    }
    if(localStorage.getItem("Taxrates_API_Bearer")){
    	//Success!
    	return true;
    }else{
    	//Not authorized - API cred problem? Token problem?
    	//Maintain errors here
    	return false;
    }
    									

Required parameters

  1. Authorization header with string starting from "Bearer: XXX" - the authorization string you have to obtain before making any requests to resource endpoints. Please see authentication section.
  2. Domain: must always be api.taxrates.io

Errors

The taxrates.io API will return ErrorCode and ErrorMessage if something will go wrong. Common codes returned by the taxrates.io API are:

1. 200 - OK


/**
* 200 return example
**/
{
    "Rates": {
        "India": {
            "taxes": [
                {
                    "Country": "India",
                    "Type": "standard",
                    "data_name": "Rate",
                    "data_value": "18"
                },
                {
                    "Country": "India",
                    "Type": "reduced",
                    "data_name": "Rate",
                    "data_value": "12"
                },
                {
                    "Country": "India",
                    "Type": "second reduced",
                    "data_name": "Rate",
                    "data_value": "5"
                }
            ]
        },
        "Austria": {
            "taxes": [
                {
                    "Country": "Austria",
                    "Type": "standard",
                    "data_name": "Rate",
                    "data_value": "20"
                },
                {
                    "Country": "Austria",
                    "Type": "reduced",
                    "data_name": "Rate",
                    "data_value": "13"
                },
                {
                    "Country": "Austria",
                    "Type": "second reduced",
                    "data_name": "Rate",
                    "data_value": "10"
                }
            ]
        }
    }
}

2. 400 - Bad Request - something got terribly wrong
3. 401,403 - Unauthorized - you have to refresh the token and get new Bearer authorization string

/**
* 403 return example
**/
{
    "ErrorCode": "403",
    "ErrorMessage": "Not authorized."
}

4. 404 - Not Found (either resource or data)

/**
* 404 return example
**/
{
    "ErrorCode": "404",
    "ErrorMessage": "Country "
}

5. 429 - Too Many Requests
6. 5XX - Server Errors
7. Empty rates

/**
* Request example to get empty array
**/
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.taxrates.io/api/v1/tax/byaddress?domain=api.taxrates.io",
  "method": "POST",
  "headers": {
    "authorization": "Bearer: eyJ0eXAiOiAiSldUIiwgImFsZyI6IlJTMjU2In0=.ewoJCQkJCQkgICJpZCI6IGIwNDBhMzVmNmU0YjdjNjE1ZThhOWI1NTcwOWRiZjdiMjI5MDExNTEsCgkJCQkJCSAgImp0aSI6IGIwNDBhMzVmNmU0YjdjNjE1ZThhOWI1NTcwOWRiZjdiMjI5MDExNTEsCgkJCQkJCSAgImlzcyI6IDAsCgkJCQkJCSAgImF1ZCI6ICwKCQkJCQkJICAic3ViIjogLAoJCQkJCQkgICJleHAiOiAxNTA0Njc2NDM0LAoJCQkJCQkgICJpYXQiOiAxNTA0ODkyNDM0LAoJCQkJCQkgICJ0b2tlbl90eXBlIjogImJlYXJlciIsCgkJCQkJCSAgInNjb3BlIjogImFwaV9tZW1iZXIiCgkJCQkJCX0=",
    "content-type": "application/json",
    "cache-control": "no-cache",
    "postman-token": "144ee953-eaf1-148f-c898-d56e1eada9e9"
  },
  "processData": false,
  "data": "{\n\t\"street\":\"MyStreetName\",\n\t\"street_number\":\"107\",\n\t\"apartment_number\":\"d23\",\n\t\"city\":\"New York City\",\n\t\"state\":\"NYC\",\n\t\"country\":\"USA\"\n}"
}
$.ajax(settings).done(function (response) {
  console.log(response);
});
/**
* Empty rates return example
**/
{
    "Rates": {
        "USA": {
            "taxes": []
        }
    }
}

Resources

Rates

Rates contain all tax rates for selected country.

The rate limits

Retrieving rates might be limited by:
-number of countries you have selected on your dashboard
-number of API hits available for your account

The rate types

Rates always have one of following types:
-standard
-reduced
-second reduced
-third reduced
-super reduced
-CombinedRate
-StateRate
-CountyRate
-CityRate
-SpecialRate

When calling API endpoint you can always use 'filter' parameters to filter out the API response and get only selected types of tax rates. You should consult a tax professional to understand what VAT, GST & tax rate apply to your product or service.

When you've had selected United States on your Taxrates.io member's dashboard then you have to provide a zip code to get proper taxes. Otherwise Taxrates.io API will return an error. If the zip code will not match any of zip codes from any state you have selected on your dashboard then the rates for United States will not be shown.

Endpoints

Methods limits

Each API method is limited the same way as rates are. Additional limits might happen when trying to get rates based on IP addresses, it might happen that IP records shared by IANA are not up-to-date with geo regions. Also, it might happen that you are behind firewall which changes your external IP address.

Methods filters

When calling taxrates.io API endpoints you can use 'filter' parameters to get taxes of selected type.

Get all rates

Get request. This method returns all tax rates configured on Member's account. Based on Member's country selection the endpoint will return all taxes for all countries of the Member. You can use 'filter' parameter to narrow results to selected type of tax. Use 'zip' paramter when you have had selected United States.Check in API reference


/**
* Javascript code example
* Taxrates.io API - get rates
**/
var taxrates_endpoint = 'tax/rates';
var taxrates_params = {'domain':'api.taxrates.io', 'session_id':localStorage.getItem("Taxrates_API_Session")};
var taxrates_url = 'https://api.taxrates.io/api/v1/';
if ( localStorage.getItem("Taxrates_API_Session") && localStorage.getItem("Taxrates_API_Bearer") ){
jQuery.support.cors = true;
jQuery.ajax({
    url: taxrates_url+taxrates_endpoint,
    type: 'get',
    method: 'get',
    dataType: "json",
    data: taxrates_params,
    beforeSend: function (request) {
            request.withCredentials = true;
            request.setRequestHeader("Authorization", localStorage.getItem("Taxrates_API_Bearer"));
    },
    headers: {
    	"accept": "application/json"
    },
    contentType: 'application/json; charset=utf-8',
    success: function (data) {
    	//Maintain errors inside success because the API may return 200 in general, but different code inside
        if(data.ErrorCode=='404' || data.ErrorCode=='500'){
        	//Maintain errors here
        	console.log(data.ErrorMessage);
        	return false;
        }else{
         	var rates = [];
         	var i=0;
         	var taxrates_range = '';
         	jQuery.each(data.Rates, function(k, v) {
         	    if(v.hasOwnProperty("taxes")){
         	    	jQuery.each(v.taxes, function(m, w) {
         	    		rates[i] = [];
         	    		//Only showing standard rate type
         	    		if( w.Type == "standard" ){
          	    		rates[i][0] = w.Country;
          	    		rates[i][1] = w.Type;
          	    		rates[i][2] = w.data_value;
          	    		i++;
         	    		}
         	    	});
         	    }
         	//Now you have all your rates inside rates variable.
         	}).fail(function(xhr) {
		        	//Maintain your errors here
		        	return false;
			});
    		return true;
}else{
	//Not logged into taxrates.io
	//Maintain your errors here  		
	return false;
}
							

Get rates by IP

Get request. This method returns all tax rates for country discovered on either your IP address or IP address param. The IP param is not required. When empty, the taxrates.io will try to discover your IP address and based on this will try to retrieve tax rates. You can use 'filter' parameter to narrow results to selected type of tax. Check in API reference


/**
* Javascript code example
* Taxrates.io API - get rates by IP
**/
var taxrates_endpoint = 'tax/ip';
var taxrates_params = {'domain':'api.taxrates.io', 'session_id':localStorage.getItem("Taxrates_API_Session"), 'ip':'208.80.152.201'};
var taxrates_url = 'https://api.taxrates.io/api/v1/';
if ( localStorage.getItem("Taxrates_API_Session") && localStorage.getItem("Taxrates_API_Bearer") ){
jQuery.support.cors = true;
jQuery.ajax({
    url: taxrates_url+taxrates_endpoint,
    type: 'get',
    method: 'get',
    dataType: "json",
    data: taxrates_params,
    beforeSend: function (request) {
            request.withCredentials = true;
            request.setRequestHeader("Authorization", localStorage.getItem("Taxrates_API_Bearer"));
    },
    headers: {
    	"accept": "application/json"
    },
    contentType: 'application/json; charset=utf-8',
    success: function (data) {
    	//Maintain errors inside success because the API may return 200 in general, but different code inside
        if(data.ErrorCode=='404' || data.ErrorCode=='500'){
        	//Maintain errors here
        	console.log(data.ErrorMessage);
        	return false;
        }else{
         	var rates = [];
         	var i=0;
         	jQuery.each(data.Rates, function(k, v) {
         	    if(v.hasOwnProperty("taxes")){
         	    	jQuery.each(v.taxes, function(m, w) {
         	    		rates[i] = [];
         	    		//Only showing standard rate type
         	    		if( w.Type == "standard" ){
          	    		rates[i][0] = w.Country;
          	    		rates[i][1] = w.Type;
          	    		rates[i][2] = w.data_value;
          	    		i++;
         	    		}
         	    	});
         	    }
         	//Now you have all your rates inside rates variable.
         	}).fail(function(xhr) {
		        	//Maintain your errors here
		        	return false;
			});
    		return true;
}else{
	//Not logged into taxrates.io
	//Maintain your errors here  		
	return false;
}
							

Get rates by country code

Get request. This method returns all tax rates for country discovered based on country code. The country code must be 2 letters ISO 3166-1 alfa-2 country code. You can use 'filter' parameter to narrow results to selected type of tax. Check in API reference


/**
* Javascript code example
* Taxrates.io API - get rates by country code
**/
var taxrates_endpoint = 'tax/countrycode';
var taxrates_params = {'domain':'api.taxrates.io', 'session_id':localStorage.getItem("Taxrates_API_Session"), 'country_code':'IE'};
var taxrates_url = 'https://api.taxrates.io/api/v1/';
if ( localStorage.getItem("Taxrates_API_Session") && localStorage.getItem("Taxrates_API_Bearer") ){
jQuery.support.cors = true;
jQuery.ajax({
    url: taxrates_url+taxrates_endpoint,
    type: 'get',
    method: 'get',
    dataType: "json",
    data: taxrates_params,
    beforeSend: function (request) {
            request.withCredentials = true;
            request.setRequestHeader("Authorization", localStorage.getItem("Taxrates_API_Bearer"));
    },
    headers: {
    	"accept": "application/json"
    },
    contentType: 'application/json; charset=utf-8',
    success: function (data) {
    	//Maintain errors inside success because the API may return 200 in general, but different code inside
        if(data.ErrorCode=='404' || data.ErrorCode=='500'){
        	//Maintain errors here
        	console.log(data.ErrorMessage);
        	return false;
        }else{
         	var rates = [];
         	var i=0;
         	jQuery.each(data.Rates, function(k, v) {
         	    if(v.hasOwnProperty("taxes")){
         	    	jQuery.each(v.taxes, function(m, w) {
         	    		rates[i] = [];
         	    		//Only showing standard rate type
         	    		if( w.Type == "standard" ){
          	    		rates[i][0] = w.Country;
          	    		rates[i][1] = w.Type;
          	    		rates[i][2] = w.data_value;
          	    		i++;
         	    		}
         	    	});
         	    }
         	//Now you have all your rates inside rates variable.
         	}).fail(function(xhr) {
		        	//Maintain your errors here
		        	return false;
			});
    		return true;
}else{
	//Not logged into taxrates.io
	//Maintain your errors here  		
	return false;
}
							

Get rates by address

Post request. This method returns all tax rates for the country discovered based on a given address. You can use 'filter' parameter to narrow results to selected type of tax. For US the address in body must contain zip code.Check in API reference


/**
* Javascript code example
* Taxrates.io API - get rates by country code
**/
var taxrates_endpoint = 'tax/address';
var taxrates_params = '?domain=api.taxrates.io&session_id='+localStorage.getItem("Taxrates_API_Session");
var taxrates_url = 'https://api.taxrates.io/api/v1/';
var taxrates_body = '{
	"street":"MyStreetName",
	"street_number":"107",
	"apartment_number":"d34",
	"city":"Dublin",
	"zip":"84534"
	"state":"",
	"country":"Ireland"
}';
if ( localStorage.getItem("Taxrates_API_Session") && localStorage.getItem("Taxrates_API_Bearer") ){
jQuery.support.cors = true;
jQuery.ajax({
    url: taxrates_url+taxrates_endpoint+taxrates_params,
    type: 'post',
    method: 'post',
    dataType: "json",
    data: taxrates_body,
    beforeSend: function (request) {
            request.withCredentials = true;
            request.setRequestHeader("Authorization", localStorage.getItem("Taxrates_API_Bearer"));
    },
    headers: {
    	"accept": "application/json"
    },
    contentType: 'application/json; charset=utf-8',
    success: function (data) {
    	//Maintain errors inside success because the API may return 200 in general, but different code inside
        if(data.ErrorCode=='404' || data.ErrorCode=='500'){
        	//Maintain errors here
        	console.log(data.ErrorMessage);
        	return false;
        }else{
         	var rates = [];
         	var i=0;
         	jQuery.each(data.Rates, function(k, v) {
         	    if(v.hasOwnProperty("taxes")){
         	    	jQuery.each(v.taxes, function(m, w) {
         	    		rates[i] = [];
         	    		//Only showing standard rate type
         	    		if( w.Type == "standard" ){
          	    		rates[i][0] = w.Country;
          	    		rates[i][1] = w.Type;
          	    		rates[i][2] = w.data_value;
          	    		i++;
         	    		}
         	    	});
         	    }
         	//Now you have all your rates inside rates variable.
         	}).fail(function(xhr) {
		        	//Maintain your errors here
		        	return false;
			});
    		return true;
}else{
	//Not logged into taxrates.io
	//Maintain your errors here  		
	return false;
}