Skip to content

Autocomplete

https://{cluster-id}.api.esales.apptus.cloud/api/v2/queries/autocomplete

GET

Deprecated

This endpoint is part of an API that has been deprecated and its end of life is 2024-04-30. All endpoints in this API version, including this, will be removed. Please upgrade to the latest version before 2024-04-30.

All API changes can be found here:

More information regarding the API versioning strategy can be found here.

Autocomplete is a query used to retrieve search suggestions, product suggestions, and content item suggestions as the visitor types. All suggestions are returned with autocorrect automatically applied as well as supporting highlighting hints, compatible with any corrections. A query can be sent on every key-press, but a debounce on 50 ms is recommended to avoid unnecessary requests while still creating an extremely snappy experience. The contentList is empty unless specified in the request body. The request body is specified in a POST request.

Request

Header parameters

Name Description Example
Accept-Encoding Allows responses to be compressed using Gzip. gzip

Query parameters

Name Description Example
customerKey
Required
A key that uniquely identifies the current visitor.Using UUIDs as keys are recommended. 0b05119e-eeb8-418a-bbfb-defa0dde417e
market
Required
The visitor market identifier. Must match the corresponding market identifier in the data feed. UK
sessionKey
Required
A unique key, identifying the session.Using UUIDs as keys are recommended. 0b05119e-eeb8-418a-bbfb-defa0dde417e
touchpoint
Required
The visitor's touchpoint. Supported values: DESKTOP, MOBILE. DESKTOP
channels Which channels to use. Valid values are ONLINE and STORE. Multiple values are provided with a pipe, |, as a separator. channels will default to ONLINE|STORE if nothing is provided. If STORE is explicitly provided then stores cannot be empty. Supported values: ONLINE, STORE. ONLINE|STORE
notify A boolean that can be used to disable notifications and behavioural registration for the query. false
presentCustom A pipe-separated list of custom product attributes to include in all listings. season|manufacturer
presentPrices A pipe-separated list of custom price ids to include in all listings. Each id must match a supplied custom price id in the data feed. VIP|member
priceId A custom price identifier. Must match supplied custom price identifiers in the data feed. VIP
q The visitor search query. blu
stores Which stores to use. Will impact which stock is displayed and which stock is used for filtering/ranking together with channel. Multiple values are provided with a pipe, |, as a separator. Each store must match a supplied store key in the data feed. 240|100
viewId A parameter that is used to show the page in either production or preview mode. Can be production or preview. Defaults to production if omitted in the query. For more information, see App Integration. Supported values: PRODUCTION, PREVIEW. production
curl -i \
-X GET \
-H 'Accept-Encoding: gzip' \
"https://{cluster-id}.api.esales.apptus.cloud/api/v2/queries/autocomplete?customerKey=0b05119e-eeb8-418a-bbfb-defa0dde417e&market=UK&sessionKey=0b05119e-eeb8-418a-bbfb-defa0dde417e&touchpoint=DESKTOP&channels=ONLINE%7CSTORE&notify=false&presentCustom=season%7Cmanufacturer&presentPrices=VIP%7Cmember&priceId=VIP&q=blu&stores=240%7C100&viewId=production"

Response

Response codes

Status Description
200 Query accepted, content flattened and serialised to JSON.
400 Invalid or missing required arguments.
404 Endpoint is not valid.
503 Service unavailable, no products found in the cluster.
500 Server error such as cluster unavailable or busy. The response body may contain more information about the error.

Response headers

Name Type Description Example
X-Response-Time Response time in milliseconds (ms) 65

Response body

