Taxrates.io API API Reference

Taxrates.io is a global tax rate service that automates the management of monitoring tax rates changes in 181 countries. We monitor over 14,000 US sales tax, VAT, GST rates for you and make updates via our API so you always have the most update tax rates.

You can use Taxrates.io as a virtual sandbox where we provide you with 30 days free trial.

API Endpoint
https://api.taxrates.io/api
Terms of Service: https://taxrates.io/terms-of-service
Request Content-Types: application/json
Response Content-Types: application/json
Schemes: https
Version: 3.0

Countries

We currently support the following countries around the world. If you would like to request the addition of a new country, please email us at support@taxrates.io

Afghanistan Gambia Niger
Albania Georgia Nigeria
Andorra Germany North Korea
Angola Ghana Norway
Antigua and Barbuda Greece Pakistan
Argentina Grenada Palestine
Armenia Guam Panama
Aruba Guatemala Papua New Guinea
Australia Guinea Paraguay
Austria Guyana Peru
Azerbaijan Haiti Philippines
Bahamas Honduras Poland
Bahrain Hungary Portugal
Bangladesh Iceland Puerto Rico
Barbados India Republic of the Congo
Belarus Indonesia Romania
Belgium Iran Russian Federation
Belize Ireland Rwanda
Benin Isle of Man Samoa
Bhutan Israel Senegal
Bolivia Italy Serbia
Bonaire Japan Seychelles
Bosnia and Herzegovina Jersey Sierra Leone
Botswana Jordan Singapore
Brazil Jordan Slovakia
Bulgaria Kazakhstan Slovenia
Burkina Faso Kenya Solomon Islands
Burundi Kiribati Somalia
Cambodia Kosovo South Africa
Cameroon Kyrgyzstan South Korea
Cape Verde Laos South Sudan
Central African Republic Latvia Spain
Chad Lebanon Sri Lanka
Chile Lesotho St Lucia
China Liberia Sudan
Columbia Liechtenstein Suriname
Comoros Lithuania Swaziland
Cook Islands Luxembourg Sweden
Costa Rica Macedonia Switzerland
Cote d'Ivoire Madagascar Tahiti
Croatia Malawi Taiwan
Cuba Malaysia Tajikistan
Curacao Maldives Tanzania
Cyprus Mali Thailand
Czech Republic Malta Togo
Democratic Republic of the Congo Mauritania Tonga
Denmark Mauritius Trinidad and Tobago
Djbouti Mexico Tunisia
Dominica Micronesia Turkmenistan
Dominican Republic Moldova Tuvalu
Ecuador Monaco Uganda
Egypt Mongolia Ukraine
El Salvador Montenegro United Arab Emirates
Equatorial Guinea Morocco United Kingdom
Eritrea Mozambique United States
Estonia Myanmar Uruguay
Ethiopia Namibia Vanuatu
Fiji Nepal Venezuela
Finland Netherlands Vietnam
France New Zealand Yemen
Gabon Nicaragua

Products codes

The Taxrates.io API’s provides product-level tax rates for a subset of product codes. These codes are to be used for products that are either exempt from tax in some jurisdictions or are taxed at reduced rates.

We will be expanding support for additional, less common categories over time. If you would like to request the addition of a new product category, please email us at support@taxrates.io

Please select a product code/s when making a request to the Taxrates.io API

Product code Product Description
C010 General Services/Products which are not subject to a service/product-specific tax
C011 Software - Downloaded
C012 Books - Downloaded
C011 Music - Downloaded
C011 Movies/Digital Video - Downloaded
C011 Other Electronic Goods - Downloaded
C011 Streaming Music/Audio Services new
C011 Streaming Video Services new
C018 Software as a Services, Generally (Remote Access to Hosted Software)
C018 Remote Access to Hosted Software - Personal Use
C018 Remote Access to Hosted Software - Business Use
C021 Remote Access to Hosted Business Custom Applications
C021 Personal Cloud Storage/Backup
C021 Business Cloud Storage/Backup
C021 Business Data Warehouses
C022 Infrastructure as Service, Generally
C022 Ecommerce Site/Webserver Hosting
C022 Provision of Virtual Computing Capacity
C022 Software - package or canned program
C022 Software - modifications to canned program
C022 Software - custom programs - material
C022 Software - custom programs - professional serv.
C022 Information services
C022 Data processing services
C022 Mainframe computer access and processing serv.
C022 Online Data processing services
C030 General Clothing (under $110)
C031 Clothing Protective
C032 Footwear
C033 Clothing Night Wear / Formal Wear / Swim Wear )
C034 Shoes (Men / Women / Children / Infant)
C035 Vitamins (Nutritional Supplements /Nutritional Mineral Supplements)
C036 Personal Care -( Products / Bath & Body / Hair Care Supplies / Skin Care Products / Foot Care)
C037 Personal Care (Eye Care)
C038 General Foods
C039 Foods (Health or Breakfast Bars)
C040 Medication (non-prescription) OTC
C041 Medication (prescription) OTC
C088 Shipping with Handling
C089 Shipping

