Merchant Tax Rate API

The following documentation covers the information on elements of the Tax rate API, including requests, responses, and error codes.

To integrate Tax rate API:

Register a Lovat OMP Account.
Fill a company profile.
Choose a plan.
Set up Webhooks.
Get a token.
Set tax rules.

Terms and Abbreviation

Merchant – the owner of an online store.
Buyer – an individual or a company who pays for goods or services.
Transaction – order or transfer of funds for goods or services received by a merchant from a customer.
Token – a secret string used by the system to identify the merchant and the web-site through which the transaction is registered.

API Reference

Lovat API uses the REST architecture. The API has predictable, resource-oriented URLs and uses HTTP response codes to indicate API errors. The API always responds in the JSON format, including cases of errors.

Authentication

Authentication to the Tax rate API is performed via HTTP header basic authentication. Subscribers need to provide a token as the basic authentication value. If you’re new to Lovat, you’ll need to sign up for an account to get your API key. The API uses built-in HTTP features such as HTTP authentication and HTTP verbs, which can be interpreted by off-the-shelf HTTP clients. It also supports cross-origin resource sharing, allowing you to access it securely from a client web application.

URL

Lovat API uses the following endpoint paths:

Production Region

https://merchant.vatcompliance.co/api/1/tax_rate/ – Tax rate API

Test Region

sandbox.vatcompliance.co/api/1/tax_rate

POST

Method

The request type: POST

https://merchant.vatcompliance.co/api/1/tax_rate/{access_token}

The Post method lets you request tax rate for transaction taking into account parameters of the transaction.

JSON Params

Parameter	Type	Description	Required
transaction_id	String	Maximum 255 characters	Optional
currency	–	Transaction currency. Three-letter currency code per ISO 4217	Optional
if_digital	Bol	Required for digital services	Optional
transaction_sum	Float	Total amount of the order, excluding shipping	Optional
delivery_fee	Float	Total amount of shipping for the order	Optional
arrival_country	String	A country where the order shipped to. Three-letter uppercase country code per ISO 3166-1 alpha-3	Required
arrival_zip	String	Required for US orders: Postal code where the order shipped to	Required for US orders
arrival_state	–	For US, Canada, UK: Two-letter ISO state code where the order shipped to	Optional
departure_country	String	Three-letter ISO country code of the country where the order shipped from. All countries are specified as strings according to ISO 3166- 1 alpha- 3	Required
departure_zip	String	For US orders: Postal code where the order shipped from	Optional
departure_state	String	For US, Canada: Two-letter ISO state code where the order shipped from	Optional
service_code	String	Required for digitally supplied services. Tax categories of digital services	Optional
good_code	String	Code of a good according to EU’s eight-digit coding system The Combined Nomenclature (CN)	Optional
vat_number_of_buyer	String	Tax number of buyer	Optional
buyer_ip	String	IP address of buyer. Required for digital services	Required for digital services
exemption_type	String	For US orders only	Optional
phone_number_of_buyer	String	Optional for digital services. At least 5 first digits consists country code	Optional
bank_country_of_buyer	String	Optional for digital services. Three – letter uppercase country code per ISO 3166-1 alpha-3	Optional

Errors List

List of supported HTTP errors:

200, 201, 204
No errors

400 Bad Request
This often indicates a required parameter missing. Refer to the response body for details

401 Unauthorized
No valid API key provided

402 Request Failed
Request failed despite valid parameters

403 Forbidden
No permission. Refer to the response body for details

404 Not Found
The requested item doesn’t exist

409, 422
Invalid request parameters

412 Precondition Failed
The project has not been activated yet (used in the Get Token method)

415 Unsupported Media Type
Content-Type: application/json’ missing in HTTP header

500, 502, 503, 504 Server Errors
Something went wrong

Example Query Request

Sample request from the console

Command Line

curl-v GET https://merchant.vatcompliance.net/api/1/VAT_rate/get/5aae918d97964ff88df64b059c2cc0f8

--header "Content-Type: application/json" \

-d '{

   "arrival_country": "ITA",

"departure_country": "GBR",

"transaction_id": "7668999765",

"transaction_sum": 10,

"vat_number_of_buyer": "IT8996543"

}'

{

"arrival_country": "GBP",

"currency": "EUR",

"delivery_fee": 0,

"departure_country": "HUN",

"vat_number_of_buyer": "IT8996543",

"transaction_datetime": "2021-01-09",

"transaction_id": "45000098"

}

