NAV

Introduction

Welcome to Velou!

The Velou REST API allows you interact directly with Velou to efficiently index your products and perform lightning fast, highly relevant search through your products catalog.

Ready to see it in action? Let's get going!

Getting Started

Velou API provides you with a variety of endpoints to craft intuitive, relevant and powerful search experiences to help your shopper's quickly find what they are looking for.

Formats

All API requests should be JSON encoded as UTF-8. The body of POST and PUT requests must be either a JSON object or a JSON array and their Content-Type header should be set to application/json. The body of responses is always a JSON object, and their content type is always application/json.

Versioning

API releases are versioned using a two part versioning scheme: {major version}.{minor version}. We broadly follow Semantic Versioning principles when versioning the API. The major version number is incremented when a backwards-incompatible change occurs. Minor version numbers are incremented when backwards-compatible changes occur.

Velou API versions are explicitly declared in the URL that your application calls: https://{API_HOST}/{version}

There are several supported versions of the APIs available, and you specify the version that you want to use by substituting the version name in the URL.

Version Release Date Changelog
0.9 March 5, 2019 Beta release
1.0 April 14, 2019 Initial stable version
1.1 June 25, 2019 Introduced facets support
1.2 October 10, 2019 Event tracking improvements (Usage Analytics)
1.3 November 15, 2021 Introducing new attributes: relatedIds, fitInformation, media.highResUrl, media.altText and collections

Authentication

Accessing the Velou API requires the following; these credentials will be provided to you by Velou once your account is established.

Velou API uses key-based authentication over SSL. All requests to Velou API require HTTP headers X-Velou-Store-ID and X-Velou-API-Key for authentication purposes.

Indexing

Add/Update Product

Velou provides an API for indexing the catalog of products in your Velou account. It is important that you leverage this API to keep the Velou product index up-to-date at all times. Consider invoking this API whenever a new product's is added to the catalog or an existing product information gets updated. Please note that this API call is asynchronous. Once the API is invoked, you will receive a unique task identifier which you can use to track the status of the task.

Sample Request

curl -X POST 'https://{API_HOST}/1.0/products' \
  -H 'X-Velou-Store-ID: <store-id>' \
  -H 'X-Velou-API-Key: <api-key-admin>' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "id": "1636730011711",
    "url": "https://demostore.com/products/floral-red-dress",
    "name": "Floral Red Dress",
    "brand": "Dress Forum",
    "slug": "/products/floral-red-dress",
    "description": "Ever comfortable and chic, the classic shift gains a fresh feeling from crisp, colorful crepe.",
    "features": [
      "34 1/2\" length (size Medium).",
      "Exposed back-zip closure.",
      "97% polyester, 3% spandex.",
      "Hand wash cold, dry flat."
    ],
    "categories": [
      "Clothing",
      "Dresses"
    ],
    "gender": "Women",
    "ageGroup": "Adults",
    "variations": [
      {
        "id": "1",
        "name": "Red",
        "swatch": "https://demostore.com/images/swatches/red.png"
      },
      {
        "id": "2",
        "name": "Black",
        "swatch": "https://demostore.com/images/swatches/black.png"
      }
    ],
    "media": [
      {
        "url": "https://demostore.com/images/products/l/1636730011711.png",
        "variationId": "1"
      },
      {
        "url": "https://demostore.com/images/products/l/1636730011711.png",
        "variationId": "2"
      }
    ],
    "skus": [
      {
        "price": 80,
        "variationId": "1",
        "size": "Small",
        "availability": "InStock"
      },
      {
        "price": 82,
        "variationId": "1",
        "size": "Large",
        "availability": "OutOfStock"
      },
      {
        "price": 80,
        "variationId": "2",
        "size": "Small",
        "availability": "InStock"
      }
    ],
    "tags": [
      "vacation",
      "floral",
      "midi dress"
    ],
    "popularity": {
      "type": "STAR",
      "data": {
        "overallRating": 4.3,
        "maxRating": 5,
        "reviewCount": 260
      }
    }
  }'

Sample Response

{
  "taskId": "4fe09ba9f54e81f98e18bce903521981e71fad48"
}

Indexing Request

POST /products (Add Product)

Required API Key: admin

