Skip to main content

Item Variations

In an eCommerce context, items (products) are often offered in several variations, such as different sizes, fits and/or colors. Krestor's item API allows customers to define all the variations available for each item, so that end users can choose to filter on size, fit and/or color.

A single variation is a fully qualified product. For example, if an item comes in 3 sizes and 4 colors, you can upload 12 variations of that item, 1 for each size/color combination. All information that is shared across variations of a single item should be uploaded at the item level. All variation-specific information must be uploaded at the variation level.

Matching​

Variation search and matching works like 'search within search'.

Krestor's search (as well as browse and autocomplete) first identifies all products that match a query (where a query encompasses a search term and zero or more filter selections; or a browse group id and zero or more filter selections).

Next Krestor searches within each item (typically, a product) to identify all matching variations for the query in question.

Finally, Krestor identifies the best matching variation among those that match the query. First the algorithm will look for any variation with is_default set to true, then will search for the best variation match based on NLP, ranking optimizations and variation suggested_score.

Results​

Items are returned one-by-one, with the best matching variation's data presented at the top level for the item in question. Other matching variations are returned in an array on the item in question. During request time it is possible to specify what fields of variation to return and even do some aggregation across all of an item variations by using the variations_map request argument of search, browse and autocomplete endpoints.

Endpoints​

The item and bulk item endpoints can accept up to 100 variations on each product.

While the item update and patch methods allow updating certain fields on an item while leaving others untouched, the variation array must be updated in full when using the REST endpoints. However, the catalog update endpoints allow updating just certain variations.