{

"arrival_country": "USA",

"arrival_state": "NY",

"arrival_zip": "10034",

"departure_country": "USA",

"departure_state": "TX",

"departure_zip": "77554",

"transaction_datetime": "2021-01-01",

"transaction_id": "788654333"

}

Command line

require 'net/http'
require 'json'

api_url = 'https://merchant.vatcompliance.net/api/1/VAT_rate/get/5aae918d97964ff88df64b059c2cc0f8'
headers = { 'Content-Type' => 'application/json' }

requests_list = [
  {
    "arrival_country" => "ITA",
    "departure_country" => "GBR",
    "transaction_id" => "7668999765",
    "transaction_sum" => 10,
    "vat_number_of_buyer" => "IT8996543"
  },
  {
    "arrival_country" => "GBP",
    "currency" => "EUR",
    "delivery_fee" => 0,
    "departure_country" => "HUN",
    "vat_number_of_buyer" => "IT8996543",
    "transaction_datetime" => "2021-01-09",
    "transaction_id" => "45000098"
  },
  {
    "arrival_country" => "USA",
    "arrival_state" => "NY",
    "arrival_zip" => "10034",
    "departure_country" => "USA",
    "departure_state" => "TX",
    "departure_zip" => "77554",
    "transaction_datetime" => "2021-01-01",
    "transaction_id" => "788654333"
  }
]

requests_list.each do |data|
  uri = URI(api_url)
  uri.query = URI.encode_www_form(data)

  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Get.new(uri)
  request['Content-Type'] = 'application/json'

  response = http.request(request)

  if response.code.to_i == 200
    puts response.body
  else
    puts "Error: #{response.code} - #{response.message}"
  end
end

Command line

import requests

api_url = 'https://merchant.vatcompliance.net/api/1/VAT_rate/get/5aae918d97964ff88df64b059c2cc0f8'
headers = {'Content-Type': 'application/json'}

requests_list = [
    {
        "arrival_country": "ITA",
        "departure_country": "GBR",
        "transaction_id": "7668999765",
        "transaction_sum": 10,
        "vat_number_of_buyer": "IT8996543"
    },
    {
        "arrival_country": "GBP",
        "currency": "EUR",
        "delivery_fee": 0,
        "departure_country": "HUN",
        "vat_number_of_buyer": "IT8996543",
        "transaction_datetime": "2021-01-09",
        "transaction_id": "45000098"
    },
    {
        "arrival_country": "USA",
        "arrival_state": "NY",
        "arrival_zip": "10034",
        "departure_country": "USA",
        "departure_state": "TX",
        "departure_zip": "77554",
        "transaction_datetime": "2021-01-01",
        "transaction_id": "788654333"
    }
]

for data in requests_list:
    response = requests.get(api_url, headers=headers, params=data)
    if response.status_code == 200:
        print(response.json())
    else:
        print(f'Error: {response.status_code}')

Command line

$apiUrl = 'https://merchant.vatcompliance.net/api/1/VAT_rate/get/5aae918d97964ff88df64b059c2cc0f8';
$headers = ['Content-Type: application/json'];

$requests = [
	[
		"arrival_country" => "ITA",
		"departure_country" => "GBR",
		"transaction_id" => "7668999765",
		"transaction_sum" => 10,
		"vat_number_of_buyer" => "IT8996543"
	],
	[
		"arrival_country" => "GBP",
		"currency" => "EUR",
		"delivery_fee" => 0,
		"departure_country" => "HUN",
		"vat_number_of_buyer" => "IT8996543",
		"transaction_datetime" => "2021-01-09",
		"transaction_id" => "45000098"
	],
	[
		"arrival_country" => "USA",
		"arrival_state" => "NY",
		"arrival_zip" => "10034",
		"departure_country" => "USA",
		"departure_state" => "TX",
		"departure_zip" => "77554",
		"transaction_datetime" => "2021-01-01",
		"transaction_id" => "788654333"
	]
];

foreach ($requests as $data) {
	$ch = curl_init($apiUrl);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
	curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
	curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
	curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

	$response = curl_exec($ch);

	if (curl_errno($ch)) {
		echo 'Error:' . curl_error($ch);
	}

	curl_close($ch);

	echo $response . PHP_EOL;
}

