NAV Navbar

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.

Hosts

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.velou.com/{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)

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.velou.com/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"
}

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 and 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
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
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
    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

Request: Variation Object

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

Request: Media Object

Parameter Type Description
url String URL of the image
variationId String Unique variation identifier

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

PUT /products/{id} (Update Product)

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

Response

Parameter Type Description
taskId String Unique task identifier

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.velou.com/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.velou.com/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"
}

Request

GET /tasks/{id}

Required API Key: admin

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

Response

Parameter Type Description
status Enum ["pending", "success", "partial_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.velou.com/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

{
  "totalResultCount": 86,
  "results": [
    {
      "id": "1636730011711",
      "url": "https://demostore.com/products/floral-red-dress",
      "name": "Floral Red Dress",
      "brand": "Dress Forum",
      "price": {
        "min": 60,
        "max": 80
      },
      "promoPrice": {
        "min": 0,
        "max": 0
      },
      "defaultVariationId": "1",
      "variations": {
        "1": {
          "name": "Red",
          "swatch": "https://demostore.com/images/swatches/red.png",
          "images": [
            {
              "s": "https://demostore.com/images/products/s/1636730011711.png",
              "m": "https://demostore.com/images/products/m/1636730011711.png",
              "l": "https://demostore.com/images/products/l/1636730011711.png"
            }
          ],
          "colors": [
            {
              "hex": "181413",
              "ratio": 90
            },
            {
              "hex": "858322",
              "ratio": 10
            }
          ]
        }
      }
    }
  ],
  "facets": [
    {
      "key": "pattern",
      "name": "Pattern",
      "values": [
        {
          "key": "floral",
          "name": "Floral",
          "count": 28
        },
        {
          "key": "stripe",
          "name": "Stripe",
          "count": 13,
        }
      ]
    }
  ],
  "spell": [],
  "query": "red long sleeve dress"
}

Request

GET /search

Required API Key: search

Parameter Type Description Default Example
query String Search term NULL red long sleeve dress
facets String Current selected facets as key-value pairs separated by commas NULL color:red,sleeve_length:long
offset Number Pagination offset 0 100
pageSize Number Number of records per page 30 50
spellEnabled Boolean Enable to return spell suggestions false true
facetsEanbled Boolean Enable to return facets facets false true
userId String Unique identifier for current shopper NULL 51w0orqu5
sessionId String Unique identifier for current session NULL bd0fl9aoc

Response

Parameter Type Description
totalResultCount Number Total search results count
results Array[Product] Paginated list of search results
facets Array[Facet] Dynamic list of facet options to narrow down current search results
spell Array[String] List of spell suggestions for current search term
query String Search term

Response: Product Object

Parameter Type Description
id String Unique product identifier
url String URL of original product detail page
name String Name of the product
brand 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
defaultVariationId String Unique identifier for default variation based on shopper's query. Useful to pre-select most relevant variation in search results.
variations Object List of variations

Response: Variation Object

Parameter Type Description
name String Name of the variation
swatch String URL of the swatch image
images Object List of images
  • key: Image size {s=small, m=medium, l=large}
  • value: Image URL
colors Array[Color] Color composition of the variation

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

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

Response: Color 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.velou.com/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": [
    {
      "label": "Black",
      "count": 86
    },
    {
      "label": "Black Clothing",
      "count": 75
    },
    {
      "label": "Blouse",
      "count": 40
    }
  ]
}

Request

GET /suggestions

Required API Key: search

Parameter Type Description Default Example
query String Search term NULL bl

Response

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

Response: Suggestion Object

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

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.velou.com/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": {,
      "searchQuery": "Red Shirt",
      "facets": [
        {
          "key": "pattern",
          "value": "floral"
        }
      ],
      "totalRecs": 2205
    },
    "sessionId": "it2qa7ksj",
    "userId": "bi34ly82v"
  }'

Sample Response

{
  "result": "success"
}

Request

POST /tracking

Required API Key: analytics

Parameter Type Description
type Enum ["Search", "PageChange", "ProductClick", "Purchase"] 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 = Search:
  • searchQuery {String} Search term
  • productIds {Array[String]} List of product IDs returned for search query
  • totalRecs {Number} Total number of records returned for search query
  • facets {Array[Facet]} List of selected facets
type = PageChange:
  • searchQuery {String} Search term
  • productIds {Array[String]} List of product IDs returned for search query
  • totalRecs {Number} Total number of records returned for search query
  • facets {Array[Facet]} List of selected facets
  • page {Number} Current page number
type = ProductClick:
  • searchQuery {String} Search term
  • productIds {Array[String]} List of product IDs returned for search query
  • totalRecs {Number} Total number of records returned for search query
  • facets {Array[Facet]} List of selected facets
  • clickedProductId {String} Product ID clicked by the shopper
type = Purchase:
  • orderId {String} Unique order identifier
  • purchasedProducts {Array[PurchasedProduct]} List of products purchased by the shopper
userId String Unique identifier for current shopper
sessionId String Unique identifier for current session

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.