Merchant Product Attributes

You can extend the product attributes that you can upload by default. For example, you might be selling a shoe and shoe size is important to assign your products or have it assigned by a customer specific assignment rule. Then you can declare a merchant product attribute called shoe_size with the following request:

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

{
    "fieldName": "shoe_size",
    "displayName": "Shoe size",
    "description": "The size of a shoe in EU format",
    "objectType": "Integer"    
}

display name is the name that is shown in the user interface whereas fieldName is the reference to the merchant product attribute that is used in API calls. The property objectType in the request body can be one of the following: "Text" for text attributes, "Blob" for binary attributes such as PDF files or pictures, "Boolean" for attributes that can only be true or false, "Number" for attributes that take float values and "Integer" for attributes that take integer values.

Check that the merchant product attribute was created by listing all merchant product attributes:

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

After defintion of the field we can now populate it through the product creation or the product update process. We can then read this product attribute, too.

Finally, we can delete merchant product attributes if we do not need them anymore:

DELETE https://eclear-solutions.com/api/vat-classification/v1/products/merchant-product-attributes/shoe_size HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{access_token}}

Binary objects

Defining merchant attributes that are binary objects is nearly identical to all other merchant product attributes. The following request defines a merchant product attribute my_certificate that has object type "Blob":

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

{
    "fieldName": "my_certificate",
    "displayName": "My certificate",
    "description": "A special certificate",
    "objectType": "Blob",
    "isSingleValue": false,
    "documentType": "Certificate"
}

The property isSingleValue controls how many files can be uploaded: isSingleValue=true means only one file can be uploaded, isSingleValue=false allows multiple. In the example my_certificate has isSingleValue=true, so only one document can be uploaded.

In order to populate this attribute the product file API needs to be called. If we want to upload a pdf file called a-nice-cert.pdf for the product with id a-product-id we would make the following call:

POST https://eclear-solutions.com/api/vat-classification/v1/products/global/files?productId=a-product-id HTTP/1.1
Content-Type: multipart/form-data; boundary=----Boundary9fGzQ2wNxT5aK
Authorization: Bearer {{access_token}}

------Boundary9fGzQ2wNxT5aK
Content-Disposition: form-data; name="fieldName"

my_certificate
------Boundary9fGzQ2wNxT5aK
Content-Disposition: form-data; name="file"; filename="a-nice-cert.pdf"
Content-Type: application/pdf

< ./a-nice-cert.pdf
------Boundary9fGzQ2wNxT5aK--

We can read the merchant product attribute with the usual read request:

GET https://eclear-solutions.com/api/vat-classification/v1/products/global?productIds=a-product-id&detail=Large HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{access_token}}

The response contains links to the pdf. With the url we can fetch the document:

GET {{file}}
Content-Type: application/json
Authorization: Bearer {{access_token}}