Parameter Type Description
id String Unique product identifier
url String URL of original product detail page
slug String Unique slug typically used in the URL to identify the product uniquely
name String Name of the product
brand String Brand name of the manufacturer
description String Long description of the product
features Array[String] List of features of the product: for example, style information, composition, washing instructions, the country where the product was made, any unique words that describe the item
categories Array[String] List of categories for the product - there can be multiple categories in a hierarchy of categories for a product. If there's a hierarchy for the categories, start at the root level and store it as the first element of the list, and then go down the hierarchy and store the rest.
gender Enum ["Women", "Men", "Unisex"] Gender of the target customer
ageGroup Enum ["Adults", "Teens", "Kids"] Age group of the target customer
relatedIds Array[String] List of all different Ids related to this product. Product will be searchable by these ids if provided
fitInformation Array[String] Size and fit information of the product. Eg:
  • Fit: This garment fits true to size.
  • Length: Mid-thigh. Size small measures 32" from shoulder to hem.
Each line should be a new array item
collections Array[String] List of collection handles. This information is used to filter the products in various collection pages in search. Not used to extract features.
variations Array[Variation] List of variations of the product
media Array[Media] List of media of the product (currently only images are supported)
skus Array[Sku] List of product SKU information including, color, size, price information for all possible combinations
tags Array[String] List of keywords to describe the product. Tags must be in the form prefix:value. E.g: pattern:floral
popularity Object The popularity of the product based on shopper feedback on the your store. There are three different popularity types supported currently: Star rating, Favorites/Likes and Thumbs up/down

The popularity object contains the following information:
  • type {Enum ["STAR", "LIKES", "THUMBS"]} Type of the popularity
  • data {Object} Depending on the type, the values contained in data will be different:
    type = STAR:
    • overallRating {Number} Overall rating for the product.
    • maxRating {Number} Maximum possible rating for product. Typically this is the same across all items for a store.
    • reviewCount {Number} Total review count for the product
    • ratingSummary Array[[Summary Object]]
      • rating: {String} Number of stars
      • count: {String} Number of times "rating" number of starts appear E.g: { rating:4, count:78 } shoppers have voted 4 stars 78 times
    type = LIKES:
      favLikeCount {Number} Favorites / Likes count for the product
    type = THUMBS:
    • thumbsUpCount {Number} Thumbs up count for the product
    • thumbsDownCount {Number} Thumbs down count for the product
customUserData Object Custom data passed to frontend for customer specific actions like showing various badges on the products, setting customer specific ids
  • key: String
  • value: Array of strings
arrivalDateTs Integer Unix timestamp (Milliseconds) for product created time. This is used to sort products based on the newness

Indexing Request: Summary Object

Parameter Type Description
rating String Number of stars
count String Number of times "rating" number of starts appear in the ratings. E.g: { rating:4, count:78 } means shoppers have voted 4 stars 78 times

Indexing Request: Variation Object

Parameter Type Description
id String Unique variation identifier
name String Name of the variation
swatch String URL of the swatch image

Indexing Request: Media Object

Parameter Type Description
url String URL of the image
variationId String Unique variation identifier
highResUrl String URL of the larger version of the image if available. This is used for image analysis
altText String Alternate text for the image if available

Indexing Request: Sku Object

Parameter Type Description
price Number Price of the variation
variationId String Unique variation identifier
size String Size label
promoPrice Number Promotional price of the variation
availability Enum ["InStock", "OutOfStock"] Stock availability of variation
inventoryQuantity Number Stock level of the SKU

Delete Product

This API prodivdes facility to delete an existing product from Velou index. It is important that you leverage this API to keep the Velou product index up-to-date at all times. Consider invoking this API whenever a product is removed from your product catalog. Please note that this API call is asynchronous. Once the API is invoked, you will receive an unique task identifier which you can use to track the status of the task.

Sample Request

curl -X DELETE 'https://{API_HOST}/1.0/products/1636730011711' \
  -H 'X-Velou-Store-ID: <store-id>' \
  -H 'X-Velou-API-Key: <api-key-admin>'

Sample Response

{
  "taskId": "4fe09ba9f54e81f98e18bce903521981e71fad48"
}

Request

DELETE /products/{id}

Required API Key: admin

Parameter Type Description Default Example
id (URL) String Unique product identifier NULL 1636730011711

Response

Parameter Type Description
taskId String Unique task identifier

Task Tracking

All asynchronous API calls supported by Velou during the product indexing returns a unique task identifier. Task tracking API is useful to understand the current status of each task you've queued on Velou indexing process. This API takes a unique task identifier as the input.

Sample Request

curl -X GET 'https://{API_HOST}/1.0/tasks/4fe09ba9f54e81f98e18bce903521981e71fad48' \
  -H 'X-Velou-Store-ID: <store-id>' \
  -H 'X-Velou-API-Key: <api-key-admin>'

Sample Response

{
  "status": "success",
  "createdAt": "2018-12-30 16:21:00.480Z",
  "updatedAt": "2018-12-30 16:22:00.480Z"
}

