Skip to content

Page configurations

The content of pages can be modified through supplying a page configuration. The page configuration allows pages to be extended with additional recommendation listings and supports product rules and filtering of primary product listings, such as search results and category pages.

Pages with modified content must be retrieved through POST requests, where the content modification specification is supplied as the body.

Product rules

Product rules, productRules, is a configuration that is equal to the visual way of defining a Product selection in the Elevate Apps. The product rules are a form of logical expressions that are used to restrict the products in a response. Rules can go from easy, such as to only include a single product using its product key or products of a specific brand, to more complex with multiple attributes for the product selection.

Risk of competing product selections

Product filters and Product rules cannot be present in the same page configuration.

Expressions

An expression may consist of multiple rules where each rule must have at least one restriction. A restriction must include a condition, which in turn consist of an attribute that has a value that is either a list of strings, an interval, an interval with a unit, or a specified newness. The structure of an expression can be visualized as follows:

"rule incl product_key { \"p1234\" \"p5678\" }"
 [                   Rule                    ]
      [             Restriction              ]
           [            Condition            ]
           [Attribute]
                       [        Value        ]

Rule

A rule, rule, must have at least one restriction. Rules are separated with a whitespace, i.e. a space, a tab, or a newline. If more than one rule is used, the rules are to be be considered as using the logical OR operator.

When product keys are specified in a rule (equal to Handpicked in the apps), this rule must be the first rule and must contain a set of product keys (one or more) as its only condition.

Restriction

A restriction is either an include, incl, or an exclude, excl, followed by a condition. If more than one restriction is present in a rule, the restrictions can be considered as using the logical AND operator.

Condition

A condition must consist of an attribute followed by a value that is either a list of strings, an interval, an interval with a unit, or a specified newness. If more than one value is present within a list of strings, consider the values to be using the logical OR operator.

Attribute

The following attributes are allowed in conditions.

Attribute Type Description
product_key list of strings The key of the product, as provided in the data feed. The list of keys must not exceed 100 keys.
department list of strings The department value of the product group, as provided in the data feed.
brand list of strings The brand value of the product group, as provided in the data feed.
pattern list of strings The pattern value of the product, as provided in the data feed.
custom.* list of strings A custom attribute, provided in the data feed. Custom attributes on products are prefixed custom., for example, custom.season. Custom attributes on variants are prefixed variant.custom., for example, variant.custom.grip. Typed custom attributes must include the type in the prefix, for example, custom.length. or variant.custom.length., for example, variant.custom.length.diameter. Supported types are length and number. Note that custom attribute values, and not names, must be used in filter rules.
price double interval The selling price of the applicable product variants, as provided in the data feed.
discount int interval The discount percentage of the applicable product variants, based on the difference between the selling price and the list price, as provided in the data feed.
rating double interval The rating of the product, as provided in the data feed.
stock_number int interval The online stock number of the applicable product variants, as provided in the data feed.
newness int newness The age of the product in days, calculated using the release_date attribute in the data feed. Can be default, or any integer value, suffixed by the character d, e.g. 5d for five days. If default is used, the number of days as defined in the Experience app will be used.
color list of colors The facet colors to filter by, as provided by automatic analysis of the images and/or overridden colors in the data feed.
categories list of strings The categories value of the product, as provided in the data feed.
width double measurement The width of the product or variant, as provided in the data feed.
height double measurement The height of the product or variant, as provided in the data feed.
length double measurement The length of the product or variant, as provided in the data feed.
depth double measurement The depth of the product or variant, as provided in the data feed.
volume double measurement The volume of the product or variant, as provided in the data feed.
weight double measurement The weight of the product or variant, as provided in the data feed.

Type definitions

Type Description
List of strings A list of strings. A list of strings is enclosed within curly brackets, { }, with each string enclosed with double quotation marks, ". Strings are separated with a space. Double quotation marks and backslashes within strings are escaped with a prefixed backslash, \.
List of colors A list of colors. A list of colors is enclosed within curly brackets, { }. Colors are separated with a space. Allowed colors are: BLACK, GRAY, WHITE, BEIGE, BROWN, BLUE, DARK_BLUE, PURPLE, PINK, RED, ORANGE, PEACH, YELLOW, LIGHT_GREEN, GREEN, TEAL, TURQUOISE, SILVER, GOLD, and MULTI. Note that colors are considered as constants and should not be enclosed with quotation marks, ".
Interval A closed numeric range, enclosed within square brackets, [ ]. Numbers are separated by a comma, ,. -infinity and infinity are used to specify undefined min and max values.
Measurement An interval followed by a valid unit for the attribute. See length, volume, and weight for allowed units.

Examples

Handpick products p1234 and p5678.

rule incl product_key { "p1234" "p5678" }

Include only products with the pattern striped with default newness.

rule incl pattern { "striped" } incl newness default

Include products from the brands Bosch or Dewalt, but exclude products with a price above 2000.