Example
application/json;charset=utf-8
{
  "contentLists" : [ {
    "id" : "content-hits",
    "items" : [ {
      "custom" : {
        "tags" : [ {
          "id" : "78",
          "label" : "Guide"
        }, {
          "id" : "223",
          "label" : "Jeans"
        } ]
      },
      "description" : "To wash or not to wash? And how?! Those are questions jeans shoppers are asking.",
      "image" : {
        "alt" : "A woman wearing a white t-shirt",
        "caption" : "The model is 176 cm tall and is wearing size S",
        "custom" : { },
        "sources" : [ {
          "url" : "https://cdn.example.com/img/j12_prod.jpg",
          "height" : 820,
          "width" : 420
        } ]
      },
      "key" : "wash_care",
      "link" : "/wash-guide",
      "releaseDate" : "2021-10-01T00:00:00Z",
      "ticket" : "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7",
      "title" : "How to wash jeans",
      "type" : "article"
    } ],
    "totalHits" : 10
  } ],
  "phraseSuggestions" : [ {
    "highlighted" : "{jea}ns",
    "q" : "Jeans"
  } ],
  "productSuggestions" : [ {
    "key" : "PRODGROUP060194",
    "products" : [ {
      "badges" : {
        "primary" : [ {
          "attribute" : "is_new",
          "label" : "Latest!",
          "theme" : "NEW"
        } ],
        "secondary" : [ {
          "attribute" : "is_new",
          "label" : "Latest!",
          "theme" : "NEW"
        } ]
      },
      "brand" : "Versace",
      "custom" : { },
      "depth" : {
        "amount" : 25.0,
        "unit" : "cm"
      },
      "description" : "Super elastic fit.",
      "height" : {
        "amount" : 25.0,
        "unit" : "cm"
      },
      "imageInfo" : {
        "effect" : "NONE",
        "images" : [ {
          "alt" : "A woman wearing a white t-shirt",
          "caption" : "The model is 176 cm tall and is wearing size S",
          "custom" : { },
          "sources" : [ {
            "url" : "https://cdn.example.com/img/j12_prod.jpg",
            "height" : 820,
            "width" : 420
          } ]
        } ],
        "thumbnail" : "https://cdn.example.com/thumbs/j12_prod.jpg"
      },
      "inStock" : true,
      "key" : "p1000-101",
      "length" : {
        "amount" : 25.0,
        "unit" : "cm"
      },
      "link" : "men/jeans/country-fit-cowboy-jeans",
      "listPrice" : {
        "max" : 4500.0,
        "min" : 190.5
      },
      "name" : "Romeo",
      "rating" : 4.5,
      "sellingPrice" : {
        "max" : 4500.0,
        "min" : 190.5
      },
      "series" : "Billy",
      "swatch" : {
        "colors" : [ "#FF0000" ],
        "type" : "COLORS"
      },
      "ticket" : "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7",
      "title" : "Country Fit Cowboy Jeans",
      "typedCustom" : {
        "lengths" : { }
      },
      "variants" : [ {
        "availability" : [ {
          "channel" : "STORE",
          "key" : "boardwalk",
          "stockNumber" : 5
        } ],
        "custom" : { },
        "depth" : {
          "amount" : 25.0,
          "unit" : "cm"
        },
        "height" : {
          "amount" : 25.0,
          "unit" : "cm"
        },
        "inStock" : true,
        "key" : "1000-101_RED",
        "label" : "XL",
        "length" : {
          "amount" : 25.0,
          "unit" : "cm"
        },
        "link" : "women/pants/khaki/101-v3-red",
        "listPrice" : 15.0,
        "prices" : [ {
          "id" : "VIP_EUR",
          "listPrice" : 12.99,
          "sellingPrice" : 9.99
        } ],
        "sellingPrice" : 24.0,
        "stockNumber" : 5,
        "ticket" : "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7",
        "typedCustom" : {
          "lengths" : { }
        },
        "volume" : {
          "amount" : 25.0,
          "unit" : "cm"
        },
        "weight" : {
          "amount" : 25.0,
          "unit" : "cm"
        },
        "width" : {
          "amount" : 25.0,
          "unit" : "cm"
        }
      } ],
      "volume" : {
        "amount" : 25.0,
        "unit" : "cm"
      },
      "weight" : {
        "amount" : 25.0,
        "unit" : "cm"
      },
      "width" : {
        "amount" : 25.0,
        "unit" : "cm"
      }
    } ],
    "remaining" : 2
  } ],
  "recentSearches" : [ {
    "q" : "Jeans"
  } ],
  "recentlyViewed" : [ {
    "key" : "PRODGROUP060194",
    "products" : [ {
      "badges" : {
        "primary" : [ {
          "attribute" : "is_new",
          "label" : "Latest!",
          "theme" : "NEW"
        } ],
        "secondary" : [ {
          "attribute" : "is_new",
          "label" : "Latest!",
          "theme" : "NEW"
        } ]
      },
      "brand" : "Versace",
      "custom" : { },
      "depth" : {
        "amount" : 25.0,
        "unit" : "cm"
      },
      "description" : "Super elastic fit.",
      "height" : {
        "amount" : 25.0,
        "unit" : "cm"
      },
      "imageInfo" : {
        "effect" : "NONE",
        "images" : [ {
          "alt" : "A woman wearing a white t-shirt",
          "caption" : "The model is 176 cm tall and is wearing size S",
          "custom" : { },
          "sources" : [ {
            "url" : "https://cdn.example.com/img/j12_prod.jpg",
            "height" : 820,
            "width" : 420
          } ]
        } ],
        "thumbnail" : "https://cdn.example.com/thumbs/j12_prod.jpg"
      },
      "inStock" : true,
      "key" : "p1000-101",
      "length" : {
        "amount" : 25.0,
        "unit" : "cm"
      },
      "link" : "men/jeans/country-fit-cowboy-jeans",
      "listPrice" : {
        "max" : 4500.0,
        "min" : 190.5
      },
      "name" : "Romeo",
      "rating" : 4.5,
      "sellingPrice" : {
        "max" : 4500.0,
        "min" : 190.5
      },
      "series" : "Billy",
      "swatch" : {
        "colors" : [ "#FF0000" ],
        "type" : "COLORS"
      },
      "ticket" : "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7",
      "title" : "Country Fit Cowboy Jeans",
      "typedCustom" : {
        "lengths" : { }
      },
      "variants" : [ {
        "availability" : [ {
          "channel" : "STORE",
          "key" : "boardwalk",
          "stockNumber" : 5
        } ],
        "custom" : { },
        "depth" : {
          "amount" : 25.0,
          "unit" : "cm"
        },
        "height" : {
          "amount" : 25.0,
          "unit" : "cm"
        },
        "inStock" : true,
        "key" : "1000-101_RED",
        "label" : "XL",
        "length" : {
          "amount" : 25.0,
          "unit" : "cm"
        },
        "link" : "women/pants/khaki/101-v3-red",
        "listPrice" : 15.0,
        "prices" : [ {
          "id" : "VIP_EUR",
          "listPrice" : 12.99,
          "sellingPrice" : 9.99
        } ],
        "sellingPrice" : 24.0,
        "stockNumber" : 5,
        "ticket" : "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7",
        "typedCustom" : {
          "lengths" : { }
        },
        "volume" : {
          "amount" : 25.0,
          "unit" : "cm"
        },
        "weight" : {
          "amount" : 25.0,
          "unit" : "cm"
        },
        "width" : {
          "amount" : 25.0,
          "unit" : "cm"
        }
      } ],
      "volume" : {
        "amount" : 25.0,
        "unit" : "cm"
      },
      "weight" : {
        "amount" : 25.0,
        "unit" : "cm"
      },
      "width" : {
        "amount" : 25.0,
        "unit" : "cm"
      }
    } ],
    "remaining" : 2
  } ],
  "redirectLink" : "/levis-jeans",
  "totalHits" : 0
}
Schema