Task Tracking Request

GET /tasks/{id}

Required API Key: admin

Parameter Type Description Default Example
id String Unique task identifier NULL 4fe09ba9f54e81f98e18bce903521981e71fad48

Task Tracking Response

Parameter Type Description
status Enum ["pending", "success", "error"] Current status of the task
createdAt Date Timestamp at which task was created
updatedAt Date Timestamp at which task was last updated

Searching

Search Results

Velou provides an API for searching the catalog of products indexed in your Velou account. The API provides the ability to return results based on a search query. The response will include data points to build a powerful search experience, such as products that match the search criteria, available facet options to further refine the results, spell correction suggestions and data useful for paginating the search results.

Sample Request

curl -X GET 'https://{API_HOST}/1.0/search?query=red%20long%20sleeve%20dress&offset=100&pageSize=50&spellEnabled=true&facetsEnabled=true&facets=color:red,sleeve_length:long&userId=51w0orqu5&sessionId=bd0fl9aoc' \
  -H 'X-Velou-Store-ID: <store-id>' \
  -H 'X-Velou-API-Key: <api-key-search>'

Sample Response

{
  "totalProductCount": 1,
  "products": [
    {
      "id": "605a14affb1e95bd9cb37fba",
      "productId": "6158888960197",
      "url": "https://demo.velou.com/products/texas-rose-plus",
      "name": "Texas Rose - Plus",
      "designer": "Bali ELF",
      "price": {
        "min": 139.95,
        "max": 139.95
      },
      "promoPrice": {
        "min": 0,
        "max": 0
      },
      "initialPrice": {
        "min": 186.95,
        "max": 186.95
      },
      "customProps": {},
      "defaultColorId": "2",
      "colors": {
        "1": {
          "name": "White",
          "swatch": "https://demo-images.velou.com/w_150/f_auto/q_auto/ar_0.66,c_fill/v1604012081/product-images-octo/labo5b0btg7sxlfpxavd.jpg",
          "images": [
            {
              "s": "https://demo-images.velou.com/w_750/f_auto/q_auto/ar_0.66,c_fill/v1604012081/product-images-octo/labo5b0btg7sxlfpxavd.jpg",
              "m": "https://demo-images.velou.com/w_750/f_auto/q_auto/ar_0.66,c_fill/v1604012081/product-images-octo/labo5b0btg7sxlfpxavd.jpg",
              "l": "https://demo-images.velou.com/w_750/f_auto/q_auto/ar_0.66,c_fill/v1604012081/product-images-octo/labo5b0btg7sxlfpxavd.jpg"
            }
          ],
          "values": [
            {
              "hex": "e0d3c3",
              "ratio": 50
            },
            {
              "hex": "d1c2a8",
              "ratio": 50
            }
          ],
          "productUrl": "https://demo.velou.com/products/texas-rose-plus?variant=37897423225029",
          "promoPrice": {
            "min": 0,
            "max": 0
          },
          "price": {
            "min": 139.95,
            "max": 139.95
          },
          "initialPrice": {
            "min": 186.95,
            "max": 186.95
          }
        },
        "2": {
          "name": "Ruby",
          "swatch": "https://demo-images.velou.com/w_150/f_auto/q_auto/ar_0.66,c_fill/v1604009390/product-images-octo/zfe71m3npqzc3jl5yxl5.jpg",
          "images": [
            {
              "s": "https://demo-images.velou.com/w_750/f_auto/q_auto/ar_0.66,c_fill/v1604009390/product-images-octo/zfe71m3npqzc3jl5yxl5.jpg",
              "m": "https://demo-images.velou.com/w_750/f_auto/q_auto/ar_0.66,c_fill/v1604009390/product-images-octo/zfe71m3npqzc3jl5yxl5.jpg",
              "l": "https://demo-images.velou.com/w_750/f_auto/q_auto/ar_0.66,c_fill/v1604009390/product-images-octo/zfe71m3npqzc3jl5yxl5.jpg"
            }
          ],
          "values": [
            {
              "hex": "4b0d1d",
              "ratio": 12
            },
            {
              "hex": "791e37",
              "ratio": 43
            },
            {
              "hex": "91354e",
              "ratio": 45
            }
          ],
          "productUrl": "https://demo.velou.com/products/texas-rose-plus?variant=37897423257797",
          "promoPrice": {
            "min": 0,
            "max": 0
          },
          "price": {
            "min": 139.95,
            "max": 139.95
          },
          "initialPrice": {
            "min": 186.95,
            "max": 186.95
          }
        },
        "3": {
          "name": "Navy Blue",
          "swatch": "https://demo-images.velou.com/w_150/f_auto/q_auto/ar_0.66,c_fill/v1604010964/product-images-octo/g4xdj4mmwksgzmezjjkw.jpg",
          "images": [
            {
              "s": "https://demo-images.velou.com/w_750/f_auto/q_auto/ar_0.66,c_fill/v1604010964/product-images-octo/g4xdj4mmwksgzmezjjkw.jpg",
              "m": "https://demo-images.velou.com/w_750/f_auto/q_auto/ar_0.66,c_fill/v1604010964/product-images-octo/g4xdj4mmwksgzmezjjkw.jpg",
              "l": "https://demo-images.velou.com/w_750/f_auto/q_auto/ar_0.66,c_fill/v1604010964/product-images-octo/g4xdj4mmwksgzmezjjkw.jpg"
            }
          ],
          "values": [
            {
              "hex": "0d1e36",
              "ratio": 30
            },
            {
              "hex": "36597c",
              "ratio": 17
            },
            {
              "hex": "8e969d",
              "ratio": 53
            }
          ],
          "productUrl": "https://demo.velou.com/products/texas-rose-plus?variant=37897423290565",
          "promoPrice": {
            "min": 0,
            "max": 0
          },
          "price": {
            "min": 139.95,
            "max": 139.95
          },
          "initialPrice": {
            "min": 186.95,
            "max": 186.95
          }
        }
      }
    }  

  ],
  "facets": [
    {
      "key": "price",
      "name": "Price",
      "values": [
        {
          "key": "r10",
          "count": 1,
          "lb": 80,
          "ub": 100
        },
        {
          "key": "r11",
          "count": 1,
          "lb": 100,
          "ub": 120
        },
        {
          "key": "r12",
          "count": 2,
          "lb": 120,
          "ub": 140
        }
      ]
    },
    {
      "key": "fit",
      "name": "Fit",
      "values": [
        {
          "key": "plus",
          "name": "Plus",
          "count": 2
        }
      ]
    }
  ],
  "spellSuggestions": [],
  "query": "red long sleeve dress",
  "collection": "new-arrivals"
}

