Catalogue Management

Any update on your system can be automatically pushed, allowing it to be recommended to your users. This can be accomplished by directly linking to the STYLE PTTRNS API either through JSON or CSV files. Alternatively, you can send an email update to your customer success manager on a regular basis via an Excel file. Either way, below you can find the summary of all the fields that you need to add for all catalogue management options.

Name: First you must choose a name for your product, this does not have to be unique, you can configure multiple products with the same name, or even no name at all.
Images: This field contains a list of images, the only required image is the "frontal-(sun)glasses-image-original" for which the URL should lead to an image that shows the frontal view of the (sun)glasses. These images will also be downloaded and saved on our platform. If your website employs bot protection and validates the user-agent header, it may interfere with our processing.
SKU (stock-keeping unit): The SKU is the product ID that you use within your system. This SKU must be correct because it is also returned in our recommendations and used as input in our visualizers. The SKU may use alphanumeric characters (upper and lowercase) and the special characters - and _ (hyphen and underscore).
Category ID: The category ID should be equal to "glasses" if you upload glasses, in case you are uploading sunglasses fill in "sunglasses".
Feature Values: The feature values are the ones you need to provide for each product, these are gender, material, lens width, bridge width and temple length and transparent. Failure to provide these features correctly will result in a 400 Bad Request Exception. This is how they should be provided:
- gender: required string indicating the gender for whom the frame is meant. It can be either "male", "female" or "unisex".
- material: required string indicating the material used in the frame. It can be either "plastic", "metal", "acetate" or "titanium".
- lens width: required integer in mm indicating the width of the lens. This value can range from 25 to 89, including those two values.
- bridge witdth: required integer in mm indicating the width of the bridge.
- temple length: optional integer in mm indicating the length of the temple.
- tranparent: optional boolean wether a frame is transparent (true) or not (false). If this is not provided, then the frame is considered to be not transparent.
Price: There is an optional price. This is a number representing the price of the glasses in your currency (e.g.: 59.99 if your product costs 59 euro and 99 cents, and the currency for your shop is configured as EUR). This field is kept here for backwards compatibility, it can also be configured differently for each product location.
External Virtual-Try-On ID: Next, there's the external virtual-try-on ID, this field is optional and represents the ID Fittingbox that your virtual-try-on (eg: fittingBox) has configured for your eyewear selection. If your shop uses an external virtual-try-on, then it is highly recommended to provide this field as well, failing to do so will exclude this product from the recommendations. If your shop uses our VTO or if you implement your own front-end, then this field does not apply to you.

Catalogue update via excel file

The first method you can use to update your frames is to send a CSV file to your customer success manager. In that file you need to fill the same fields that are shown below.

Material	Gender	Status	CategoryID	Transparent
acetate	female	active	glasses	true
plastic	male	inactive	sunglasses	false
metal	unisex
titanium

Catalogue update via API

All the following calls require Bearer authentication.

Using JSON-body per single product

There are multiple single product calls: POST, PUT, DELETE and PATCH. Although the only recommended methods are the PUT and DELETE call, feel free to also use POST or PATCH.

The PUT and POST methods

The POST and PUT method both require the same data and are used to either fully overwrite an existing product with new data (PUT), or to create new products (PUT and POST). The following fields are required for this call:

featureValues: The features of your product, ony gender, material, lens_width and bridge_width are required
categoryId
sku
name
images

The following data is optional:

externalVtoId: Highly recommended if you use an external VTO, which is not our VTO.
price: This field is kept here for backwards compatibility, it can also be configured differently for each product location.

The PUT call will only reprocess an entrire product (which requires our approval) if the image or a crucial feature has changed.

An example body would look like:

{
      "featureValues":
    [
        {
            "featureId": "gender",
            "value": "female"
        },
        {
            "featureId": "material",
            "value": "metal"
        },
        {
            "featureId": "lens_width", # Crucial feature for processing
            "value": 53
        },
        {
            "featureId": "bridge_width",
            "value": 17
        },
        {
            "featureId": "temple_length", # Optional feature
            "value": 120
        },
        {
            "featureId": "transparent", # Optional feature
            "value": true
        }
    ],
    "categoryId": "sunglasses",
    "sku": "new-sku",
    "name": "Updated",
    "externalVtoId": "989898"  # Optional
    "images": [
    {
      "imageUrl": "https://recommender-platform-public-storage-uat.s3.eu-central-1.amazonaws.com/612de276731e730030b34de1_111120_frontal-sunglasses-image.jpg",
      "filename": "frontal-sunglasses-image-original"
    }
  ]
}

The Swagger documentation for POST and PUT can be found here:

https://style-uat.pttrns.ai/eyewear-api/#/Products/post_products
https://style-uat.pttrns.ai/eyewear-api/#/Products/put_products

The PATCH method

This call is used to update certain fields, and therefore all fields are optional. This call is not recommended as the PUT call is smart enough to know whether an update requires re-processing or not. You cannot update your image with this call but the call can update the following features:

