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
Method
The request type: POST
The Post method lets you request VAT 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"
}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 |
| sales_tax_rate | 8 | Sales tax rate |
| vat_rate | 20 | Vat 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
{
"transaction_type": "b2c_distance_sales",
"taxable_jurisdiction": "USA",
"taxable_state": "NY",
"sales_tax_rate": 8.25
}
{
"transaction_type": "export/import",
"taxable_jurisdiction": "GBR",
"vat_rate": 0,
"export_country": "GBR",
"import_country": "ITA"
}
{
"transaction_type": "reverse_charge",
"taxable_jurisdiction": "FRA",
"vat_rate": 0
}Countries
We support the following countries around the world:
US, EU countries, UK, Russia, Ukraine, Belarus, Norvey, Canada, Australia, Japan, Switzerland.
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 |
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.