Search Request

GET /search

Required API Key: search

Parameter Type Description
query String Search term used for filtering. At least one of query or collection parameters must be supplied.

Example: red long sleeve dress.

collection String Collection handle used for filtering. At least one of query or collection parameters must be supplied.

Example: dresses

from Number Pagination offset

Example: 100
Default: 0

pageSize Number Number of records per page

Example: 50
Default: 30

userId String Unique identifier for current shopper. This information is used to identify returning shoppers for personalization

Example: 51w0orqu5
Default: NULL

sessionId String Unique identifier for current session. This information is used for personalization

Example: bd0fl9aoc
Default: NULL

preprod Boolean Set true to indicate that we are running on the pre production mode. In the pre production mode, Velou receives search queries when the shoppers perform searches. But they still see the results from the website's existing search solution. Pre-production mode is usually used to examin production traffic just before deploying Velou search on production

Example: true
Default: false

returnFacets Boolean Set true to return facets

Example: true
Default: false

facets String Current selected facets as key-value pairs separated by commas

Example: color:red,sleeve_length:long
Default: NULL

campaignProducts String Comma separated value of product ids. Used with campaign value in sortBy

Example: 261252712,373849939,473673552
Default: NULL

sortBy String Sort parameter. Following values are supported at the moment.
  • rating: Sort by the star rating of the product. If the ratings summary is available, star rating is normalized using Wilson formula
  • new: Sort by product arrival timestamp in descending order
  • newc: Product arrival timestamp is divided by an integer n to create n day blocks. n is pre configured per store basis. Sorted by the resulting value in descending order.
  • newc2: The difference between product's arrival timestamp and the current timestamp is divided by an integer n. n is pre configured value. Sorting is done by the resulting value in ascending order
  • purchase: Sort by product purchase count in descending order
  • pricea: Sort by product price in ascending order
  • priced: Sort by product price in descending order
  • namea: Sort by product name in ascending order
  • named: Sort by product name in descending order
  • stocka: Sort by stock count in ascending order (Note: Stock count must be available via the index API)
  • stockd: Sort by stock count in descending order (Stock count must be available via the index API)
  • campaign: Product ids sent through campaignProducts parameter are moved to the top of the search results list. This mechanism can be used to boost arbitrary products up the search results for various marketing campaigns
  • rating2: Sort by the star rating of the product. Average star rating is normalized using Bayesian Estimate
  • vendor_based_newness: Same as newc2, The difference between product's arrival timestamp and the current timestamp is divided by a pre configured value. Sorting is done by the resulting value in ascending order. However, pre-configured number of products from each vendor is moved to the top of the list randomly. This results in each vendor having fair chance to show their products at the top of the list if there are newly arrived products from multiple vendors