gender
material
bridge_width
transparent
temple_length

An example body will look like this:

{
      "featureValues":
    [
        {
            "featureId": "transparent",
            "value": false
        }
    ],
    "externalVtoId": "77777",
}

In this case we update the transparency feature and the external VTO ID. The SKU is provided in the path of the url (PATCH /products/new-sku)

The Swagger for this method can be found here: https://style-uat.pttrns.ai/eyewear-api/#/Products/patch_products__sku_

The DELETE method

The DELETE method is used for archiving data (be careful to not accidently use this one). The SKU is provided in the path (DELETE /products/new-sku) The swagger can be found here: https://style-uat.pttrns.ai/eyewear-api/#/Products%20Archive/delete_products__sku_

Using CSVs to update multiple products

All CSVs uploaded to our system must be; (semicolon) delimited. Failure to do so will result in an error. It’s also required to use UTF-8 encoding. All fields should exactly match the fields from the documentation. All whitespaces in field names and values should be trimmed. When struggling, please ask for an example CSV.

You can update, create, and delete products in bulk by using the CSV calls:

Please note: for the CSV calls, the PUT- and POST-calls have the same behaviour.

The data that is required is the same as from the previous chapter, except this time the sku is a field and not part of the URL. The fields are:

SKU: the unique ID for the article.
ImageUrl: A URL leading to a front facing image of the frame that can and will be scraped.
Material: The material that the glasses are made of should be one of the following: metal, acetate, plastic, titanium.
Gender: The gender the glasses are intended for, can be one of the following: female, male, unisex.
LensWidth: The width of the lens in millimeters without any unit of measurement. This value can range from 25 to 89, including those two values.
BridgeWidth: The width of the bridge in millimeters without any unit of measurement.
Name: The name of the product which will be displayed and visible to users.
TempleLength: The length of the temple in millimeters without any unit of measurement.
Transparent: Boolean indicating whether a product is transparent (true) or not (false)
GlassesID: Optional ID that represents the externalVtoId of your glasses. If you have an external VTO activated for your shop, then this field is especially important.
Price: Optional price to indicate how much a product costs. This field is kept here for backwards compatibility, it can also be configured differently for each product location.
CategoryID: optional category the product belongs to. This value will default to glasses, in case you are uploading sunglasses fill in “sunglasses”.

So for the PUT and POST calls the following are required (click here for an example csv):

SKU
ImageUrl
Material
Gender
Lenswidth
BridgeWidth
Name
CategoryID

For PATCH all fields except the SKU are optional

For DELETE only the SKU should be provided (click here to download an example csv).

Fetching the SKUs in our system

If you're using our endpoints to manage your catalogue, then you might also want to know which products are configured in our system, for your shop. This can help you build a synchronization service. The following call will return that data for you:

GET https://style-uat.pttrns.ai/eyewear-api/#/Products/get_products_sku

The response is a list of SKUs, that we have in our system for your shop, eg:

 ['SKU12345', 'SKU67890', 'SKU11123', 'SKU45678']

Using JSON-array to update multiple products

To update products in batch we support POST, PUT, PATCH and DELETE methods which are used to create, update or create, partially update and delete resources in an API, respectively.

Since the PUT can create and update, we do not recommend to use the POST-method. Which fields are required, and which aren't is already explained here: Using JSON-body per single product

Example body for PUT and POST request:

[
  {
    "name": "string",
    "images": [
      {
        "imageUrl": "www.string.be/image.jpg",
        "filename": "frontal-glasses-image"
      }
    ],
    "sku": "12355",
    "categoryId": "glasses",
    "featureValues": [
      {
        "featureId": "gender",
        "value": "female"
      }
    ],
    "externalVtoId": "654654",
    "price": 15.5
  }
]

Example body for PATCH request

PATCH: https://style-uat.pttrns.ai/eyewear-api/#/Products%20Batch/patch_products_batch

[
  {
    "name": "string",
    "sku": "12355",
    "externalVtoId": "654654",
    "price": 15.5,
    "featureValues": [
      {
        "featureId": "gender",
        "value": "female"
      }
    ]
  }
]

Example body for DELETE request

DELETE: https://style-uat.pttrns.ai/eyewear-api/#/Products%20Archive/delete_products_batch


['SKU12345', 'SKU67890', 'SKU11123', 'SKU45678']

Implementation tips

When implementing a catalogue management solution, make sure to take the following tips into account:

Every shop has a max amount of products, this amount is dependent on your agreement. When you upload a CSV or batch that will cause this maximum amount to be exceeded, you'll receive an error and the processing request will be rejected.
If you have a new catalogue it's wise to first delete existing products that you no longer need. This will prevent that you exceed the maximum amount of products.
Do not delete too many products, otherwise the recommendation quality will decrease.
Every product you add needs to be approved by us, to guarantee the quality and customer satisfaction. This process can take a while, products will therefore not be immediately available.