Command line

const axios = require('axios');

const apiUrl = 'https://merchant.vatcompliance.net/api/1/VAT_rate/get/5aae918d97964ff88df64b059c2cc0f8';
const headers = { 'Content-Type': 'application/json' };

const requests = [
  {
    "arrival_country": "ITA",
    "departure_country": "GBR",
    "transaction_id": "7668999765",
    "transaction_sum": 10,
    "vat_number_of_buyer": "IT8996543"
  },
  {
    "arrival_country": "GBP",
    "currency": "EUR",
    "delivery_fee": 0,
    "departure_country": "HUN",
    "vat_number_of_buyer": "IT8996543",
    "transaction_datetime": "2021-01-09",
    "transaction_id": "45000098"
  },
  {
    "arrival_country": "USA",
    "arrival_state": "NY",
    "arrival_zip": "10034",
    "departure_country": "USA",
    "departure_state": "TX",
    "departure_zip": "77554",
    "transaction_datetime": "2021-01-01",
    "transaction_id": "788654333"
  }
];

requests.forEach(async (data) => {
  try {
    const response = await axios.get(apiUrl, {
      headers: headers,
      params: data
    });

    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.message);
  }
});

Command line

using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var apiUrl = "https://merchant.vatcompliance.net/api/1/VAT_rate/get/5aae918d97964ff88df64b059c2cc0f8";
        var headers = "application/json";

        var requests = new[]
        {
            new
            {
                arrival_country = "ITA",
                departure_country = "GBR",
                transaction_id = "7668999765",
                transaction_sum = 10,
                vat_number_of_buyer = "IT8996543"
            },
            new
            {
                arrival_country = "GBP",
                currency = "EUR",
                delivery_fee = 0,
                departure_country = "HUN",
                vat_number_of_buyer = "IT8996543",
                transaction_datetime = "2021-01-09",
                transaction_id = "45000098"
            },
            new
            {
                arrival_country = "USA",
                arrival_state = "NY",
                arrival_zip = "10034",
                departure_country = "USA",
                departure_state = "TX",
                departure_zip = "77554",
                transaction_datetime = "2021-01-01",
                transaction_id = "788654333"
            }
        };

        using (var httpClient = new HttpClient())
        {
            foreach (var data in requests)
            {
                var content = new StringContent(Newtonsoft.Json.JsonConvert.SerializeObject(data),
                    System.Text.Encoding.UTF8, headers);

                try
                {
                    var response = await httpClient.GetAsync(apiUrl + "?" + await content.ReadAsStringAsync());

                    if (response.IsSuccessStatusCode)
                    {
                        var responseBody = await response.Content.ReadAsStringAsync();
                        Console.WriteLine(responseBody);
                    }
                    else
                    {
                        Console.WriteLine($"Error: {response.StatusCode} - {response.ReasonPhrase}");
                    }
                }
                catch (HttpRequestException ex)
                {
                    Console.WriteLine($"Error: {ex.Message}");
                }
            }
        }
    }
}

Command line

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.List;

public class Main {
    public static void main(String[] args) {
        String apiUrl = "https://merchant.vatcompliance.net/api/1/VAT_rate/get/5aae918d97964ff88df64b059c2cc0f8";
        String headers = "Content-Type: application/json";

        List requests = new ArrayList<>();
        requests.add("{\"arrival_country\":\"ITA\",\"departure_country\":\"GBR\",\"transaction_id\":\"7668999765\",\"transaction_sum\":10,\"vat_number_of_buyer\":\"IT8996543\"}");
        requests.add("{\"arrival_country\":\"GBP\",\"currency\":\"EUR\",\"delivery_fee\":0,\"departure_country\":\"HUN\",\"vat_number_of_buyer\":\"IT8996543\",\"transaction_datetime\":\"2021-01-09\",\"transaction_id\":\"45000098\"}");
        requests.add("{\"arrival_country\":\"USA\",\"arrival_state\":\"NY\",\"arrival_zip\":\"10034\",\"departure_country\":\"USA\",\"departure_state\":\"TX\",\"departure_zip\":\"77554\",\"transaction_datetime\":\"2021-01-01\",\"transaction_id\":\"788654333\"}");

        for (String data : requests) {
            try {
                URL url = new URL(apiUrl + "?" + data);
                HttpURLConnection conn = (HttpURLConnection) url.openConnection();
                conn.setRequestMethod("GET");
                conn.setRequestProperty("Content-Type", headers);

                if (conn.getResponseCode() == HttpURLConnection.HTTP_OK) {
                    BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream(), StandardCharsets.UTF_8));
                    String line;
                    StringBuilder response = new StringBuilder();

                    while ((line = in.readLine()) != null) {
                        response.append(line);
                    }

                    in.close();
                    System.out.println(response.toString());
                } else {
                    System.out.println("Error: " + conn.getResponseCode() + " - " + conn.getResponseMessage());
                }

                conn.disconnect();
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
    }
}