Example: rating
Default: NULL

Search Response

Parameter Type Description
totalProductCount Number Total search results count
products Array[Product] Paginated list of search results
fallback Boolean Indicates if the search engine decided to run a fallback query instead of the query sent through the query parameter. This might happen if the original query is not producing any results. This flag can be used to display a message to the shopper indicating produced results are not for his original query
facets Array[Facet] Dynamic list of facet options to narrow down current search results
spellSuggestions Array[String] List of spell suggestions for current search term
query String Search term used for filtering if available
collection String Collection handle used for filtering if available

Search Response: Product Object

Parameter Type Description
id String Unique Velou product identifier
productId String Unique store product identifier
url String URL of original product detail page
name String Name of the product
designer String Brand name of the manufacturer
price Object Price range considering all SKUs
  • min {Number} price lower bound
  • max {Number} price upper bound
promoPrice Object Promotional price range considering all SKUs
  • min {Number} price lower bound
  • max {Number} price upper bound
initialPrice Object Initial price range considering all SKUs
  • min {Number} price lower bound
  • max {Number} price upper bound
customUserData Object Custom data passed to frontend for customer specific actions like showing various badges on the products, setting customer specific ids
  • key: String
  • value: Array of strings
productPopularity Object Product ratings data. Please refer to popularity in index API for more information
defaultColorId String Id of the color variant that should be selected by default
colors Object List of color variations
ccv Object Converted price values for the product if the currency conversion is configured for this store Object

Search Response: Color Variation Object

Parameter Type Description
name String Name of the variation (Color)
swatch String URL of the swatch image if available
images Object List of images
  • key: Image size {s=small, m=medium, l=large}
  • value: Image URL
values Array[Color] Color composition of the variation if the color details are extracted
productName String Name of the color variant. Some e-commerce stores have slightly different product names for the color variations
productUrl String URL of original product detail page for this color variation
productId String Unique store product identifier for this color variation
promoPrice Object Promotional price range of the color variant considering all SKUs
  • min {Number} price lower bound
  • max {Number} price upper bound
price Object Price range of the color variant considering all SKUs
  • min {Number} price lower bound
  • max {Number} price upper bound
initialPrice Object Initial price range of the color variant considering all SKUs
  • min {Number} price lower bound
  • max {Number} price upper bound
ccv Object Converted price values for the color variance if the currency conversion is configured for this store Object

Search Response: Currency Conversion Object

Parameter Type Description
price Object Converted price range of the product considering all SKUs
  • min {Number} price lower bound
  • max {Number} price upper bound
promoPrice Object Converted promotional price range of the product considering all SKUs
  • min {Number} price lower bound
  • max {Number} price upper bound
initialPrice Object Converted initial price range of the product considering all SKUs
  • min {Number} price lower bound
  • max {Number} price upper bound
currency String Currency code of the converted currency

Search Response: Facet Object

Parameter Type Description
key String Unique key to identify the facet
name String Name of the facet
values Array[FacetValue] List of facet values for current facet

Search Response: Facet Value Object

Parameter Type Description
key String Unique key to identify the facet value
name String Name of the facet value
count Number Number of search results for facet value

Search Response: Color Value Object

Parameter Type Description
hex String Hexadecimal value of the color
ratio Number Composition ratio of the color

Query Suggestions

Velou provides an API to return helpful query recommendations based on shopper's current search query. This API can be handy to implement an autocomplete/typeahead feature as shopper inputs a partial search query. Velou's search algorithm generates query suggestions based on your indexed products catalog as well as using previous/popular search queries.

Sample Request

curl -X GET 'https://{API_HOST}/1.0/suggestions?query=bl' \
  -H 'X-Velou-Store-ID: <store-id>' \
  -H 'X-Velou-API-Key: <api-key-search>'

Sample Response

{
  "query": "bl",
  "suggestions": [
    {
      "id": 1,
      "label": "Black",
      "count": 86
    },
    {
      "id": 2,
      "label": "Black Clothing",
      "count": 75
    },
    {
      "id": 3,
      "label": "Blouse",
      "count": 40
    }
  ]
}

Suggestions Request

GET /suggestions

Required API Key: search

Parameter Type Description Default Example
query String Search term NULL bl
preprod Boolean Set true to indicate that we are running on the pre production mode. In the pre production mode, Velou receives search queries when the shoppers perform searches. But they still see the results from the website's existing search solution. Pre-production mode is usually used to examin production traffic just before deploying Velou search on production false true