AutocompleteResult

The result object from a successful call to the autocomplete.

Name Type Description Example
contentLists ContentList[] A list of lists of requested content that matched the query and specified filters in the request body. Empty unless a content list configuration is provided in the request body.
contentSuggestions ContentSuggestion[] A list of ContentSuggestions that matched the query. Will only find content of type link.Replaced by contentLists.
phraseSuggestions PhraseSuggestion[] A list of PhraseSuggestions, that matched the query.
productSuggestions ProductGroupResult[] A list of products matching the search query. Each group contains a main product and its sibling products within its product group. Each group should correspond to one product card.
recentSearches RecentSearch[] A list of RecentSearches by the visitor with the provided customerKey. Recent searches are not filtered based on whether the query returned any products.
recentlyViewed ProductGroupResult[] A list of RecentlyViewed products by the visitor with the provided customerKey.
redirectLink string Redirect directly to a product page. Returned if the visitor should be redirected to a product page instead of search result. "/levis-jeans"
totalHits integer The total number of ProductGroups that matched the query.

POST

Deprecated

This endpoint is part of an API that has been deprecated and its end of life is 2024-04-30. All endpoints in this API version, including this, will be removed. Please upgrade to the latest version before 2024-04-30.

All API changes can be found here:

More information regarding the API versioning strategy can be found here.

Autocomplete is a query used to retrieve search suggestions, product suggestions, and content item suggestions as the visitor types. All suggestions are returned with autocorrect automatically applied as well as supporting highlighting hints, compatible with any corrections. A query can be sent on every key-press, but a debounce on 50 ms is recommended to avoid unnecessary requests while still creating an extremely snappy experience.

Request

Header parameters

Name Description Example
Accept-Encoding Allows responses to be compressed using Gzip. gzip

Query parameters

