> ## 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.
# Sponsored Page
> This endpoint can be called to get sponsored recommendation lists, similar to those returned in the landing page response.
## GET
This endpoint can be called to get sponsored recommendation lists, similar to those returned in the landing page response. Because sponsored lists use real-time bidding, calling this endpoint can be relatively slow, which is why this endpoint is separate from the landing page endpoint.
If not enough products fulfill the requirements, fewer or no lists may be returned. No lists will be returned if the request is set to non-notifying as no bidding will be performed.
Note that the contents of the response object depends on which template is used, if any.
```http theme={null}
GET https://{cluster-id}.elevate-api.cloud/api/storefront/v3/queries/sponsored-page
```
### Request
| Name | Description | Example |
| ----------------- | --------------------------------------------- | ------- |
| `Accept-Encoding` | Allows responses to be compressed using Gzip. | `gzip` |
| Name | Description | Example |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- |
| `customerKey`\* | A key that uniquely identifies the current visitor.
Using UUIDs as keys are recommended.
This field is **required** unless `userContext` is set to `ANONYMOUS` or `UNPERSONALIZED` in which case it is not allowed.
If `userContext` is set to `SYNTHETIC` this is optional. | `0b05119e-eeb8-418a-bbfb-defa0dde417e` |
| `locale`\* | The visitor locale. Must match an available locale identifier on the current market in the data feed. | `en-GB` |
| `market`\* | The visitor market identifier. Must match the corresponding market identifier in the data feed. | `UK` |
| `pageReference`\* | A reference to the page, either Page ID or the localized path, uniquely identifying this page. For more information about page references, see Page IDs. | `/women/shoes/loafers` |
| `sessionKey`\* | A unique key, identifying the session.
Using UUIDs as keys are recommended.
This field is **required** unless `userContext` is set to `ANONYMOUS` in which case it is not allowed.
If `userContext` is set to `SYNTHETIC` this is optional. | `0b05119e-eeb8-418a-bbfb-defa0dde417e` |
| `touchpoint`\* | 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` |
| `f.[id]` | An example parameter of a value or checkbox attribute. Value attributes can be a `\|` pipe-separated list of strings, while a checkbox attributes only can be true or false. Detailed information is available at Facet selections. | `Bosch\|Dewalt or true/false` |
| `f.[id].max` | An example parameter of a range attribute. | `1000` |
| `f.[id].min` | The applied Facet selection in the search result/primary product listing. Each facet attribute is prefixed with f. | `0` |
| `notify` | A boolean that can be used to disable notifications and behavioural registration for the query. May not be combined with any userContext.
You are recommended to set an appropriate userContext instead. | `false` |
| `presentCustom` | A pipe-separated list of custom attributes or custom typed attributes to include in all listings. Prefix with `variant.` to request custom variant attributes. Prefix with `number.`, `length.` or `json.` to request custom typed attributes | `season\|variant.number.item_count\|variant.weight` |
| `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 that determines which price is used throughout the response. Must match a supplied custom price identifier in the data feed. When set, all product prices (selling price, list price etc.), price filtering, and price-based sorting will use this price instead of the standard prices. | `VIP` |
| `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` |
| `templateId` | The id of a response template to apply to all product lists returned. Templates can be imported via the template API. | `template1` |
| `userContext` | Specifies the level of consent for data tracking. Can also be used to flag requests as synthetic to not contribute to statistics. If omitted, the request will be treated as if PERSONALIZED is used.
See user context for more details.
Supported values: `PERSONALIZED`, `UNPERSONALIZED`, `ANONYMOUS`, `SYNTHETIC`. | `PERSONALIZED` |
| `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` |
| `winner` | Include to force a winning brand. Reporting will fail if the brand never won organically. | |
```bash title="bash" theme={null}
curl -i \
-X GET \
-H 'Accept-Encoding: null' \
"https://{cluster-id}.elevate-api.cloud/api/storefront/v3/queries/sponsored-page?customerKey=customerKey&locale=locale&market=market&pageReference=pageReference&sessionKey=sessionKey&touchpoint=touchpoint&channels=channels&f.%5Bid%5D=f.%5Bid%5D&f.%5Bid%5D.max=f.%5Bid%5D.max&f.%5Bid%5D.min=f.%5Bid%5D.min¬ify=notify&presentCustom=presentCustom&presentPrices=presentPrices&priceId=priceId&stores=stores&templateId=templateId&userContext=userContext&viewId=viewId&winner=winner"
```
### Response
| 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. |
```json theme={null}
{
"banners" : [ {
"height" : 300,
"id" : "BANNER_1",
"images" : [ {
"link" : null,
"ticket" : null,
"url" : null
} ],
"width" : 200
} ],
"sponsoredLists" : [ {
"id" : "PDP-1",
"impressionTicket" : null,
"label" : "The presentation text of the list.",
"productGroups" : [ {
"key" : "PRODGROUP060194",
"products" : [ {
"badges" : {
"primary" : [ {
"attribute" : "is_new",
"label" : "Latest!",
"theme" : null
} ],
"secondary" : [ {
"attribute" : "is_new",
"label" : "Latest!",
"theme" : null
} ]
},
"brand" : "Versace",
"custom" : { },
"depth" : {
"amount" : 25.0,
"unit" : "cm"
},
"description" : "null",
"height" : {
"amount" : 25.0,
"unit" : "cm"
},
"imageInfo" : {
"effect" : null,
"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,
"remainingVariants" : 0,
"sellingPrice" : {
"max" : 4500.0,
"min" : 190.5
},
"series" : "Billy",
"sponsored" : true,
"swatch" : {
"colors" : [ "#FF0000" ],
"type" : null
},
"ticket" : "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7",
"title" : "Country Fit Cowboy Jeans",
"typedCustom" : {
"json" : { },
"lengths" : { },
"numbers" : { }
},
"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" : {
"json" : { },
"lengths" : { },
"numbers" : { }
},
"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
} ],
"showMoreLink" : "https://example.com/prods/jeans/levis",
"visible" : true,
"visualization" : "CAROUSEL",
"winners" : [ null ]
} ]
}
```
#### SponsoredPageResult
The object representation of the landing page result.
| Name | Type | Description |
| -------------- | ------------------------------------------------ | ----------------------------------- |
| banners | [BannerResult](#bannerresult)\[] | Collection of banners for the page. |
| sponsoredLists | [SponsoredProductList](#sponsoredproductlist)\[] | Collection of recommendation lists. |
## POST
The POST endpoint is identical to the GET endpoint.
```http theme={null}
POST https://{cluster-id}.elevate-api.cloud/api/storefront/v3/queries/sponsored-page
```
### Request
| Name | Description | Example |
| ----------------- | --------------------------------------------- | ------- |
| `Accept-Encoding` | Allows responses to be compressed using Gzip. | `gzip` |
| Name | Description | Example |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- |
| `customerKey`\* | A key that uniquely identifies the current visitor.
Using UUIDs as keys are recommended.
This field is **required** unless `userContext` is set to `ANONYMOUS` or `UNPERSONALIZED` in which case it is not allowed.
If `userContext` is set to `SYNTHETIC` this is optional. | `0b05119e-eeb8-418a-bbfb-defa0dde417e` |
| `locale`\* | The visitor locale. Must match an available locale identifier on the current market in the data feed. | `en-GB` |
| `market`\* | The visitor market identifier. Must match the corresponding market identifier in the data feed. | `UK` |
| `pageReference`\* | A reference to the page, either Page ID or the localized path, uniquely identifying this page. For more information about page references, see Page IDs. | `/women/shoes/loafers` |
| `sessionKey`\* | A unique key, identifying the session.
Using UUIDs as keys are recommended.
This field is **required** unless `userContext` is set to `ANONYMOUS` in which case it is not allowed.
If `userContext` is set to `SYNTHETIC` this is optional. | `0b05119e-eeb8-418a-bbfb-defa0dde417e` |
| `touchpoint`\* | 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` |
| `f.[id]` | An example parameter of a value or checkbox attribute. Value attributes can be a `\|` pipe-separated list of strings, while a checkbox attributes only can be true or false. Detailed information is available at Facet selections. | `Bosch\|Dewalt or true/false` |
| `f.[id].max` | An example parameter of a range attribute. | `1000` |
| `f.[id].min` | The applied Facet selection in the search result/primary product listing. Each facet attribute is prefixed with f. | `0` |
| `notify` | A boolean that can be used to disable notifications and behavioural registration for the query. May not be combined with any userContext.
You are recommended to set an appropriate userContext instead. | `false` |
| `presentCustom` | A pipe-separated list of custom attributes or custom typed attributes to include in all listings. Prefix with `variant.` to request custom variant attributes. Prefix with `number.`, `length.` or `json.` to request custom typed attributes | `season\|variant.number.item_count\|variant.weight` |
| `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 that determines which price is used throughout the response. Must match a supplied custom price identifier in the data feed. When set, all product prices (selling price, list price etc.), price filtering, and price-based sorting will use this price instead of the standard prices. | `VIP` |
| `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` |
| `templateId` | The id of a response template to apply to all product lists returned. Templates can be imported via the template API. | `template1` |
| `userContext` | Specifies the level of consent for data tracking. Can also be used to flag requests as synthetic to not contribute to statistics. If omitted, the request will be treated as if PERSONALIZED is used.
See user context for more details.
Supported values: `PERSONALIZED`, `UNPERSONALIZED`, `ANONYMOUS`, `SYNTHETIC`. | `PERSONALIZED` |
| `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` |
| `winner` | Include to force a winning brand. Reporting will fail if the brand never won organically. | |
```json title="application/json;charset=utf-8" theme={null}
{
"catalogEntitlement" : "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\" }"
}
```
#### SponsoredPageRequestSettings
A configuration object representing the request to the sponsored category or landing page endpoint.
| Name | Type | Description |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| catalogEntitlement | string | An optional product rule that may be supplied to further limit which products are returned. Products not matching this filter will be purged from all lists and will be excluded from all returned product groups. Use this with extreme care in the rare case where you wish to hide part of your catalog from specific visitors.
Examples: `"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\" }"` |
```bash title="bash" theme={null}
curl -i \
-X POST \
-H 'Accept-Encoding: null' \
-H 'Content-Type: application/json;charset=utf-8' \
"https://{cluster-id}.elevate-api.cloud/api/storefront/v3/queries/sponsored-page?customerKey=customerKey&locale=locale&market=market&pageReference=pageReference&sessionKey=sessionKey&touchpoint=touchpoint&channels=channels&f.%5Bid%5D=f.%5Bid%5D&f.%5Bid%5D.max=f.%5Bid%5D.max&f.%5Bid%5D.min=f.%5Bid%5D.min¬ify=notify&presentCustom=presentCustom&presentPrices=presentPrices&priceId=priceId&stores=stores&templateId=templateId&userContext=userContext&viewId=viewId&winner=winner" \
-T request-body.file
```
### Response
| Status | Description |
| ------ | ----------------------------------------------------------------------------------------------------------------- |
| `415` | Incorrect headers or the body encoding could not be parsed. The request body is expected to be plain text. |
| `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. |
```json theme={null}
{
"banners" : [ {
"height" : 300,
"id" : "BANNER_1",
"images" : [ {
"link" : null,
"ticket" : null,
"url" : null
} ],
"width" : 200
} ],
"sponsoredLists" : [ {
"id" : "PDP-1",
"impressionTicket" : null,
"label" : "The presentation text of the list.",
"productGroups" : [ {
"key" : "PRODGROUP060194",
"products" : [ {
"badges" : {
"primary" : [ {
"attribute" : "is_new",
"label" : "Latest!",
"theme" : null
} ],
"secondary" : [ {
"attribute" : "is_new",
"label" : "Latest!",
"theme" : null
} ]
},
"brand" : "Versace",
"custom" : { },
"depth" : {
"amount" : 25.0,
"unit" : "cm"
},
"description" : "null",
"height" : {
"amount" : 25.0,
"unit" : "cm"
},
"imageInfo" : {
"effect" : null,
"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,
"remainingVariants" : 0,
"sellingPrice" : {
"max" : 4500.0,
"min" : 190.5
},
"series" : "Billy",
"sponsored" : true,
"swatch" : {
"colors" : [ "#FF0000" ],
"type" : null
},
"ticket" : "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7",
"title" : "Country Fit Cowboy Jeans",
"typedCustom" : {
"json" : { },
"lengths" : { },
"numbers" : { }
},
"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" : {
"json" : { },
"lengths" : { },
"numbers" : { }
},
"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
} ],
"showMoreLink" : "https://example.com/prods/jeans/levis",
"visible" : true,
"visualization" : "CAROUSEL",
"winners" : [ null ]
} ]
}
```
#### SponsoredPageResult
The object representation of the landing page result.
| Name | Type | Description |
| -------------- | ------------------------------------------------ | ----------------------------------- |
| banners | [BannerResult](#bannerresult)\[] | Collection of banners for the page. |
| sponsoredLists | [SponsoredProductList](#sponsoredproductlist)\[] | Collection of recommendation lists. |
## Inner Schemas
### Badges
| Name | Type | Description |
| --------- | -------------------------------- | ---------------------------- |
| primary | [ProductBadge](#productbadge)\[] | Badges in the primary area |
| secondary | [ProductBadge](#productbadge)\[] | Badges in the secondary area |
### BadgeTheme (enum)
| Name | Description |
| -------- | ---------------------------------------------------- |
| NONE | No badge used. |
| SALE | Used when the product is on sale. |
| DISCOUNT | Used when the product has a discounted price. |
| NEW | Used if the product is determined as new by Elevate. |
| THEME\_1 | Custom badge 1. |
| THEME\_2 | Custom badge 2. |
| THEME\_3 | Custom badge 3. |
### BannerImage
| Name | Type | Description |
| ------ | ------ | --------------------------------------------------------- |
| link | string | Redirect to this address when user presses the banner |
| ticket | string | Ticket to use when invoking impression and click tracking |
| url | string | URL of the image |
### BannerResult
| Name | Type | Description |
| ------ | ------------------------------ | --------------------------------------------------------------- |
| height | integer | The height of the banner.
Examples: `300` |
| id | string | The identifier of the banner.
Examples: `"BANNER_1"` |
| images | [BannerImage](#bannerimage)\[] | Images to display within the banner |
| width | integer | The width of the banner.
Examples: `200` |
### CustomAttribute
| Name | Type | Description |
| ----- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| id | string | Id of the attribute (the actual value).
Examples: `"summer"` |
| label | string | The label of the attribute (the name attribute in the feed - currently not available for content items).
Examples: `"Summer"` |
### CustomPrice
| Name | Type | Description |
| ------------ | ------ | ----------------------------------------------------------------------------------- |
| id | string | The id identifying the custom price.
Examples: `"VIP_EUR"` |
| listPrice | number | The price displayed in the shop as the standard price.
Examples: `12.99` |
| sellingPrice | number | The price that the customer pays.
Examples: `9.99` |
### Image
The object representation of an image.
| Name | Type | Description |
| ------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 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.
Examples: `"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).
Examples: `"The model is 176 cm tall and is wearing size S"` |
| custom | \ | Custom attributes of the image. |
| sources | [Source](#source)\[] | All valid image URLs and dimensions. If no images are valid, one arbitrary URL will be selected. |
### ImageEffect (enum)
| Name | Description |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NONE | No image effect should be applied. The images array will contain as most one element. |
| SWAP | The images array will always contain two elements. The images should swap on hover. |
| GALLERY | The images array will always contain more than one element. The images can be used to, for example, present an image gallery where the visitor can alternate between images. |
### ImageInfo
The object representation of image information.
| Name | Type | Description |
| --------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| effect | [ImageEffect](#imageeffect-enum) | 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`. |
| images | [Image](#image)\[] | The product images to display. |
| thumbnail | string | The url of the thumbnail for the product. Undefined if images is empty.
Examples: `"https://cdn.example.com/thumbs/j12_prod.jpg"` |
### Measurement
| Name | Type | Description |
| ------ | ------ | ---------------------------------------------------------------------------------- |
| amount | number | The amount of the measurement as provided in the import.
Examples: `25` |
| unit | string | The unit of the measurement as provided in the import.
Examples: `"cm"` |
### Price
| Name | Type | Description |
| ---- | ------ | ------------------------------ |
| max | number |
Examples: `4500.0` |
| min | number |
Examples: `190.5` |
### ProductBadge
| Name | Type | Description |
| --------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| attribute | string | The attribute in the data feed that the badge is based on.
Examples: `"is_new"` |
| label | string | The presentation text of the badge.
Examples: `"Latest!"` |
| theme | [BadgeTheme](#badgetheme-enum) | The type of badge style used. Supported values: `NONE`, `SALE`, `DISCOUNT`, `NEW`, `THEME_1`, `THEME_2`, `THEME_3`.
Examples: `"NEW"` |
### ProductGroup
The object representation of the product group result.
| Name | Type | Description |
| --------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | string | Product group identifier.
Examples: `"PRODGROUP060194"` |
| products | [Product](#product)\[] | 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.
Examples: `2` |
### Product
The object representation of a product.
| Name | Type | Description |
| ------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| badges | [Badges](#badges) | Product badges, split per area. |
| brand | string | Brand of the product.
Examples: `"Versace"` |
| custom | \ | Custom attributes of the product. Only available on the product-page productGroup and when using the query parameter 'presentCustom'. |
| depth | [Measurement](#measurement) | Depth of the product. Undefined if omitted during import. |
| description | string | Description of the product. Only available on the product-page productGroup, unless specified in a template. Undefined if omitted during import.
Examples: `"null"` |
| height | [Measurement](#measurement) | Height of the product. Undefined if omitted during import. |
| imageInfo | [ImageInfo](#imageinfo) | Product image information. |
| inStock | boolean | True if any variant is in stock.
Examples: `true` |
| key | string | Product identifier.
Examples: `"p1000-101"` |
| length | [Measurement](#measurement) | Length of the product. Undefined if omitted during import. |
| link | string | Link to the product page. Will point to a variant if the visitor has filtered on a specific size.
Examples: `"men/jeans/country-fit-cowboy-jeans"` |
| listPrice | [Price](#price) | Min and max price |
| name | string | Name of the product.
Examples: `"Romeo"` |
| notifyImpression **Deprecated** | boolean | True, if the rendering of the product card should trigger an impression notification.
**For retail media only.**
Examples: `true` |
| rating | number | Current rating value. Undefined when ratings are disabled.
Examples: `4.5` |
| remainingVariants | integer | The number of variants not included in the response. Only included if the number of variants have been limited through a template. Does not include variants hidden for being out of stock. |
| sellingPrice | [Price](#price) | Min and max price |
| series | string | Series that this product belongs to.
Examples: `"Billy"` |
| sponsored | boolean | True if the product is sponsored.
**For retail media only.**
Examples: `true` |
| swatch | [Swatch](#swatch) | Swatch information. |
| ticket | string | The ticket is a unique string for an object generated by Elevate.
Examples: `"Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7"` |
| title | string | Title of the product.
Examples: `"Country Fit Cowboy Jeans"` |
| typedCustom | [TypedCustomAttributes](#typedcustomattributes) | Typed custom attributes of the product. Only available on the product-page productGroup and when using the query parameter 'presentCustom'. |
| variants | [Variant](#variant)\[] | 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 | [Measurement](#measurement) | Volume of the product. Undefined if omitted during import. |
| weight | [Measurement](#measurement) | Weight of the product. Undefined if omitted during import. |
| width | [Measurement](#measurement) | Width of the product. Undefined if omitted during import. |
### Source
| Name | Type | Description |
| ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| url\* | string | The URL of the image source.
Examples: `"https://cdn.example.com/img/j12_prod.jpg"` |
| height | integer | The height of the image. Undefined if height was not specified.
Examples: `820` |
| width | integer | The width of the image. Undefined if width was not specified and hasn't yet been assessed by the image service.
Examples: `420` |
### SponsoredProductList
The object representation of a sponsored product list.
| Name | Type | Description |
| ---------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | string | The identifier of the list.
Examples: `"PDP-1"` |
| impressionTicket | string | A ticket to include in impression notifications when this list is being displayed to the visitor.
**For retail media only.** |
| label | string | The identifier of the list.
Examples: `"The presentation text of the list."` |
| productGroups | [ProductGroup](#productgroup)\[] | Products that match the selected algorithm. Each group contains a main product and its sibling products within its product group. Each group should correspond to one product card. |
| showMoreLink | string | A URL to see a large selection. Undefined if not specified in eSales Apps. Merchandiser option.
Examples: `"https://example.com/prods/jeans/levis"` |
| visible | boolean | Whether the recommendation list is visible or has been hidden in the apps |
| visualization | [Visualization](#visualization-enum) | How the list should be presented. Merchandiser option. Supported values: `CAROUSEL`, `GRID`.
Examples: `"CAROUSEL"` |
| winners | string\[] | The brands that won the bidding for this sponsored list.
**For retail media only.** |
### 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, MULTI or TRANSPARENT are other possible return types. These are to be used to generate swatches matching these specific properties.
| Name | Type | Description |
| ------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| colors | string\[] | An array with 1 - 3 CSS colour codes for SwatchType COLORS. Empty for other types.
Examples: `"#FF0000"` |
| type | [SwatchType](#swatchtype-enum) | Type of colour swatch for the product. Supported values: `MISSING_COLORS`, `COLORS`, `SILVER`, `GOLD`, `MULTI`, `TRANSPARENT`.
Examples: `"COLORS"` |
### SwatchType (enum)
| Name | Description |
| --------------- | ------------------------------------------------------------------------------------------------ |
| MISSING\_COLORS | Used if there is no available color. |
| COLORS | Used if colors have been analysed or provided in the data feed. |
| SILVER | Used if silver properties are found in analysis or SILVER is provided as color in the data feed. |
| GOLD | Used if gold properties are found in analysis or GOLD is provided as color in the data feed. |
| MULTI | Used if MULTI was provided as color in the data feed. |
| TRANSPARENT | Used if TRANSPARENT was provided as color in the data feed. |
### TypedCustomAttributes
| Name | Type | Description |
| ------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| json | \ | Custom json data of the product matching json attributes requested by the query parameter 'presentCustom'. |
| lengths | \ | Custom lengths of the product matching length attributes requested by the query parameter 'presentCustom'. |
| numbers | \ | Custom numbers of the product matching numbers attributes requested by the query parameter 'presentCustom'. |
### VariantAvailabilityInfo
Represents availability in one store or online.
| Name | Type | Description |
| ----------- | ------- | ------------------------------------------------------------------------------------------- |
| channel | string | The channel either STORE or ONLINE.
Examples: `"STORE"` |
| key | string | The key identifying the store. Null if channel = ONLINE.
Examples: `"boardwalk"` |
| stockNumber | integer | The number of items of this variant in stock in this channel/key.
Examples: `5` |
### Variant
The object representation of a variant.
| Name | Type | Description |
| ------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| availability | [VariantAvailabilityInfo](#variantavailabilityinfo)\[] | List of availability information. Contains an entry for the online channel and one for each relevant store. |
| custom | \ | Custom attributes of the variant. Available when specified in the applied template or the query parameter `presentCustom` (always available in product-page productGroup). |
| depth | [Measurement](#measurement) | Depth of the variant. Undefined if omitted during import. |
| height | [Measurement](#measurement) | Height of the variant. Undefined if omitted during import. |
| inStock | boolean | True if the variant is in stock.
Examples: `true` |
| key | string | Variant identifier.
Examples: `"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.
Examples: `"XL"` |
| length | [Measurement](#measurement) | Length of the variant. Undefined if omitted during import. |
| link | string | Link to product page with variant selected.
Examples: `"women/pants/khaki/101-v3-red"` |
| listPrice | number | List price of the variant.
Examples: `15.0` |
| prices | [CustomPrice](#customprice)\[] | 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.
Examples: `24.0` |
| size **Deprecated** | string | A representative size of the variant. Overridden by label if provided. Deprecated, use label instead,
Examples: `"XL"` |
| stockNumber | integer | The amount of this variant that is in stock.
Examples: `5` |
| ticket | string | Unique ticket for the eSales object.
Examples: `"Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7"` |
| typedCustom | [TypedCustomAttributes](#typedcustomattributes) | Typed custom attributes of the variant. Available when specified in the applied template or the query parameter `presentCustom` (always available in product-page productGroup). |
| volume | [Measurement](#measurement) | Volume of the variant. Undefined if omitted during import. |
| weight | [Measurement](#measurement) | Weight of the variant. Undefined if omitted during import. |
| width | [Measurement](#measurement) | Width of the variant. Undefined if omitted during import. |
### Visualization (enum)
| Name | Description |
| -------- | ------------------------------------------- |
| CAROUSEL | The list should be presented as a carousel. |
| GRID | The list should be presented as a grid. |