Suggestions Response

Parameter Type Description
suggestions Array[Suggestion] List of query suggestions matching search term
designers Array[Suggestion] List of brand suggestions matching search term
query String Search term

Suggestions Response: Suggestion Object

Parameter Type Description
id String Search term id
label String Suggested search term
count Number Number of search results for suggested search term

Similarity

Velou provides you an API to find similar products for any given product. This facility can be used to show other similar products in a product description page for your shoppers further increasing the chance of them buying a product.

Sample Request

curl --request GET \
  --url 'https://{API_HOST}/1.0/similarity?from=0&pageSize=20&productId=73529573021&variantId=12532' \
    -H 'X-Velou-Store-ID: <store-id>' \
    -H 'X-Velou-API-Key: <api-key-search>'

Sample Response

{
  "totalProductCount": 20,
  "products": [
    {
      "product": {
        "id": "615498f5d3c391de972a22bd",
        "productId": "62853527846",
        "url": "https://demo.velou.com/products/chiffon-wrap-top",
        "name": "Navy Ruched Chiffon Wrap Top",
        "designer": "ELF",
        "price": {
          "min": 9.99,
          "max": 9.99,
          "first": 9.99
        },
        "promoPrice": {
          "min": 0,
          "max": 0,
          "first": 0
        },
        "initialPrice": {
          "min": 24.99,
          "max": 24.99,
          "first": 24.99
        },
        "customUserData": {
          "auroraId1": [
            "286504"
          ]
        },
        "defaultColorId": "1",
        "colors": {
          "1": {
            "name": "Navy",
            "swatch": "https://demo.velou.com/images/navy",
            "images": [
              {
                "s": "https://demo.velou.com/images/62853527846_s",
                "m": "https://demo.velou.com/images/62853527846_m",
                "l": "https://demo.velou.com/images/62853527846_l"
              }
            ],
            "promoPrice": {
              "min": 0,
              "max": 0
            },
            "price": {
              "min": 9.99,
              "max": 9.99,
              "first": 9.99
            },
            "initialPrice": {
              "min": 24.99,
              "max": 24.99,
              "first": 24.99
            }
          }
        }
      }
    },
    ...
  ],
  "facets": [
    {
      "key": "sizes",
      "name": "Size",
      "values": [
        {
          "key": "6",
          "name": "6",
          "count": 6
        },
        {
          "key": "8",
          "name": "8",
          "count": 9
        },
        {
          "key": "10",
          "name": "10",
          "count": 9
        },
        {
          "key": "12",
          "name": "12",
          "count": 10
        },
        {
          "key": "14",
          "name": "14",
          "count": 6
        },
        {
          "key": "16",
          "name": "16",
          "count": 5
        },
        {
          "key": "18",
          "name": "18",
          "count": 1
        },
        {
          "key": "s",
          "name": "S",
          "count": 6
        },
        {
          "key": "m",
          "name": "M",
          "count": 6
        },
        {
          "key": "l",
          "name": "L",
          "count": 5
        }
      ],
      "specialValues": []
    }
  ],
  "sourceProduct": {
    "productId": "73529573021",
    "image": "https://demo.velou.com/images/00100029021_XM?$plptest$&fmt=webp",
    "name": "Blue Knitted Wrap Jumper"
  }
}

Similarity Request

GET /similarity

Required API Key: search

Parameter Type Description Default Example
productId String Velou search engine will find the similar products for the product that has this id NULL 628373838
from Number Pagination offset 0 100
pageSize Number Number of records per page 30 50
variantId String Variant id. When searching similar products, this variant will also be considered if available NULL 62524
facets String Current selected facets as key-value pairs separated by commas NULL sizes:10,sleeve_length:long

Similarity Response

Parameter Type Description
totalProductCount Number Total similar items count
products Array[ProductWrapper] Paginated list of similar items
facets Array[Facet] Dynamic list of facet options to narrow down similar items list
sourceProduct Object Details about the product similar items are returned for.
  • productId: {String} Unique store product identifier
  • image: {URL} main image of the product
  • name: {String} Name of the product

Response: ProductWrapper Object

Parameter Type Description
product Array[Product] Product Object

Analytics

Event Tracking

Velou uses event tracking on your store to generate valuable insights on your shopper behavior and to monitor how Velou contributes to the convertion of your customers. Velou also uses these data points to boost the most important products to the top of search results based on past shopper behavior (ranking). It is highly recommend you report all event types accurately to get the maximum benefit through Velou's reporting platform and ranking algorithm.

Sample Request