Name Description Example
customerKey
Required
A key that uniquely identifies the current visitor.Using UUIDs as keys are recommended. 0b05119e-eeb8-418a-bbfb-defa0dde417e
market
Required
The visitor market identifier. Must match the corresponding market identifier in the data feed. UK
sessionKey
Required
A unique key, identifying the session.Using UUIDs as keys are recommended. 0b05119e-eeb8-418a-bbfb-defa0dde417e
touchpoint
Required
The visitor's touchpoint. Supported values: DESKTOP, MOBILE. DESKTOP
channels Which channels to use. Valid values are ONLINE and STORE. Multiple values are provided with a pipe, |, as a separator. channels will default to ONLINE|STORE if nothing is provided. If STORE is explicitly provided then stores cannot be empty. Supported values: ONLINE, STORE. ONLINE|STORE
notify A boolean that can be used to disable notifications and behavioural registration for the query. false
presentCustom A pipe-separated list of custom product attributes to include in all listings. season|manufacturer
presentPrices A pipe-separated list of custom price ids to include in all listings. Each id must match a supplied custom price id in the data feed. VIP|member
priceId A custom price identifier. Must match supplied custom price identifiers in the data feed. VIP
q The visitor search query. blu
stores Which stores to use. Will impact which stock is displayed and which stock is used for filtering/ranking together with channel. Multiple values are provided with a pipe, |, as a separator. Each store must match a supplied store key in the data feed. 240|100
viewId A parameter that is used to show the page in either production or preview mode. Can be production or preview. Defaults to production if omitted in the query. For more information, see App Integration. Supported values: PRODUCTION, PREVIEW. production

Supported Content-Type

  • application/json;charset=utf-8
  • text/plain;charset=utf-8

Request body

Example
application/json;charset=utf-8
{
  "contentLists" : [ {
    "contentFilter" : {
      "map" : { }
    },
    "id" : "CDP-2",
    "limit" : 8
  } ],
  "productRules" : "rule incl product_key { \"ABC123\" \"DEF456\" \"GHJ789\" } rule incl custom.material { \"leather\" } excl price [ -infinity, 100 ] rule incl newness 10d rule incl brand { \"Birkenstock\" } excl custom.isActive { \"false\" } "
}
Schema

AutocompleteRequestSettings

The autocomplete request configuration.

Name Type Description Example
contentLists ContentListSettingsSearch[] Content to search in.
productFilter
Deprecated
ProductFilter
productRules string A logical expression used by Voyado Elevate 4 to restrict the data set to a Product Selection. The rules can go from easy, such as to only include a product by its key or items that are in stock, to more complex expressions with multiple attributes for products at the same time. If no rules are provided, the entire data set will be used. Please note that when used in Landing Pages, the "Handpicked" rule must be the first rule, and must contain a set of product keys as its only condition. At most 100 product keys can be handpicked in a single request, and at most 200 attribute values can be supplied for each attribute. "rule incl product_key { "ABC123" "DEF456" "GHJ789" } rule incl custom.material { "leather" } excl price [ -infinity, 100 ] rule incl newness 10d rule incl brand { "Birkenstock" } excl custom.isActive { "false" } "
curl -i \
-X POST \
-H 'Accept-Encoding: gzip' \
-H 'Content-Type: application/json;charset=utf-8' \
"https://{cluster-id}.api.esales.apptus.cloud/api/v2/queries/autocomplete?customerKey=0b05119e-eeb8-418a-bbfb-defa0dde417e&market=UK&sessionKey=0b05119e-eeb8-418a-bbfb-defa0dde417e&touchpoint=DESKTOP&channels=ONLINE%7CSTORE&notify=false&presentCustom=season%7Cmanufacturer&presentPrices=VIP%7Cmember&priceId=VIP&q=blu&stores=240%7C100&viewId=production" \
-T request-body.file

Response

Response codes

Status Description
200 Query accepted, content flattened and serialised to JSON.
400 Invalid or missing required arguments.
404 Endpoint is not valid.
503 Service unavailable, no products found in the cluster.
500 Server error such as cluster unavailable or busy. The response body may contain more information about the error.

Response headers

Name Type Description Example
X-Response-Time Response time in milliseconds (ms) 65

Response body