rule incl brand { "Bosch" "Dewalt" } excl price [ 2000.01, infinity ]

Include products which are up to three days old and have a rating between 2.5 and 4.5.

rule incl newness 3d incl rating [ 2.5, 4.5 ]

Include black and gray products from the categories Kitchen and Dining with a discount that is less than 30%.

rule incl custom.category_name { "Kitchen" "Dining" } incl discount [ 0, 30 ] incl color { BLACK GRAY }

Include products that have a volume between 1 and 2 liters, a diameter (custom on the product) above 10 cm, and a package_height (custom on the variant) that is 2.5 dm.

rule incl volume [ 1, 2 ]l incl custom.length.diameter [10, infinity] cm incl variant.custom.length.package_height [2.5, 2.5]dm

Include products that have more than 10 items in the package ( custom on the product ).

rule incl custom.number.items_in_package [10, infinity]

Include all products that match any of the included rules.

rule incl product_key { "ABC123" "DEF456" "GHJ789" }
rule incl custom.material { "leather" } excl price [ 0.00, 100.00 ]
rule incl newness 10d
rule incl brand { "Birkenstock" } excl custom.isActive { "false" }

Product filters

Deprecated

The Product filters configuration has been superseded by the Product rules configuration. It is recommended to use the Product rules configuration for new Voyado Elevate integrations.

Deprecated information

Product filters can be applied to both primary listings and recommendation listings and are included in the request body for the target listing. Applying a filter will restrict the set of returned products to be included in the actual result set and can be either numeric or value filters.

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).

Risk of competing product selections

Product filters and Product rules cannot be present in the same page configuration.

Request example

The following illustrates an example on applying a filter for a Calvin Klein outlet of products from old seasons.

  • All products will be of the brand Calvin Klein.
  • All products will at least be 1 percent discounted.
  • All products belong to either the Winter or Spring season.
{
    "productFilter": {
        "brand": "Calvin Klein",
        "discount": {"min": 1},
        "custom.season": ["Winter", "Spring"],
    }
}

Numeric product filters

Numeric filters can be provided as a range, single values, or as lists of values. All ranges are inclusive and may be provided with a one sided limitation, where min defaults to 0 and max defaults to the maximum eligible value.

Request example
{
    "price": {"max": 300.0},
    "discount": 70,
    "rating": {"min": 4.0, "max": 5.0},
    "stock_number": [0, 1, 2]
}

Supported numeric filter attributes

Name Type Description
discount int The discount percentage of the product.
price double The selling price of the product.
rating double The rating of the product.
stock_number int The stock number of the variants in the product. Will include applicable variants.
daysOld int The age of the product in days, calculated using the release_date attribute in the data feed. This enables queries to include a max age for displayed products when displaying new products. Must be provided on the form "daysOld": {"max": 7} (value selections and requests providing a min value will be rejected). Related to isNew in Supported value filter attributes.

Value product filters

Value filters can be provided as single values or as a list of values.

Request example
{
    "brand": "Calvin Klein",
    "custom.season": ["Winter", "Spring"],
}

Supported value filter attributes

Name Type Description
pattern string The pattern value of the product as provided in the data feed.
department string The department value of the product as provided in the data feed.
brand string The brand value of the product as provided in the data feed.
custom.* string Any custom attribute can be used as a value filter, through prefixing the attribute to be filtered with custom., for example custom.season.
product_key string The key of the product as provided in the data feed.
isNew boolean Whether the product is considered new, as defined in the settings for New products in the Experience app. By default, "isNew": true includes products newer than 7 days. Same as daysOld, see Supported numeric filter attributes, but based on the app setting instead of a fixed max limit. "isNew": false will not apply any filter.

Primary list

Some page types include primary listings such as search and category pages. Primary lists can be configured with product rules.

Request example
{
    "primaryList": {
        "include": true,
        "productRules": "rule incl brand { \"Bosch\" \"Dewalt\" }"
        }
    }
}
Name Type Description
include boolean Specifies if the primary list should be included or not in the response. Always included in search page requests.
productRules ProductRules Product rules restricting which products that the listing may contain.

Recommendation lists

Most page types support recommendation lists. To include recommendation lists in a page response, the request body must include the recommendation configuration.

Request example
{
  "recommendationLists": [
    {
      "id": "START-PAGE-1",
      "limit": 8,
      "algorithm": "PERSONAL"
    },
    {
      "id": "START-PAGE-2",
      "algorithm": "ALTERNATIVES",
      "params": {
        "productKey": "P1"
      }
    },
    {
      "id": "START-PAGE-3",
      "algorithm": "TOP_PRODUCTS",
      "productRules": "rule incl discount [ 0, 30 ]"
      }
    },
  ]
}
Name Type Description Example
id string An identifier for the recommendation listing area.

Multiple pages using the same template can share identifiers, but one identifier may not appear twice within a page. E.g. all product pages should use the same identifier for their alternative recommendation areas.

