Category page imports

Pages are entities that determine what types of product listings should be included in the response for a given page ID, such as recommendations or facetable product grids. They also include rules that merchandisers can configure, such as pinned products, default sorting, and other merchandising controls. It is possible to work with pages in two ways:

You can import a collection of pages using the import API (see the guide on how to import and export pages) or set them up in the app.
Or you can supply a configuration in the POST body of each landing page query.

We recommend importing pages, as that gives you access to more customization tools and options, such as the Navigation editor, improved facet handling, and Boost by page.

The page identifier, page ID or page reference, is used to identify an existing page configuration. An existing page configuration created via the Admin API or Elevate Application takes precedence over configuration supplied in the POST request body.

Product rules

Product rules is a configuration that is equal to the visual way of defining a product selection in the Elevate app. 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.

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 consists 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 must have at least one restriction. Rules are separated with a whitespace, that is, a space, a tab, or a newline. If more than one rule is used, the rules are to 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. Example:

include products that are *striped* OR have the product key *1234*

"rule incl product_key { "p1234" }"
"rule incl pattern { "striped" }"

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. Example:

include products that are both *striped* AND NOT *white*

"rule incl pattern { "striped" } excl color { WHITE }"

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. Example:

include products that are either *red* OR *green*

"rule incl color { RED GREEN }"

Attribute

Most built-in or custom attributes are allowed in conditions. Here is a list of common ones to use:

Attribute	Type	Description
`product_key`	list of strings	The key of the product, as provided in the catalog import. The list of keys must not exceed 100 keys.
`department`	list of strings	The department value of the product group, as provided in the catalog import.
`brand`	list of strings	The brand value of the product group, as provided in the catalog import.
`pattern`	list of strings	The pattern value of the product, as provided in the catalog import.
`custom.*`	list of strings	A custom attribute, such as `customLabel`, provided in the catalog import. 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 catalog import.
`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 catalog import.
`rating`	double interval	The rating of the product, as provided in the catalog import.
`stock_number`	int interval	The online stock number of the applicable product variants, as provided in the catalog import.
`newness`	int newness	The age of the product in days, calculated using the `releaseDate` attribute in the catalog import. Can be `default`, or any integer value, suffixed by the character `d`, for example `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 catalog import.
`categories`	list of strings	The `category` value of the product, as provided in the catalog import.
`width`	double measurement	The width of the product or variant, as provided in the catalog import.
`height`	double measurement	The height of the product or variant, as provided in the catalog import.
`length`	double measurement	The length of the product or variant, as provided in the catalog import.
`depth`	double measurement	The depth of the product or variant, as provided in the catalog import.
`volume`	double measurement	The volume of the product or variant, as provided in the catalog import.
`weight`	double measurement	The weight of the product or variant, as provided in the catalog import.

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.

Products and variants

Criteria are evaluated at the product level. This means:

If a variant is included in the selection, the entire product it belongs to will be included.
If a product has multiple variants, and at least one variant matches the selection criteria, the product will be included.

To exclude a product, none of its variants can match the selection criteria. Even if one variant of a product is explicitly excluded, the product will still be included as long as at least one other variant is included. A product is excluded when all of its variants are excluded.

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 of 2000.01 or higher, for example prices above 2000.

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

Include products up to 3 days old with a rating between 2.5 and 4.5 (inclusive).

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 30% or less.

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 (inclusive), a diameter (custom on the product) of 10 cm or larger, 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 10 or more 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" }

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

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

The following illustrates an example of 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 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.

{
  "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 `releaseDate` attribute in the catalog import. This enables queries to include a max age for displayed products when displaying new products. Must be provided in 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 filters can be provided as single values or as a list of values.

{
  "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 catalog import.
`department`	string	The department value of the product as provided in the catalog import.
`brand`	string	The brand value of the product as provided in the catalog import.
`custom.*`	string	Any custom attribute can be used as a value filter, by prefixing the attribute to be filtered with `custom.`, for example `custom.season`.
`product_key`	string	The key of the product as provided in the catalog import.
`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.

{
  "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 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.

{
  "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. For example, 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 personalization.
`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 upsell, 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 catalog import 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 personalization.
`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 personalization.
`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 the `variantKey` query parameter for the add-to-cart-popup endpoint. Strongly recommended to only use for the add-to-cart-popup endpoint.

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 from being 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 catalog import. 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, for example 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). The following illustrates an example of 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.

{
  "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 catalog import.
`custom.*`	string	Any custom attribute can be used as a value filter, by 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 catalog import.

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.

{
  "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. Default 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 catalog import. Content items with the same release date are internally sorted by `TOP_CONTENT`.

Overview

Configuration

Catalog imports

Other imports

Site integration

Other integrations

Product rules

Expressions

Rule

Restriction

Condition

Attribute

Type definitions

Products and variants

Examples

Product filters

Numeric product filters

Supported numeric filter attributes

Value product filters

Supported value filter attributes

Primary list

Recommendation lists

Algorithms

Parameters

Content filters

Value content filters

Supported value filter attributes

Content lists

Algorithms (Content)

​Product rules

​Expressions

​Rule

​Restriction

​Condition

​Attribute

​Type definitions

​Products and variants

​Examples

​Product filters

​Numeric product filters

​Supported numeric filter attributes

​Value product filters

​Supported value filter attributes

​Primary list

​Recommendation lists

​Algorithms

​Parameters

​Content filters

​Value content filters

​Supported value filter attributes

​Content lists

​Algorithms (Content)

Product rules

Expressions

Rule

Restriction

Condition

Attribute

Type definitions

Products and variants

Examples

Product filters

Numeric product filters

Supported numeric filter attributes

Value product filters

Supported value filter attributes

Primary list

Recommendation lists

Algorithms

Parameters

Content filters

Value content filters

Supported value filter attributes

Content lists

Algorithms (Content)