Example
application/json;charset=utf-8
{
  "contentLists" : [ {
    "id" : "content-hits",
    "items" : [ {
      "custom" : {
        "tags" : [ {
          "id" : "78",
          "label" : "Guide"
        }, {
          "id" : "223",
          "label" : "Jeans"
        } ]
      },
      "description" : "To wash or not to wash? And how?! Those are questions jeans shoppers are asking.",
      "image" : {
        "alt" : "A woman wearing a white t-shirt",
        "caption" : "The model is 176 cm tall and is wearing size S",
        "custom" : { },
        "sources" : [ {
          "url" : "https://cdn.example.com/img/j12_prod.jpg",
          "height" : 820,
          "width" : 420
        } ]
      },
      "key" : "wash_care",
      "link" : "/wash-guide",
      "releaseDate" : "2021-10-01T00:00:00Z",
      "ticket" : "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7",
      "title" : "How to wash jeans",
      "type" : "article"
    } ],
    "totalHits" : 10
  } ],
  "phraseSuggestions" : [ {
    "highlighted" : "{jea}ns",
    "q" : "Jeans"
  } ],
  "productSuggestions" : [ {
    "key" : "PRODGROUP060194",
    "products" : [ {
      "badges" : {
        "primary" : [ {
          "attribute" : "is_new",
          "label" : "Latest!",
          "theme" : "NEW"
        } ],
        "secondary" : [ {
          "attribute" : "is_new",
          "label" : "Latest!",
          "theme" : "NEW"
        } ]
      },
      "brand" : "Versace",
      "custom" : { },
      "depth" : {
        "amount" : 25.0,
        "unit" : "cm"
      },
      "description" : "Super elastic fit.",
      "height" : {
        "amount" : 25.0,
        "unit" : "cm"
      },
      "imageInfo" : {
        "effect" : "NONE",
        "images" : [ {
          "alt" : "A woman wearing a white t-shirt",
          "caption" : "The model is 176 cm tall and is wearing size S",
          "custom" : { },
          "sources" : [ {
            "url" : "https://cdn.example.com/img/j12_prod.jpg",
            "height" : 820,
            "width" : 420
          } ]
        } ],
        "thumbnail" : "https://cdn.example.com/thumbs/j12_prod.jpg"
      },
      "inStock" : true,
      "key" : "p1000-101",
      "length" : {
        "amount" : 25.0,
        "unit" : "cm"
      },
      "link" : "men/jeans/country-fit-cowboy-jeans",
      "listPrice" : {
        "max" : 4500.0,
        "min" : 190.5
      },
      "name" : "Romeo",
      "rating" : 4.5,
      "sellingPrice" : {
        "max" : 4500.0,
        "min" : 190.5
      },
      "series" : "Billy",
      "swatch" : {
        "colors" : [ "#FF0000" ],
        "type" : "COLORS"
      },
      "ticket" : "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7",
      "title" : "Country Fit Cowboy Jeans",
      "typedCustom" : {
        "lengths" : { }
      },
      "variants" : [ {
        "availability" : [ {
          "channel" : "STORE",
          "key" : "boardwalk",
          "stockNumber" : 5
        } ],
        "custom" : { },
        "depth" : {
          "amount" : 25.0,
          "unit" : "cm"
        },
        "height" : {
          "amount" : 25.0,
          "unit" : "cm"
        },
        "inStock" : true,
        "key" : "1000-101_RED",
        "label" : "XL",
        "length" : {
          "amount" : 25.0,
          "unit" : "cm"
        },
        "link" : "women/pants/khaki/101-v3-red",
        "listPrice" : 15.0,
        "prices" : [ {
          "id" : "VIP_EUR",
          "listPrice" : 12.99,
          "sellingPrice" : 9.99
        } ],
        "sellingPrice" : 24.0,
        "stockNumber" : 5,
        "ticket" : "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7",
        "typedCustom" : {
          "lengths" : { }
        },
        "volume" : {
          "amount" : 25.0,
          "unit" : "cm"
        },
        "weight" : {
          "amount" : 25.0,
          "unit" : "cm"
        },
        "width" : {
          "amount" : 25.0,
          "unit" : "cm"
        }
      } ],
      "volume" : {
        "amount" : 25.0,
        "unit" : "cm"
      },
      "weight" : {
        "amount" : 25.0,
        "unit" : "cm"
      },
      "width" : {
        "amount" : 25.0,
        "unit" : "cm"
      }
    } ],
    "remaining" : 2
  } ],
  "recentSearches" : [ {
    "q" : "Jeans"
  } ],
  "recentlyViewed" : [ {
    "key" : "PRODGROUP060194",
    "products" : [ {
      "badges" : {
        "primary" : [ {
          "attribute" : "is_new",
          "label" : "Latest!",
          "theme" : "NEW"
        } ],
        "secondary" : [ {
          "attribute" : "is_new",
          "label" : "Latest!",
          "theme" : "NEW"
        } ]
      },
      "brand" : "Versace",
      "custom" : { },
      "depth" : {
        "amount" : 25.0,
        "unit" : "cm"
      },
      "description" : "Super elastic fit.",
      "height" : {
        "amount" : 25.0,
        "unit" : "cm"
      },
      "imageInfo" : {
        "effect" : "NONE",
        "images" : [ {
          "alt" : "A woman wearing a white t-shirt",
          "caption" : "The model is 176 cm tall and is wearing size S",
          "custom" : { },
          "sources" : [ {
            "url" : "https://cdn.example.com/img/j12_prod.jpg",
            "height" : 820,
            "width" : 420
          } ]
        } ],
        "thumbnail" : "https://cdn.example.com/thumbs/j12_prod.jpg"
      },
      "inStock" : true,
      "key" : "p1000-101",
      "length" : {
        "amount" : 25.0,
        "unit" : "cm"
      },
      "link" : "men/jeans/country-fit-cowboy-jeans",
      "listPrice" : {
        "max" : 4500.0,
        "min" : 190.5
      },
      "name" : "Romeo",
      "rating" : 4.5,
      "sellingPrice" : {
        "max" : 4500.0,
        "min" : 190.5
      },
      "series" : "Billy",
      "swatch" : {
        "colors" : [ "#FF0000" ],
        "type" : "COLORS"
      },
      "ticket" : "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7",
      "title" : "Country Fit Cowboy Jeans",
      "typedCustom" : {
        "lengths" : { }
      },
      "variants" : [ {
        "availability" : [ {
          "channel" : "STORE",
          "key" : "boardwalk",
          "stockNumber" : 5
        } ],
        "custom" : { },
        "depth" : {
          "amount" : 25.0,
          "unit" : "cm"
        },
        "height" : {
          "amount" : 25.0,
          "unit" : "cm"
        },
        "inStock" : true,
        "key" : "1000-101_RED",
        "label" : "XL",
        "length" : {
          "amount" : 25.0,
          "unit" : "cm"
        },
        "link" : "women/pants/khaki/101-v3-red",
        "listPrice" : 15.0,
        "prices" : [ {
          "id" : "VIP_EUR",
          "listPrice" : 12.99,
          "sellingPrice" : 9.99
        } ],
        "sellingPrice" : 24.0,
        "stockNumber" : 5,
        "ticket" : "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7",
        "typedCustom" : {
          "lengths" : { }
        },
        "volume" : {
          "amount" : 25.0,
          "unit" : "cm"
        },
        "weight" : {
          "amount" : 25.0,
          "unit" : "cm"
        },
        "width" : {
          "amount" : 25.0,
          "unit" : "cm"
        }
      } ],
      "volume" : {
        "amount" : 25.0,
        "unit" : "cm"
      },
      "weight" : {
        "amount" : 25.0,
        "unit" : "cm"
      },
      "width" : {
        "amount" : 25.0,
        "unit" : "cm"
      }
    } ],
    "remaining" : 2
  } ],
  "redirectLink" : "/levis-jeans",
  "totalHits" : 0
}
Schema