curl -X POST 'https://{API_HOST}/1.0/tracking' \
  -H 'X-Velou-Store-ID: <store-id>' \
  -H 'X-Velou-API-Key: <api-key-analytics>' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "type": "Search",
    "data": {,
      "query": "Red Shirt",
      "pageSize": 30,
      "sortBy": "relevance",
      "productIds": [
        "6153342714048",
        "6642820382912",
        "6536276934848"
      ],
      "facets": [
        {
          "key": "pattern",
          "value": "floral"
        }
      ],
      "totalProducts": 3
    },
    "sessionId": "it2qa7ksj",
    "userId": "bi34ly82v"
    "storeId": "storeId"
  }'

Sample Response

{
  "ok":true
}

Request

POST /tracking

Required API Key: analytics

Parameter Type Description
type Enum ["SiteView", "Search", "PageChange", "SortByChange", "ProductClick", "AddToCart", "OrderComplete", "Purchase", "ViewSimilarProducts", "SimilarProductClick"] Type of activity performed by the shopper
data Object Additional important details related to the event.

Depending on the type, the values contained in data will be different:
type = SiteView:
  • location {String} The current page address
  • referrer {String} The URI of the page that linked to this page
  • userAgent {String} TheThe user-agent header
type = Search:
  • query {String} Search term
  • productIds {Array[String]} List of product IDs returned for search query
  • pageSize {Number} Number of items to appear on search results page
  • sortBy {String} Selected sortBy option for search query
  • totalProducts {Number} Total number of records returned for search query
  • facets {Array[Facet]} List of selected facets
type = PageChange:
  • query {String} Search term
  • productIds {Array[String]} List of product IDs returned for search query
  • facets {Array[Facet]} List of selected facets
  • pageSize {Number} Number of items to appear on search results page
  • sortBy {String} Selected sortBy option for search query
  • page {Number} Current page number
type = ProductClick:
  • query {String} Search term
  • productIds {Array[String]} List of product IDs returned for search query
  • facets {Array[Facet]} List of selected facets
  • pageSize {Number} Number of items to appear on search results page
  • sortBy {String} Selected sortBy option for search query
  • page {Number} Current page number
  • clickProductId {String} The clicked product id
type = SortByChange:
  • query {String} Search term
  • productIds {Array[String]} List of product IDs returned for search query
  • facets {Array[Facet]} List of selected facets
  • pageSize {Number} Number of items to appear on search results page
  • sortBy {String} Selected sortBy option for search query
type = AddToCart:
  • query {String} Search term
  • productIds {Array[String]} List of product IDs returned for search query
  • facets {Array[Facet]} List of selected facets
  • pageSize {Number} Number of items to appear on search results page
  • sortBy {String} Selected sortBy option for search query
  • page {Number} Current page number
  • totalProducts {Number} The total number of products.
  • addProductId {String} The product Id added to cart.
  • qty {Number} The product quantity added to cart.
type = OrderComplete:
  • orderId {String} Unique order identifier
type = Purchase:
  • orderId {String} Unique order identifier
  • products {Array[Product]} List of products purchased by the shopper
type = ViewSimilarProducts:
  • productId {String} The original product id which used to view other similar products.
type = SimilarProductClick:
  • similarProductId {String} The similar product id.
  • clickProductId {String} The clicked product id.
userId String Unique identifier for current shopper.
sessionId String Unique identifier for current session.
storeId String Unique identifier of the shop.

Request: Purchased Product Object

Parameter Type Description
id String Unique product identifier
price Number Price of the product

Response

Parameter Type Description
result Enum ["success", "error"] Result of the request

Error Handling

Whether a request succeeded is indicated by the HTTP status code. A 2xx status code indicates success, whereas a 4xx status code indicates failure.

When a request fails, the response body is still JSON, but always contains a message field with a description of the error, which you can inspect for debugging.

The Velou API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request is invalid. Response body usually provides details of the error.
401 Unauthorized – Your Store ID or API Key is wrong. Ensure you are using API Key with required permissions to access the resource.
404 Not Found – Your request is looking for a non-existant resource.
500 Internal Server Error – An unexpected error occured at server-side. Retry the request after few minutes or contact Velou if problem persists over a long period.

Tag generation webhook

In addition to the search functionality, Velou can enrich your data by providing you product features identified by Velou. You can use webhook subscriptions to receive this information. Once subscribed, tag generation webhooks will be called as soon as Velou identify the features of any product you send via the indexing API. It is possible to call the webhooks multiple times for a single product as Velou identify features at various stages of the analysis process. (E.g. Text analysis, Image analysis, etc)

Webhook Headers