Filtering

When calling the API endpoints you can use 'filter' parameters to get tax rate for the selected type. You can get the following tax types (Each tax rate will always have one of following types)

US Sales tax Rates

  1. CombinedRate
  2. StateRate
  3. CountyRate
  4. CityRate
  5. SPDRate
  6. MTARate

We recommend using Postman when discovering our API. Happy using!

Rate Limiting

We limit API requests.

If you’re exceeding this rate and encountering 429 errors, review the following:

  • Only make requests in states / regions where you have enabled.
  • Cache responses if the order details haven’t changed since the last calculation at checkout.

Errors

The Taxrates.io API uses the following error codes:

Code Error Message
400 Bad Request – Your request format is bad.
401 Unauthorized – Your API key is wrong.
404 Not Found – The specified resource could not be found.
405 Method Not Allowed – You tried to access a resource with an invalid method.
429 Too Many Requests – You’re requesting too many resources! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Try again later.

Verify your API token is correct and make sure you’re correctly setting the Authorization header.

If you’re still not sure what’s wrong, contact us and we’ll investigate.

Changelog

Stay on top of new developer-facing features, accuracy improvements, and bug fixes for our API. Have a request? Encounter an issue? We’d love to hear your feedback.

Authentication

Apikey

Taxrates uses API keys to allow access to the API. If you’re new to Taxrates.io, you’ll need to sign up for an account to get your API key. Otherwise, log in and go to API Access tab to generate a new API token.

Taxrates.io expects the API key to be included in all API requests to the server using a header like the following:

type
apiKey
name
Authorization
in
header

Testing via Postman

Authorization of the API

The following outlines to test each of the endpoints via Postman, if you have any questions please don’t hesitate to contact us support@taxrates.io

Steps

  1. Tab - "Authorization".
  2. Type - "API Key".
  3. Key - "Authorization".
  4. Value - "Apikey your_key".
  5. Add to - "Header".
See screenshot below: Authorization of the API

Tax rates by IP address

Steps to test on Postman

  1. Make sure you are on Params tab
  2. The Domain should be api.taxrates.io
  3. Input an IP address you can use the following:
    US (New York) 72.229.28.185
    Ireland 54.72.254.118
  4. For US sales tax you can add a filter for one of the following tax rates:
    1. CombinedRate
    2. StateRate
    3. CountyRate
    4. CityRate
    5. SpecialRate
  5. Input a product code, see the list “Product codes”
  6. Click “Send”
See the below screenshots: Authorization of the API

Authorization of the API

Tax rates by Country Code

  1. Make sure you are on Params tab
  2. The Domain should be api.taxrates.io
  3. Input a Country 2 digit ISO code
    1. Samples below - see the following link here for a full list
      1. IE = Ireland
      2. IN = India
      3. GB = United Kindgom
  4. For US sales tax you can filter for any of the following sales tax rates
    1. CombinedRate
    2. StateRate
    3. CountyRate
    4. CityRate
    5. SPDRate
    6. MTARate
  5. To get a tax rate for US sales tax you Need a zipcode, for testing use 10001 (New York) Make sure you have New York enabled on your dashboard
  6. Input a product code, see the list “Product codes”
  7. Click “Send”
See the below screenshot: Authorization of the API

Get All tax rates