AutocompleteResult

The result object from a successful call to the autocomplete.

Name Type Description Example
contentLists ContentList[] A list of lists of requested content that matched the query and specified filters in the request body. Empty unless a content list configuration is provided in the request body.
contentSuggestions ContentSuggestion[] A list of ContentSuggestions that matched the query. Will only find content of type link.Replaced by contentLists.
phraseSuggestions PhraseSuggestion[] A list of PhraseSuggestions, that matched the query.
productSuggestions ProductGroupResult[] A list of products matching the search query. Each group contains a main product and its sibling products within its product group. Each group should correspond to one product card.
recentSearches RecentSearch[] A list of RecentSearches by the visitor with the provided customerKey. Recent searches are not filtered based on whether the query returned any products.
recentlyViewed ProductGroupResult[] A list of RecentlyViewed products by the visitor with the provided customerKey.
redirectLink string Redirect directly to a product page. Returned if the visitor should be redirected to a product page instead of search result. "/levis-jeans"
totalHits integer The total number of ProductGroups that matched the query.

Schemas

Inner schemas

Badges

Name Type Description Example
primary ProductBadge[]
secondary ProductBadge[]

ContentItem

Object representation of the content item.

Name Type Description Example
custom <string, CustomAttributeResult[]> Custom attributes of the content item, represented as key-value pairs. {"tags":[{"id":"78","label":"Guide"},{"id":"223","label":"Jeans"}]}
description string Description of the content item. Undefined if omitted during import. "To wash or not to wash? And how?! Those are questions jeans shoppers are asking."
image Image Image information. Undefined if omitted during import.
key string Content identifier "wash_care"
link string Link to the page representing this content item. "/wash-guide"
releaseDate string Release date of the content item. Undefined if omitted during import. "2021-10-01T00:00:00Z"
ticket string Used in notification calls to register visitor interaction. "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7"
title string Title of the content item. "How to wash jeans"
type string Type of the content item. "article"

ContentList

The object representation of the content list. Content lists are supported by the Search-page, autocomplete and landing-page. To include content lists in a page response, the request body must include a content list configuration.

Name Type Description Example
id string List identifier. "content-hits"
items ContentItem[] The content items.
totalHits integer The total number of content that matches the filter and query if applicable. 10

ContentListSettingsSearch

The content list request configuration.

Name Type Description Example
contentFilter JsonContentFilter {"custom.designer":"Langdon","type":"article","custom.season":["Winter","Spring"]}
id string An identifier for the content listing area. Multiple pages using the same template can share identifiers, but one identifier may not appear twice within a page.Required Type restrictions:Maximum length is 20 characters. Allowed characters are letters, numbers, dashes, and underscores. Min length: 1. Max length: 20. Pattern: ^[A-Za-z0-9_-]*$. "CDP-2"
limit integer The number of content items to list. Default is page-type specific, 5 for search page and 3 for autocomplete. Min: 1. Max: 200. 8