Header Description Example
x-velou-topic Webhook Topic tags
x-velou-hmac-sha256 base64 encoded string that is used to verify a webhook notification BE90+RWqMIFylcyc969HlGznlZ9MPnGQxvmEs+o5C7U=
x-velou-store-id Id of the store registered with Velou my_store_123
x-velou-ts UNIX timestamp in milliseconds. This is used to compute the HMAC hash for request authentication 1638164106697
x-velou-api-version Version of the webhook API being used. 1.3
x-velou-webhook-id Id of the webhook 526143728

Webhook body

Parameter Type Description Default
id String Unique Velou product identifier
productId String Unique store product identifier
features Object Object containing identified features and feature values
  • Key: {String} feature name
  • Value: {Array} Array of feature values

Example webhook body given below

{
  "id": "5f637c246b9eeecb1134a212",
  "productId": "812456103",
  "features": {
        "attributes" : [ 
            "hand_washed", 
            "stretch", 
            "back_in_stock",
            "lined"
        ],
        "country_of_origin": [
            "gb"
        ],
        "brands" : [ 
            "boohoo"
        ],
        "category" : [ 
            "dresses"
        ],
        "closure" : [ 
            "back_zipper",
            "zipper"
        ],
        "concept" : [ 
            "evening", 
            "new_in", 
            "christmas_party", 
            "new_year", 
            "little_black_dress", 
            "wedding_guest", 
            "going_out",
            "party", 
            "date_night" 
        ],
        "embellishments" : [ 
            "ruching", 
            "glitter"
        ],
        "fit" : [ 
            "petite"
        ],
        "hemline" : [ 
            "tulip"
        ],
        "length" : [ 
            "mini"
        ],
        "material" : [ 
            "polyester", 
            "elastane"
        ],
        "neckline" : [ 
            "plunging", 
            "v_neckline"
        ],
        "pattern" : [ 
            "solid"
        ],
        "product_color" : [ 
            "black"
        ],
        "sizes" : [ 
            "size_2", 
            "size_4", 
            "size_6", 
            "size_8"
        ],
        "sleeve_length" : [ 
            "long"
        ],
        "sleeve_style" : [ 
            "plain"
        ],
        "style" : [  
            "bodycon"
        ],
        "gender" : [ 
            "women"
        ]
    }
}

Retry logic

If the webhook is not responded within 5 seconds or any status code other than 2xx is received, Velou consider it as a failure and fall back to a retry cycle. Following retry strategy is currently in place

  1. Try 3 times with 30 second interval in between
  2. Try 3 times with 2 minutes wait time between each attempt
  3. Try 3 times with 5 minutes wait time between each attempt
  4. Try 3 times with 1 hour wait time between each attempt
  5. Try 2 times with 6 hour wait time between each attempt
  6. Try one last time after 24 hours

Webhook Authentication

When you receive a webhook request, it is very important to verify that the request has originated from Velou before processing it any further. Velou provides a digital signature for you to use in this verification process. A string is generated by concatenating body of the request with number of other parameters. Final signature is obtained by signing this string with a shared secret key. Velou provides you this secret key as part of the setup process. A simple nodejs snippet is given below in order to explain the authentication process.

const express = require('express')
const crypto = require('crypto')
const getRawBody = require('raw-body')
const app = express()

const webhookSecret = MY_VELOU_SECRET

app.post('/webhook', async (req, res) => {

  try {
    // Parse the request body
    const body = await getRawBody(req)

    // Extract x-velou-hmac-sha256 header from the request
    const hmacHash = req.header('x-velou-hmac-sha256')

    // Extract x-velou-store-id header from the request
    const storeId = req.header('x-velou-store-id')

    // Extract x-velou-ts header from the request. 
    // This is a UNIX timestamp in milliseconds indicating the request created time.
    const signatureTs = req.header('x-velou-ts')

    // Extract x-velou-topic header from the request
    // This is the webhooks topic. For tag generation, its value is "tags"
    const topic = req.header('x-velou-topic')

    // Extract x-velou-webhook-id header from the request
    // When a webhook is registered with velou, its given a unique id
    const id = req.header('x-velou-webhook-id')

    const signatureSourceComponents = [
      storeId, signatureTs, topic, id, body.toString('utf8')
    ]

    const computedHash = crypto.createHmac('sha256', webhookSecret)
      .update(signatureSourceComponents.join('.'))
      .digest('base64')

    if (computedHash === hmacHash) {
      console.log("Webhook source confirmed. Continue processing");
      res.sendStatus(200)
    } else {
      console.log("Unidentified webhook source. Do not process");
      res.sendStatus(403)
    }
  } catch (e) {
    console.error(e)
    res.sendStatus(500)
  }
})

app.listen(43215)

Best practices