Supported characters: a-z, A-Z, 0-9, dash (-), and underscore (_).
Required
PDP-1
algorithm Algorithm The algorithm to apply on the recommendation listing. Defaults to TOP_PRODUCTS. PERSONAL
params Parameters Any parameters required by the applied algorithm.
Conditionally required
{ "productKey": "P1" }
limit int The number of product hits to list. For each product hit in the list, its product group is returned in full to facilitate rendering of color swatches and more. Defaults to 4. 8
productRules ProductRules An expression restricting the products that the recommendation listing may contain. rule incl discount [ 0, 30 ]

Algorithms

All recommendation algorithms will utilize provided product rules, productRules, or product filters, productFilter (deprecated).

Name Description
TOP_PRODUCTS Returns the most relevant product based on set business goals.
PERSONAL Returns personal recommendations based on the interaction history of the current visitor. Backfills using the TOP_PRODUCT algorithm. Requires Visitor identification for cross device personalisation.
ALTERNATIVES Returns alternative products based on a product key. This algorithm is best utilized without product rules/filters.
Can take productKey as parameter.
UPSELL Returns complementary products for up sell, based on a product key. This algorithm is best utilized without product rules/filters.
Can take productKey as parameter.
CART Returns recommendations based on the provided cart products.
Can take cart as parameter.
NEWEST_PRODUCTS Returns the newest products.
STYLE_WITH Returns products defined by the retailer in the data feed based on a product key.
Can take productKey as parameter.
FAVORITES Returns recommendations based on favorites notified for the current visitor. Requires Visitor identification for cross device personalisation.
MORE_FROM_SERIES Returns products from the same series, based on a product key. Can take productKey as parameter.
RECENTLY_VIEWED Returns the most recently clicked products of the current visitor. Requires Visitor identification for cross device personalisation.
ADD_TO_CART_RECS Returns recommendations for a product that has just been added to cart. Requires productKey directly in the request body or indirectly via variantKey query parameter for the add-to-cart-popup endpoint. Strongly recommended to ONLY use for the add-to-cart-popup endpoint.

Algorithms and product rules/filters

The recommendation algorithms ALTERNATIVES and UPSELL are primarily used on product pages. They are best utilized without product rules/filters. Too strict product rules/filters may prevent actual visitor behavior to be properly reflected and thus reduce sales.

Parameters

Name Type Description Example
productKey string The base product for the ALTERNATIVES, STYLE_WITH, UPSELL, MORE_FROM_SERIES, and ADD_TO_CART_RECS recommendation algorithms. Defaults to the provided product key parameter for product-page requests. P1
cart string[] A list of product and/or variant keys depicting the cart content. Must match keys of variants or products in the data feed. Always use the variant key when possible. Defaults to the provided cart parameter for cart-page requests. ["P2", "V2", "V3"]

Content filters

Content filters can be applied to most content listings and are included in the request body for the target listing. Applying a filter will restrict the set of returned content and can only be string value filters e.g. not numeric.

Listing multiple attributes to filter on will restrict the content to all conditions (logical AND). When listing values within one attribute, content with any of the listed properties apply (logical OR).

Request example

The following illustrates an example on applying a filter for content by the author Pelle containing both articles and size-guides.

  • All content will be from the author Pelle.
  • All products will be of either the article or size-guide type.
{
    "contentFilter": {
        "custom.author": "Pelle",
        "type": ["article", "size-guide"]
    }
}

Value content filters

Value filters can be provided as single values or as a list of values.

Request example
{
    "type": "article",
    "custom.season": ["Winter", "Spring"]
}

Supported value filter attributes

Name Type Description
type string The type value of the content item as provided in the data feed.
custom.* string Any custom attribute can be used as a value filter, through prefixing the attribute to be filtered with custom., for example custom.season.
content_key string The key of the content item as provided in the data feed.

Content lists

Search-page, autocomplete and landing-page support content lists. To include content lists in a page response, the request body must include a content list configuration.

Request example
{
    "contentLists": [
        {
            "id": "bottom-right-mini-faq",
            "limit": 8,
            "contentFilter": {
                "type": "faq"
            }
        }
    ]
}
Name Type Description Example
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, dash, and underscore.
CDP-2
limit int The number of content items to list. Defaults is page-type specific.

Type restrictions:
Must be a positive number that is less than 200.
8
contentFilter ContentFilter An expression restricting the content in the content listing. { "type": "article" }
algorithm Algorithm The algorithm to apply on the content listing. The algorithm only works when used on a Category Page and Landing page. Defaults to TOP_CONTENT. NEWEST_CONTENT

Algorithms (Content)

Name Description
TOP_CONTENT Returns the most relevant content, based on clicks.
NEWEST_CONTENT Returns the newest content based on releaseDate of the content items as provided in the data feed. Content items with the same release date are internally sorted by TOP_CONTENT.
×
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