ContentSuggestion

Name Type Description Example
highlightedTitle string The matching content page title with highlight, e.g. {Return}s. When implementing, always highlight the differences from the input. "{PDP}"
link string A link to the content page. "men/jeans"
ticket string The ticket is a unique string for an object generated by Elevate. "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7"
title string The title of the content page matching the query. "PDP-1"

CustomAttributeResult

Name Type Description Example
id string Id of the attribute (the actual value). "summer"
label string The label of the attribute (the name attribute in the feed - currently not available for content items). "Summer"

Image

The object representation of an image.

Name Type Description Example
alt string Element of image specifying the alt text of an image. The alt text should describe the image. Always returned along with the image. "A woman wearing a white t-shirt"
caption string Element of image specifying the caption for the image, only returned on the product page (or content information for content). "The model is 176 cm tall and is wearing size S"
custom <string, string> Custom attributes of the image.
sources Source[]

ImageInfo

The object representation of image information.

Name Type Description Example
effect string The interaction effects of the product images. Merchandiser option. Defaults to NONE if there are fewer than two valid images for that product. Supported values: NONE, SWAP, GALLERY. "NONE"
images Image[] The product images to display.
thumbnail string The url of the thumbnail for the product. Undefined if images is empty. "https://cdn.example.com/thumbs/j12_prod.jpg"

JsonContentFilter

Name Type Description Example
map <string, JsonFacetSelection>

JsonFacetSelection

Name Type Description Example

MeasurementResult

Name Type Description Example
amount number The amount of the measurement as provided in the import. 25
unit string The unit of the measurement as provided in the import. "cm"

PhraseSuggestion

Name Type Description Example
highlighted string Matching phrase with highlight, e.g. {jea}ns. When implementing, always highlight the differences from the input. "{jea}ns"
q string Matching phrase, to be used as the query for search when clicked on by the visitor. "Jeans"

Price

Name Type Description Example
max number 4500.0
min number 190.5

PriceResult

Name Type Description Example
id string The id identifying the custom price. "VIP_EUR"
listPrice number The price displayed in the shop as the standard price. 12.99
sellingPrice number The price that the customer pays. 9.99

ProductBadge

Name Type Description Example
attribute string The attribute in the data feed that the badge is based on. "is_new"
label string The presentation text of the badge. "Latest!"
theme string The type of badge style used. Supported values: NONE, SALE, DISCOUNT, NEW, THEME_1, THEME_2, THEME_3. "NEW"

ProductFilter

Deprecated

This feature will most likely be removed in new versions.

A product filter restricting which products that the listing may contain. Supports single values, lists, and (for numerical attributes) ranges. Listing multiple attributes to filter on will restrict the products to all conditions (logical AND). When listing values within one attribute, products with any of the listed properties apply (logical OR). In addition to built-in attributes, it is also possible to filter on custom facets, through prefixing the attribute to be filtered with custom., for example "custom.season": ["Winter", "Spring"]. At most 200 attribute values can be supplied per attribute and at most 100 product keys can be picked at once.

Name Type Description Example
price
Deprecated
RangeAttribute An example parameter of a range attribute.

ProductGroupResult

The object representation of the product group result.

Name Type Description Example
key string Product group identifier. "PRODGROUP060194"
products ProductResult[] Products in the Product group. The first element corresponds to the main product. The remaining elements are the other products in the group, to be shown as thumbnails or color swatches, etc.
remaining integer The number of products within this group not included in the response. E.g. if Elevate has been set to include the first five products in the response and this group has seven, there will be two remaining. 2

ProductResult

The object representation of a product.

Name Type Description Example
badges Badges Product badges, split per area.
brand string Brand of the product. "Versace"
custom <string, CustomAttributeResult[]> Custom attributes of the product. Only available on the product-page productGroup and when using the query parameter 'presentCustom'.
depth MeasurementResult Depth of the product. Undefined if omitted during import.
description string Description of the product. Undefined if omitted during import. "Super elastic fit."
height MeasurementResult Height of the product. Undefined if omitted during import.
imageInfo ImageInfo Product image information.
inStock boolean True if any variant is in stock. true
key string Product identifier. "p1000-101"
length MeasurementResult Length of the product. Undefined if omitted during import.
link string Link to the product page. "men/jeans/country-fit-cowboy-jeans"
listPrice Price Min and max price
name string Name of the product. "Romeo"
rating number Current rating value. Undefined when ratings are disabled. 4.5
sellingPrice Price Min and max price
series string Series that this product belongs to. "Billy"
swatch Swatch Swatch information.
ticket string The ticket is a unique string for an object generated by eSales. "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7"
title string Title of the product. "Country Fit Cowboy Jeans"
typedCustom TypedCustomResult Typed custom attributes of the product. Only available on the product-page productGroup and when using the query parameter 'presentCustom'.
variants VariantResult[] List of variants. Empty if all variants are out of stock and the setting Display out of stock sizes in product card is disabled.
volume MeasurementResult Volume of the product. Undefined if omitted during import.
weight MeasurementResult Weight of the product. Undefined if omitted during import.
width MeasurementResult Width of the product. Undefined if omitted during import.