Command line

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	apiURL := "https://merchant.vatcompliance.net/api/1/VAT_rate/get/5aae918d97964ff88df64b059c2cc0f8"
	headers := "application/json"

	requests := []map[string]interface{}{
		{
			"arrival_country":     "ITA",
			"departure_country":   "GBR",
			"transaction_id":      "7668999765",
			"transaction_sum":     10,
			"vat_number_of_buyer": "IT8996543",
		},
		{
			"arrival_country":       "GBP",
			"currency":              "EUR",
			"delivery_fee":          0,
			"departure_country":     "HUN",
			"vat_number_of_buyer":   "IT8996543",
			"transaction_datetime":  "2021-01-09",
			"transaction_id":        "45000098",
		},
		{
			"arrival_country":       "USA",
			"arrival_state":         "NY",
			"arrival_zip":           "10034",
			"departure_country":     "USA",
			"departure_state":       "TX",
			"departure_zip":         "77554",
			"transaction_datetime":  "2021-01-01",
			"transaction_id":        "788654333",
		},
	}

	for _, data := range requests {
		jsonData, err := json.Marshal(data)
		if err != nil {
			fmt.Println("Error:", err)
			return
		}

		req, err := http.NewRequest("GET", apiURL, bytes.NewBuffer(jsonData))
		if err != nil {
			fmt.Println("Error:", err)
			return
		}

		req.Header.Set("Content-Type", headers)

		client := &http.Client{}
		resp, err := client.Do(req)
		if err != nil {
			fmt.Println("Error:", err)
			return
		}
		defer resp.Body.Close()

		var result bytes.Buffer
		_, err = result.ReadFrom(resp.Body)
		if err != nil {
			fmt.Println("Error:", err)
			return
		}

		fmt.Println(result.String())
	}
}

Response elements

Parameter	Type/ Example	Example Description
transaction_type	“export/import”,”b2c_distance_sales”, “reverse_charge”	–
taxable_jurisdiction	“ITA”, “GBR”	Three-letter ISO country code of the country where the order is taxable. All countries are specified as strings according to ISO 3166- 1 alpha-3
taxable_state	“NY”	For US, Canada, UK: Two-letter ISO state code where the order is taxable
tax_rate	8	Tax rate
export_country	“USA”, “GBR”	Export country for orders with transaction type export/import
import_country	“USA”, “GBR”	Import country for orders with transaction type export/import

Example response

cURL

Command Line

{

"transaction_type": "b2c_distance_sales",

"taxable_jurisdiction": "USA",

"taxable_state": "NY",

"tax_rate": 8.25

}

{

  "transaction_type": "export/import",

  "taxable_jurisdiction": "GBR",

  "tax_rate": 0,

  "export_country": "GBR",

  "import_country": "ITA"

}

{

  "transaction_type": "reverse_charge",

  "taxable_jurisdiction": "FRA",

  "tax_rate": 0

}

Countries

Lovat API is available in more than 100 countries. We support the following countries around the world: US, EU countries, UK, Norway, Canada, Australia, Japan, and Switzerland. You can find the complete list of supported countries on our website.

Tax categories of digital services

audio/visual content	1
live streaming	2
telephone services	3
internet telephone services	4
call management services	5
paging services	6
internet access	7
images	8
music	9
games	10
e-newspapers	11
web hosting	12
distance maintenance of programmes	13
advertising space on a website	14
e-books	15
licenses	16
dating	17
distance education	18
gambling	19
Saas	20

Call Limiting

We limit API requests to 100 per minute for merchant plans. You may have more calls than your monthly plan limit. Overage fees are charged separately if you exceed your plan limit during a next month.

Exemption types

For US orders only types of exemption: wholesale, government, marketplace, other, non_exempt, or nill.