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:

    1. Register a Lovat 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

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:

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

Method

The request type: POST

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

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 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 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

}

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, 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

Close Bitnami banner
Bitnami