Steps to Test on Postman

  1. Select a product code in your Taxrates.io dashboard
  2. Select the countries/ states that you want the Tax rates for in your Taxrates dashboard
    1. Note: for US sales tax the reponse will return all the Zipcode’s along the sales tax rates for each State. If all US states are selected than you are dealing with a lot of data (around 39,185 rows).
  3. Make sure you are on Params in Postman
  4. Domain should be api.taxrates.io
  5. You can filter the type of tax for any of the following types of sales tax rates, note: they are case sensitive
    • CombinedRate
    • StateRate
    • CountyRate
    • CityRate
    • SPDRate
    • MTARate
  6. Taxrates.io will only return 500 rates at a time,( It's a large amount of data so we will send more with one response) to leave the cursor empty for the first page and use value form “X-Cursor-Next” header for the next one. See below to get all the tax rates in the responses:
    1. Send the first request
    2. Check the tab with response headers
    3. If there is a X-Next-Cursor - use it for the "cursor" parameter to get the next page
    4. If there is no header/ X-Next-Cursor - this is the last page

Endpoints

All tax rates

GET /v3/tax/rates

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

We have development an easy to use scheduler so you can call the API to get the rates every hour or day. Please click on the following link to see the code on Github.

Please note in cases when a US state doesn't have sales tax and when a product is tax exempt for a zip code or for a state the API response will be "null"

To get a response you need to have selected a product code in your Taxrates.io dashboard, please see the Introduction section above for description of the different types of product codes.

For US sales tax you can filter the tax rate you want for each state or zip code with one of the following: (they are case sensitive)

  • CombinedRate
  • StateRate
  • CountyRate
  • CityRate
  • SPDRate
  • MTARate

var taxrates_endpoint = 'tax/rates';
var taxrates_params = {'domain':'api.taxrates.io'};
var taxrates_url = '/api/v3/';
if ( localStorage.getItem("Taxrates_API_Client_Secret") ){
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", "Apikey " + localStorage.getItem("Taxrates_API_Client_Secret"));
    },
    headers: {
      "accept": "application/json"
    },
    contentType: 'application/json; charset=utf-8',
    success: function (data, textStatus, jqXHR) {
      //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, function(k, v) {
              if(v.hasOwnProperty("rates")){
                  jQuery.each(v.rates, function(m, w) {
                      rates[i] = [];
                      //Only showing standard rate type
                      if( w.Type == "standard" ){
                          rates[i][0] = w.Type;
                          rates[i][1] = w.data_value;
                          rates[i][2] = w.product_code;
                          i++;
                      }
                  });
              }
          }).fail(function(xhr) {
                  //Maintain your errors here
                  return false;
          });
          var cursor = jqXHR.getResponseHeader('X-Cursor-Next');
          if (cursor) {
            // get next page...
          }
          return true;
}else{
  //Not logged into taxrates.io
  //Maintain your errors here
  return false;
}
domain: string
in query

Domain name: api.taxrates.io

filter: string
in query

You can filter your taxes by one of following types: 'standard', 'CombinedRate', 'CountyRate', 'CityRate', 'SPDRate' and 'MTARate'.

cursor: string
in query

Cursor shows from which record you want to get information. Default value is 0, next value can be retrieved from X-Cursor-Next header.

200 OK

An array of locations with tax rates

type
404 Not Found

No configured tax rates found. Have you added any country to your account?

default

Unexpected error

Response Example (200 OK)
[
  {
    "id": "integer",
    "name": "string",
    "state": "string",
    "zip": "string",
    "metadata": "object",
    "rates": [
      {
        "type": "string",
        "data_name": "string",
        "data_value": "string",
        "product_code": "string"
      }
    ]
  }
]
Response Example (default )
{
  "code": "integer (int32)",
  "message": "string",
  "fields": "string"
}

Tax rates by IP address

GET /v1/tax/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 retrieve the tax rates. You can use 'filter' parameter to narrow results to selected type of tax

For US sales tax you can filter the tax rate you want for each state or zip code with one of the following: (they are case sensitive)

  • CombinedRate
  • StateRate
  • CountyRate
  • CityRate
  • SPDRate
  • MTARate
var taxrates_endpoint = 'tax/ip';
var taxrates_params = {'domain':'api.taxrates.io', 'ip':'208.80.152.201', 'product_code':'C010'};
var taxrates_url = '/api/v1/';
if ( localStorage.getItem("Taxrates_API_Client_Secret") ){
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", "Apikey " + localStorage.getItem("Taxrates_API_Client_Secret"));
    },
    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, 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;
}
domain: string
in query

Domain name: api.taxrates.io

ip: string
in query

Customer's IP address

filter: string
in query

You can filter your taxes by one of following types: 'standard', 'CombinedRate', 'CountyRate', 'CityRate', 'SPDRate' and 'MTARate'.

