Retrieving VAT rates

VAT rates can be retrieved either in batches of countries and products or for a single location and product. The following request queries for a vat rate for a location in Germany for a product with id a-product-id.:

GET https://eclear-solutions.com/api/vat-classification/v1/vat-rates?productId=a-product-id&shopId=44001331&country=DE&zipCode=65232 HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{access_token}}

The response indicates in the source property that the VAT rate was retrieved from eClear's taxonomy. That is because the assignment for product with id a-product-id is APPROVED. By default eClear always returns a TAXONOMY rate for products that have APPROVED assignments. If instead we send a request for a product that has a status other than APPROVED or a product that does not exist eClear returns the standard rate for this country as a fallback. This behaviour is indicated by source=FALLBACK in the response to:

GET https://eclear-solutions.com/api/vat-classification/v1/vat-rates?productId=id-does-not-exist&shopId=44001331&country=DE&zipCode=65232 HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{access_token}}

In the above request, the product with id id-does-not-exist has not been created. Querying for a VAT rate in a single location and for a single product has the advantage that VAT exemption regions are taken into account. An exception region is located in the countries that eClear supports and either has no VAT regime or a VAT regime that is different from the mainland. For example, the isle of Helgoland in Germany has no VAT regime. Its zipCode is 27498. The response to the below query thus returns a 404 status code:

GET https://eclear-solutions.com/api/vat-classification/v1/vat-rates?productId=a-product-id&shopId=44001331&country=DE&zipCode=27498 HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{access_token}}

Currently eClear supports four regions in Europe that have a different VAT regime from the mainland:

1. Azores (Portugal)
2. Madeira (Portugal)
3. Corsica (France)
4. Northern Ireland (UK)

If you query vat rates for these regions then you will receive VAT rates. For all other exemption regions you will receive a 404 status code.

Batch requests

You can also query VAT rates for batches of products and countries. In contrast to single region and product requests, the batch endpoint returns VAT rates for the mainland only. The below request asks for VAT rates in Italy and Germany for products with id a-product-id or id-does-not-exist.

GET https://eclear-solutions.com/api/vat-classification/v1/vat-rates-batch?shopId=44001331&countries=DE&countries=IT&productIds=a-product-id&productIds=id-does-not-exist
Content-Type: application/json
Authorization: Bearer {{access_token}}

The response is similar to the single country and product request but here an array is returned instead of a single JSON object. You can send up to 50 products in one request. Note that the shopId parameter is mandatory and that instead of passing a comma separated string of productIds you can also repeat the productId argument (e.g. productId=A&productId=B in place of productId=A,B)

Configuring VAT rate requests

By default only products with APPROVED assignments return a vat rate from eClear's taxonomy. You can configure what assignment status may be used in VAT rate requests. In status of assignments we explained that assignments that have the status ASSIGNED or APPROVED contain all the information to find vat rates for eClear's supported countries. Assignments with status REJECTED have a product class code but this product class code does not suffice to find vat rates for all supported countries although it might suffice to return vat rates for some countries. In the following request you can instruct eClear to consider the assignment status for vat rate requests that you pass:

PUT https://eclear-solutions.com/api/vat-classification/v1/vat-rates/qualifying-status?newValue=ASSIGNED,APPROVED,REJECTED
Content-Type: application/json
Authorization: Bearer {{access_token}}

In the request, we pass the status ASSIGNED, APPROVED, REJECTED. This configuration is the most liberal setup as you can receive VAT rates from eClear's taxonomy for assignments that have not had human review. It also implies that you receive a VAT rate from the taxonomy with minimal assignment effort. So, if you want to operate eClear without human review nor assignment effort you should choose the above configuration. The drawback is that sometimes the product class found by auto-assignment could be wrong or insufficient to find VAT rates for all supported countries.