Docs

Getting started

You can work with eClear immediately or spend a bit longer to understand the usual flow.

VAT classification in 30 seconds

First authenticate by retrieving a valid token:

Getting an access token
POST https://eclear-solutions.com/api/auth/v1/login HTTP/1.1
Content-Type: application/json

{
  "username": "{{username}}",
  "password": "{{password}}"
}

Say, you have a product with id productXYZA and you want to get its VAT Rate for an address with zip code 28046 in Spain. Your shopId is 44001331. You would request:

Retrieving a VAT rate for a product that has not been classified
GET https://eclear-solutions.com/api/vat-classification/v1/vat-rates?country=ES&zipCode=28046&productId=productXYZA&shopId=44001331 HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{access_token}}

The response body is:

A fallback VAT rate
{
  "rateType": "STANDARD",
  "vatRate": 21.0,
  "productId": "productXYZB",
  "source": "FALLBACK"
}

The property source and the value FALLBACK indicate that rather than return a VAT rate from eClear's taxonomy the standard rate for Spain, a fallback, is returned. This response is not a surprise because your product has not been classified into eClear's taxonomy. If you want to learn how to classify your product read on.

VAT classification in under 5 Minutes

First authenticate by retrieving a valid token:

Getting an access token
POST https://eclear-solutions.com/api/auth/v1/login HTTP/1.1
Content-Type: application/json

{
  "username": "{{username}}",
  "password": "{{password}}"
}

Now upload two products with productIds productXYZA and productXYZB:

Uploading products
POST https://eclear-solutions.com/api/vat-classification/v1/products/global HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{access_token}}

{
  "productXYZA":
    {
      "productDetails": {
        "languageAttributes":
        {
          "en": {
            "productName": "Desk Lamp",
            "productDescription": "A lamp made of wood. Optimal for long working hours ...",          
            "productTags": ["Furniture" , "Office", "Lamp"]
          }
        },
        "customs": {
          "taricCode": "9405214000"
        }        
      },
      "shopIds": [44001331] 
     },
  "productXYZB":
    {
      "productDetails": {
        "languageAttributes":
        {
          "en": {
            "productName": "Nice coffee mug",
            "productDescription": "This coffee mug is also suited for tea ...",          
            "productTags": ["Tableware" , "Mugs"]
          }
        },
        "customs": {
          "taricCode": "6912002310"
        }
      },
   "shopIds": [44001331] 
   }
}

eClear will now attempt to auto-assign these products to a productClass in its taxonomy.

Check the assignment status for your products:

Get the assignment status
GET https://eclear-solutions.com/api/vat-classification/v1/assignments/TARIC?productIds=productXYZA,productXYZB&assignmentStatus=ASSIGNED,UNASSIGNED,APPROVED,REJECTED,DENIED HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{access_token}}

We see that the auto-assignment was able to find a productClass with the DESCRIPTION strategy (i.e. based on textual product attributes such as the title and description). The status of the assignment is ASSIGNED. This status indicates that the productClass allows us to retrieve VAT rates for all European countries and Northern Ireland. Before we can query VAT rates we have to confirm that the productClass that was derived automatically is correct - in other words we have to approve the assignment:

Approving the assignment
PATCH https://eclear-solutions.com/api/vat-classification/v1/assignments/TARIC?assignmentAction=APPROVE&applications=VAT-RULES HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{access_token}}

{
  "products": [{      
        "assignmentVersion": {
          "vatRules": 5},
        "productId": "productXYZB",
        "shopIds": [44001331]
      },
      {      
        "assignmentVersion": {
          "vatRules": 4},
        "productId": "productXYZA",
        "shopIds": [44001331]
      }]
}

Now retrieve the VAT rate for product productXYZA for an address with zip code 28046 in Spain:

Retrieving a VAT rate for a product that has been classified
GET https://eclear-solutions.com/api/vat-classification/v1/vat-rates?country=ES&zipCode=28046&productId=productXYZA&shopId=44001331 HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{access_token}}

The response body is:

A taxonomy VAT rate
{
  "rateType": "STANDARD",
  "vatRate": 21.0,
  "productId": "productXYZA",
  "source": "TAXONOMY"
}

The VAT rate is 21% and it is derived from eClear's taxonomy as indicated by the source property.

What is next:

VAT classification

Previous Page

Local and global Products

Next Page

On this page

VAT classification in 30 secondsVAT classification in under 5 Minutes