> ## Documentation Index
> Fetch the complete documentation index at: https://product-discovery.developer.voyado.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Category page imports
> Configuring pages, product rules, and recommendation and content lists for category and landing pages in Voyado Elevate.
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](/elevate/docs/guides/pages-and-navigation/import-export-pages) 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](https://help.elevate.voyado.com/hc/en-gb/articles/27610856510236-Product-selection) in the Elevate app. The product rules are a form of [logical expressions](#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](#product-filters) and Product rules cannot be present in the same page configuration.
### Expressions
An expression may consist of multiple [rules](#rule) where each rule must have at least one [restriction](#restriction). A restriction must include a [condition](#condition), which in turn consists of an [attribute](#attribute) that has a value that is either a list of strings, an interval, an interval with a unit, or a specified [newness](https://help.elevate.voyado.com/hc/en-gb/articles/27609462141596-Additional-features#newness) . The structure of an expression can be visualized as follows:
```handlebars icon="code" theme={null}
"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](https://help.elevate.voyado.com/hc/en-gb/articles/27610856510236-Product-selection) 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:
```handlebars title="include products that are *striped* OR have the product key *1234*" icon="code" theme={null}
"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:
```handlebars title="include products that are both *striped* AND NOT *white*" icon="code" theme={null}
"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:
```handlebars title="include products that are either *red* OR *green*" icon="code" theme={null}
"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](#type-definitions) | The key of the product, as provided in the [catalog import](/elevate/docs/integration/catalog-imports/catalog-imports). The list of keys must not exceed 100 keys. |
| `department` | [list of strings](#type-definitions) | The department value of the product group, as provided in the [catalog import](/elevate/docs/integration/catalog-imports/catalog-imports). |
| `brand` | [list of strings](#type-definitions) | The brand value of the product group, as provided in the [catalog import](/elevate/docs/integration/catalog-imports/catalog-imports). |
| `pattern` | [list of strings](#type-definitions) | The pattern value of the product, as provided in the [catalog import](/elevate/docs/integration/catalog-imports/catalog-imports). |
| `custom.*` | [list of strings](#type-definitions) | 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](#type-definitions) | The selling price of the applicable product variants, as provided in the [catalog import](/elevate/docs/integration/catalog-imports/catalog-imports). |
| `discount` | int [interval](#type-definitions) | 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](/elevate/docs/integration/catalog-imports/catalog-imports). |
| `rating` | double [interval](#type-definitions) | The rating of the product, as provided in the [catalog import](/elevate/docs/integration/catalog-imports/catalog-imports). |
| `stock_number` | int [interval](#type-definitions) | The online stock number of the applicable product variants, as provided in the [catalog import](/elevate/docs/integration/catalog-imports/catalog-imports). |
| `newness` | int [newness](https://help.elevate.voyado.com/hc/en-gb/articles/27609462141596-Additional-features#newness) | The age of the product in days, calculated using the `releaseDate` attribute in the [catalog import](/elevate/docs/integration/catalog-imports/catalog-imports). 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](https://help.elevate.voyado.com/hc/en-gb/articles/27611322098076-FAQ-Pages-settings) will be used. |
| `color` | [list of colors](#type-definitions) | The facet colors to filter by, as provided by automatic analysis of the images and/or overridden colors in the [catalog import](/elevate/docs/integration/catalog-imports/catalog-imports). |
| `categories` | [list of strings](#type-definitions) | The `category` value of the product, as provided in the [catalog import](/elevate/docs/integration/catalog-imports/catalog-imports). |
| `width` | double [measurement](#type-definitions) | The width of the product or variant, as provided in the [catalog import](/elevate/docs/integration/catalog-imports/catalog-imports). |
| `height` | double [measurement](#type-definitions) | The height of the product or variant, as provided in the [catalog import](/elevate/docs/integration/catalog-imports/catalog-imports). |
| `length` | double [measurement](#type-definitions) | The length of the product or variant, as provided in the [catalog import](/elevate/docs/integration/catalog-imports/catalog-imports). |
| `depth` | double [measurement](#type-definitions) | The depth of the product or variant, as provided in the [catalog import](/elevate/docs/integration/catalog-imports/catalog-imports). |
| `volume` | double [measurement](#type-definitions) | The volume of the product or variant, as provided in the [catalog import](/elevate/docs/integration/catalog-imports/catalog-imports). |
| `weight` | double [measurement](#type-definitions) | The weight of the product or variant, as provided in the [catalog import](/elevate/docs/integration/catalog-imports/catalog-imports). |
#### 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](/elevate/docs/api/admin/v4/import/catalog#length), [volume](/elevate/docs/api/admin/v4/import/catalog#volume), and [weight](/elevate/docs/api/admin/v4/import/catalog#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`.
```handlebars icon="code" theme={null}
rule incl product_key { "p1234" "p5678" }
```
Include only products with the pattern `striped` with default newness.
```handlebars icon="code" theme={null}
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`.
```handlebars icon="code" theme={null}
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).
```handlebars icon="code" theme={null}
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.
```handlebars icon="code" theme={null}
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.
```handlebars icon="code" theme={null}
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).
```handlebars icon="code" theme={null}
rule incl custom.number.items_in_package [10, infinity]
```
Include all products that match any of the included rules.
```handlebars icon="code" theme={null}
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
The Product filters configuration has been superseded by the [Product rules](#product-rules) configuration. It is recommended to use the [Product rules](#product-rules) configuration for new Voyado Elevate integrations.
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](#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.
```json icon="code" theme={null}
{
"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.
```json icon="code" theme={null}
{
"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](/elevate/docs/integration/catalog-imports/catalog-imports). 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](#supported-value-filter-attributes). |
### Value product filters
Value filters can be provided as single values or as a list of values.
```json icon="code" theme={null}
{
"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](/elevate/docs/integration/catalog-imports/catalog-imports). |
| `department` | string | The department value of the product as provided in the [catalog import](/elevate/docs/integration/catalog-imports/catalog-imports). |
| `brand` | string | The brand value of the product as provided in the [catalog import](/elevate/docs/integration/catalog-imports/catalog-imports). |
| `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](/elevate/docs/integration/catalog-imports/catalog-imports). |
| `isNew` | boolean | Whether the product is considered new, as defined in the settings for [new products](https://help.elevate.voyado.com/hc/en-gb/articles/27611266063132-Settings#default-settings) in the Experience app. By default, `"isNew": true` includes products newer than 7 days. Same as `daysOld`, see [Supported numeric filter attributes](#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.
```json icon="code" theme={null}
{
"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) | 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.
```json icon="code" expandable theme={null}
{
"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](#algorithms) | The algorithm to apply on the recommendation listing. Defaults to `TOP_PRODUCTS`. | `PERSONAL` |
| `params` | [Parameters](#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](#product-rules) | 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](#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](/elevate/docs/integration/site-integration/session-management#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](#parameters). |
| `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](#parameters). |
| `CART` | Returns recommendations based on the provided cart products. Can take `cart` as [parameter](#parameters). |
| `NEWEST_PRODUCTS` | Returns the newest products. |
| `STYLE_WITH` | Returns products defined by the retailer in the [catalog import](/elevate/docs/integration/catalog-imports/catalog-imports) based on a product key. Can take `productKey` as [parameter](#parameters). |
| `FAVORITES` | Returns recommendations based on favorites notified for the current visitor. Requires [visitor identification](/elevate/docs/integration/site-integration/session-management#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](/elevate/docs/integration/site-integration/session-management#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](/elevate/docs/integration/catalog-imports/catalog-imports). 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.
```json icon="code" theme={null}
{
"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.
```json icon="code" theme={null}
{
"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](/elevate/docs/integration/catalog-imports/catalog-imports). |
| `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](/elevate/docs/integration/catalog-imports/catalog-imports). |
## 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.
```json icon="code" expandable theme={null}
{
"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](#content-filters) | An expression restricting the content in the content listing. | `{ "type": "article" }` |
| `algorithm` | [Algorithm](#algorithms-content) | The algorithm to apply on the content listing. The algorithm only works when used on a [category page and landing page](/elevate/docs/api/storefront/v3/queries/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](/elevate/docs/integration/catalog-imports/catalog-imports). Content items with the same release date are internally sorted by `TOP_CONTENT`. |