Auto-assignment

Whenever a product is created it is attempted to find a product class code automatically (auto-assignment). Different auto-assignment strategies are available to find a product class code:

By default, first the CUSTOMS-CODE strategy is used and if that cannot return a code the DESCRIPTION strategy is used. On top of these assignment strategies you can write customer specific assignment rules and use them in auto-assignment.

Configuring auto-assignment

You can configure what auto-assignment strategies are used, including none at all, and how the product class code should be selected among competing strategies.

The following request sets the compliance parameter of the description strategy to 65%:

PUT https://eclear-solutions.com/api/vat-classification/v1/assignments/auto-assignment/minimum-compliance?newValue=65 HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{access_token}}

You can also configure the priority order of the auto-assignment strategies:

PUT https://eclear-solutions.com/api/vat-classification/v1/assignments/auto-assignment HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{access_token}}

{
  "autoAssignmentConfigurations": {
    "strategyPriorityOrder": ["DESCRIPTION", "NEAREST-CUSTOMS-CODE", "CUSTOMS-CODE"],
    "stoppingRule": "ON-SUCCESS-RETURN"
  }
}

This request changes auto-assignment to first try the "DESCRIPTION" strategy, then the "NEAREST-CUSTOMS-CODE" strategy and finally the "CUSTOMS-CODE" strategy. As you can see in this request, you can also configure the stoppingRule. There are two stopping rules to choose from:

1. ON-SUCCESS-RETURN: Auto-assignment stops if the first auto-assignment strategy in strategyPriorityOrder found a product class code. The found product class code is used in assignment.
2. MAXIMUM-LENGTH: Auto-assignment uses the longest product class code found by the assignment strategies in strategyPriorityOrder. If there is more than one longest code the ordering in the array strategyPriorityOrderis used to break the tie.

Customer specific assignment rules

You have the possibility to craft your own assignment rules and use them in auto-assignment. A so called customer specific assignment rule consists of a filter and a product class code for a taxonomy. A filter is an expression on product attributes in a specific language. The following table gives an overview of how to express product attributes in the language:

As is evident from the table, the naming of the product attributes follow the naming of the request body in the POST request. It is important to point out that the customs codes listed in the table are the customs codes that the user provided on product creation or update, not the ones that are part of the assignment.

Product attributes can be combined with following logical operators:

As is the case in the last example of the table you can use brackets to express precedence. You can use the following operators to compare numeric values:

You can also use the %in% operator to test the existence of a value in an array. For example, merchant.alcohol %in% (3,4,5) returns products that have a merchant product attribute alcohol that has values 3, 4 or 5.

There are also arithmetic operators:

Finally, the language supports three functions:

Crafting a customer specific assignment rule

With the syntax explained, we can now craft a customer specific assignment rule. First we have to define a filter. The following defines a filter that returns products whose product name (in German) contains the word "drink" or "Drink" and whose merchant product attribute alcohol_content_percent is less than 0.05.

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

{
    "name": "alcohol-free-drink",
    "query": "(contains(eclear.productName[de], \"drink\") | contains(eclear.productName[de], \"Drink\")) & merchant.alcohol_content_percent < 0.05",
    "description": "Filters a drink containing no alcohol"
}

Confirm that the filter has been created by reading all filters:

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

The filter has been created and has the id 94eed2e4-2abd-44ac-abda-da2e2ea73e7f in this example. We can apply the filter to check whether it returns any result:

POST https://eclear-solutions.com/api/vat-classification/v1/products/filters/94eed2e4-2abd-44ac-abda-da2e2ea73e7f HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{access_token}}

Now we can associate the filter with a product class code. The following request associates the filter with product class code 2106909285 on the TARIC and thereby creates the customer specific assignment rule:

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

{
    "name": "DRINK-NO-ALCOHOL",
    "description": "Assign drink without alcohol to 2106909285",
    "code": {
      "taric": "2106909285"
    },
    "filterId": "94eed2e4-2abd-44ac-abda-da2e2ea73e7f"
}

We can then use the rule in auto-assignment. We simply reference it by the name that we have provided on rule creation. The following request configures auto-assignment in such a way that it first tries the customer specific assignment rule "DRINK-NO-ALCOHOL" and if this rule is unsuccessful the "DESCRIPTION" strategy.

PUT https://eclear-solutions.com/api/vat-classification/v1/assignments/auto-assignment HTTP/1.1
Authorization: Bearer {{access_token}}
Content-Type: application/json

{
  "autoAssignmentConfigurations": {
  "strategyPriorityOrder": ["DRINK-NO-ALCOHOL", "DESCRIPTION"],
  "stoppingRule": "ON-SUCCESS-RETURN"
  }
}