RangeAttribute

Deprecated

This feature will most likely be removed in new versions.

A min and max range value object for a specific attribute.

Name Type Description Example
max integer Defaults to the maximum eligible value if omitted. 1000
min integer Defaults to 0 if omitted. 0

RecentSearch

Name Type Description Example
q string Recent search phrase, to be used as the query for search when clicked on by the visitor. "Jeans"

Source

Name Type Description Example
url
Required
string The URL of the image source. "https://cdn.example.com/img/j12_prod.jpg"
height integer The height of the image. Undefined if height was not specified. 820
width integer The width of the image. Undefined if width was not specified and hasn't yet been assessed by the image service. 420

Swatch

Swatch information is used to generate swatches for different products. The type COLORS is the most common returned type and is accompanied by the actual colours as CSS colour codes. Special colour properties, supported in the data feed such as GOLD, SILVER, or MULTI are other possible return types. These are to be used to generate swatches matching these specific properties.

Name Type Description Example
colors string[] An array with 1 - 3 CSS colour codes for SwatchType COLORS. Empty for other types. "#FF0000"
type string Type of colour swatch for the product. Supported values: MISSING_COLORS, COLORS, SILVER, GOLD, MULTI. "COLORS"

TypedCustomResult

Name Type Description Example
lengths <string, MeasurementResult> Custom lengths of the product matching length attributes requested by the query parameter 'presentCustom'.

VariantAvailabilityInfo

Represents availability in one store or online.

Name Type Description Example
channel string The channel either STORE or ONLINE. "STORE"
key string The key identifying the store. Null if channel = ONLINE. "boardwalk"
stockNumber integer The number of items of this variant in stock in this channel/key. 5

VariantResult

The object representation of a variant.

Name Type Description Example
availability VariantAvailabilityInfo[] List of availability information. Contains an entry for the online channel and one for each relevant store.
custom <string, CustomAttributeResult[]> Custom attributes of the variant. Only available on the product-page productGroup and when using the query parameter 'presentCustom'.
depth MeasurementResult Depth of the variant. Undefined if omitted during import.
height MeasurementResult Height of the variant. Undefined if omitted during import.
inStock boolean True if the variant is in stock. true
key string Variant identifier. "1000-101_RED"
label string The label of the variant. Defaults to size if undefined. Undefined if neither label or size is specified in the import. "XL"
length MeasurementResult Length of the variant. Undefined if omitted during import.
link string Link to product page with variant selected. "women/pants/khaki/101-v3-red"
listPrice number List price of the variant. 15.0
prices PriceResult[] Additional prices for presentation. Only available on the product-page productGroup and when using the query parameter 'presentPrices'.
sellingPrice number Selling price of the variant. 24.0
size string A representative size of the variant. Overridden by label if provided. Deprecated, use label instead, "XL"
stockNumber integer The amount of this variant that is in stock. 5
ticket string Unique ticket for the eSales object. "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7"
typedCustom TypedCustomResult Typed custom attributes of the variant. Only available on the product-page productGroup and when using the query parameter 'presentCustom' requesting typed custom attributes.
volume MeasurementResult Volume of the variant. Undefined if omitted during import.
weight MeasurementResult Weight of the variant. Undefined if omitted during import.
width MeasurementResult Width of the variant. Undefined if omitted during import.
×
Copyright

This online publication is intellectual property of Voyado Lund AB. Its contents can be duplicated in part or whole, provided that a copyright label is visibly located on each copy and the copy is used in conjunction with the product described within this document.

All information found in these documents has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Voyado Lund AB nor the authors shall be held liable for possible errors or the consequences thereof.

Software and hardware descriptions cited in these documents might be registered trademarks. All trade names are subject to copyright restrictions and may be registered trademarks. Voyado Lund AB essentially adheres to the manufacturer’s spelling. Names of products and trademarks appearing in this document, with or without specific notation, are likewise subject to trademark and trade protection laws and may thus fall under copyright restrictions.

CLOSE