Assignment

In order to retrieve VAT rates for your products from eClear's product taxonomy they need to be associated with a product class. A product class contains like products in terms of VAT and customs. We call the association between a product and a product class an assignment. Assignments have a status that signals the extent to which a correct product class has been found and whether it has had human review. When you create a product it is attempted to automatically assign it to a product class (auto-assignment).

Status of assignments

Assignments can have the following status:

Assignment lifecycle

Assignment process

When you create a product it is attempted to automatically assign it to a product class (auto-assignment). Auto-assignment happens asynchronously. Before the auto-assignment has run the assignment has the status unassigned. After the auto-assignment has completed the assignment can have the status: UNASSIGNED, REJECTED or ASSIGNED depending on whether a product class could be found at all and whether the product class suffices to retrieve all VAT rates of the supported countries. It is worth stressing that auto-assignment cannot change the assignment status to APPROVED because human review is required to reach the status.

An assignment can also be changed through requests to the following endpoint

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

where taxonomy is one of: TARIC, TARES, UKGT. Assignments through this endpoint are marked as being created by the MANUAL assignment strategy as this endpoint is typically called by the user interface. Whenever you call the above endpoint while an auto-assignment is in progress the auto-assignment is aborted. The above endpoint requires you to provide the current version of the assignments so that concurrent updates do not unintentionally overwrite each other. The following request returns a paged list of assignments. The current version of the assignment is included in the response:

GET https://eclear-solutions.com/api/vat-classification/v1/assignments/TARIC?assignmentStatus=UNASSIGNED HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{access_token}}

The path variable taxonomy and the query parameter assignmentStatus are required. The above request queries the assignments for the TARIC that have the status UNASSIGNED.

You can navigate across pages by requesting the links in the links property. The response also contains the property assignmentVersion in the vatRules object that itself is a property of subscribedEclearServices. If we query for any other assignmentStatus the response body also contains the productClassCode and fixedWidthProductClass. These are the codes of the product class that the product is currently assigned to as well as the code padded by "0" from the right so that it is fixed width, respectively (codes on the TARIC AND UKGT have a width of 10 and on the TARES of 8, see Product Taxonomy).

With the assignmentVersion we can now change the assignmentStatus. We have to pass the assignmentActionto the PATCH request. assignmentAction can take one of the following values: "ASSIGN", "APPROVE", "REJECT", "DENY", "RECONFIRM" and "UNASSIGN".

The action ASSIGN associates a product with the provided productClass code. Hence productClassis a required query parameter if assignmentAction=ASSIGN. Depending on whether the productClass code suffices to find VAT rates for all supplied countries the status after the action will be "APPROVED" or "REJECTED", respectively.

The action APPROVE changes the status of "ASSIGNED" to "APPROVED", the action UNASSIGN removes any existing product class codes from the assignment and changes the status to "UNASSIGNED", REJECT changes the status to "REJECTED", DENY changes the status to "DENIED" and RECONFIRM changes that status from "DENIED" to "REJECTED".

The following requests are used to assign a product with productId test111 on the TARIC. First find the current versions of the assignment:

GET https://eclear-solutions.com/api/vat-classification/v1/assignments/TARIC?assignmentStatus=REJECTED&assignmenstStaus=UNASSIGNED&productIds=test111 HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{access_token}}

Then assign the product:

PATCH https://eclear-solutions.com/api/vat-classification/v1/assignments/TARIC?assignmentAction=ASSIGN&productClass=3301291100-80-000 HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{access_token}}

{
  "products": [
    {
      "productId": "test111",
      "assignmentVersion": {
        "vatRules": 1
      }
    }
  ]
}

Assignment labels

To make finding assignments easier to find you can declare assignment labels. The following request defines an assignment label called FOLLOW-UP that should be displayed with a blue color (hex "#0000FF"):

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

{
  "label": "FOLLOW-UP",
  "color": "#0000FF"
}

Now this assignment label can be attached to an assignment. Get the assignmentUuid first:

GET https://eclear-solutions.com/api/vat-classification/v1/assignments/TARIC?assignmentStatus=REJECTED&assignmenstStaus=UNASSIGNED&assignmentStatus=APPROVED&productIds=test111 HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{access_token}}

Now attach the label:

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

{
  "assignmentUuids": ["{{assignmentUuid}}"],
  "labels": ["FOLLOW-UP"]
}

It is now possible to search the assignment by label:

GET https://eclear-solutions.com/api/vat-classification/v1/assignments/TARIC?assignmentStatus=REJECTED&assignmenstStaus=UNASSIGNED&assignmentStatus=APPROVED&labels=FOLLOW-UP HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{access_token}}

If multiple labels are provided the assignments must have all labels to be included in the result set. If you enter a "!" before the assignment label the result set returns all assignments that do not have the label:

GET https://eclear-solutions.com/api/vat-classification/v1/assignments/TARIC?assignmentStatus=REJECTED&assignmenstStaus=UNASSIGNED&assignmentStatus=APPROVED&labels=!FOLLOW-UP HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{access_token}}

Assignment history

You can see the change history of an assignment by first getting the assignmentUuid and then providing it as a path variable in the following request:

GET https://eclear-solutions.com/api/vat-classification/v1/assignments/TARIC/{{assignmentUuid}}?embed=EVENTS HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{access_token}}

The response shows who changed the assignment status at what time and what the product class code was.