T

Tax Rate API

Instruction for technical integration with the tax rate API by LOVAT

Introduction

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

To integrate OMP tax rate API:

  1. Register a Lovat OMP Account.
  2. Fill a company profile.
  3. Choose a plan.
  4. Set up Webhooks.
  5. Get a token.
  6. Set tax rules.

Terms and Abbreviations

API – application Programming Interface. A set of calls provided by the system calls for integration with external software products.

Merchant – the owner of an online store.

Customer – an individual who pays for goods or services.

Transaction – transfer of funds for goods or services received by the customer from the merchant.

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

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

JSON Params

Parameter Type Description Required
transaction_id String Maximum 255 characters. optional
сurrency

 

String

 

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 shopping order 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 to the US orders
arrival_state String For US, Canada, the 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 optional

 

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 error

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:

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 Description
transaction_type “export/import”, “b2c_distance_sales”, “reverse_charge”
transaction_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 USA, Canada, the 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
}

Date Format

All dates are specified as strings according to ISO 8601. You can specify date strings either in UTC (e.g., 2013-01-15T00:00:00Z), or indicating the UTC offset (e.g., 2013-01-15T00:00:00-08:00 for eight hours behind UTC). In the latter case, make sure to take into account the daylight saving time, if applicable.

Countries

We support the following countries around the world: US, EU countries, UK, Russia, Ukraine, Belarus, Norway, Canada, Australia, Japan.

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 1,000 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.