product_codes: string[]
in query

You can filter your taxes by product codes.

200 OK

An array of tax rates for VAT, GST & TAX

type
404 Not Found

Geolocation can not be processed/No matching country found

default

Unexpected error

Response Example (200 OK)
[
  {
    "country_name": "string",
    "taxes": [
      {
        "Country": "string",
        "Type": "string",
        "ProductCode": "string",
        "data_name": "string",
        "data_value": "string",
        "metadata": "object"
      }
    ]
  }
]
Response Example (default )
{
  "code": "integer (int32)",
  "message": "string",
  "fields": "string"
}

Tax rates by Country Code

GET /v1/tax/countrycode

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 (see here for more information). You can use 'filter' parameter to narrow results to selected type of tax

For US sales tax you can filter the tax rate you want for each state or zip code with one of the following: (they are case sensitive)

  • CombinedRate
  • StateRate
  • CountyRate
  • CityRate
  • SPDRate
  • MTARate
var taxrates_endpoint = 'tax/countrycode';
var taxrates_params = {'domain':'api.taxrates.io', 'country_code':'IE', 'product_code':'C010'};
var taxrates_url = '/api/v1/';
if ( localStorage.getItem("Taxrates_API_Client_Secret") ){
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", "Apikey " + localStorage.getItem("Taxrates_API_Client_Secret"));
    },
    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, 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;
}
domain: string
in query

Domain name: api.taxrates.io

country_code: string
in query

Country code alpha 2

filter: string
in query

You can filter your taxes by one of following types: 'standard', 'CombinedRate', 'CountyRate', 'CityRate', 'SPDRate' and 'MTARate'.

zip: string
in query

You must provide a zip code if one of your selected countries is United States and you've had selected a state on your Taxrates.io member's dashboard.

province: string
in query

You must provide a province if one of your selected countries is Canada and you've had selected a province on your Taxrates.io member's dashboard.

product_codes: string[]
in query

You can filter your taxes by product codes.

200 OK

Success

404 Not Found

Country not found. Have you provided correct alpha-2 country code?

500 Internal Server Error

Unexpected error

Response Example (200 OK)
{
  "country_name": "string",
  "taxes": [
    {
      "Country": "string",
      "Type": "string",
      "ProductCode": "string",
      "data_name": "string",
      "data_value": "string",
      "metadata": "object"
    }
  ]
}
Response Example (500 Internal Server Error)
{
  "code": "integer (int32)",
  "message": "string",
  "fields": "string"
}

Schema Definitions

Rates: object

country_name: string

The country name

taxes: Tax
Tax
Example
{
  "country_name": "string",
  "taxes": [
    {
      "Country": "string",
      "Type": "string",
      "ProductCode": "string",
      "data_name": "string",
      "data_value": "string",
      "metadata": "object"
    }
  ]
}

Tax: object

Country: string

The country name

Type: string

The tax type

ProductCode: string

The product code

data_name: string

The tax name and description (VAT, GST, PIT, CIT etc)

data_value: string

The tax value in percents

metadata: object

Map, values are strings and possible keys are City, CityNumber, County, CountyNumber, SPD, SPDNumber, MTA, MTANumber, Zip

Example
{
  "Country": "string",
  "Type": "string",
  "ProductCode": "string",
  "data_name": "string",
  "data_value": "string",
  "metadata": "object"
}

Error: object

code: integer (int32)
message: string
fields: string
Example
{
  "code": "integer (int32)",
  "message": "string",
  "fields": "string"
}

TaxRate: object

type: string

The tax type

data_name: string

The tax name and description (VAT, GST, PIT, CIT etc)

data_value: string

The tax value in percents

product_code: string

Product code

Example
{
  "type": "string",
  "data_name": "string",
  "data_value": "string",
  "product_code": "string"
}

Location: object

id: integer
name: string

Country name

state: string

State/province name if exists

zip: string

Zipcode

metadata: object

Map, values are strings and possible keys are city, city_number, county, county_number, spd, spd_number, mta, mta_number

rates: TaxRate
TaxRate
Example
{
  "id": "integer",
  "name": "string",
  "state": "string",
  "zip": "string",
  "metadata": "object",
  "rates": [
    {
      "type": "string",
      "data_name": "string",
      "data_value": "string",
      "product_code": "string"
    }
  ]
}