Product Page¶
https://{cluster-id}.api.esales.apptus.cloud/api/v2/queries/product-page
POST¶
Deprecated
This endpoint is part of an API that has been deprecated and its end of life is 2024-04-30. All endpoints in this API version, including this, will be removed. Please upgrade to the latest version before 2024-04-30.
All API changes can be found here:
This endpoint will be replaced by product-page.
More information regarding the API versioning strategy can be found here.
The product page query should be used on product pages. The product page by default returns the product on the product page for rendering, but is typically combined with additional product recommendation listings.
Request¶
Header parameters¶
Name | Description | Example |
---|---|---|
Accept-Encoding | Allows responses to be compressed using Gzip. | gzip |
Query parameters¶
Name | Description | Example |
---|---|---|
customerKey Required | A key that uniquely identifies the current visitor.Using UUIDs as keys are recommended. | 0b05119e-eeb8-418a-bbfb-defa0dde417e |
market Required | The visitor market identifier. Must match the corresponding market identifier in the data feed. | UK |
productKey Required | The product key for the current product page. Must match a product key in the data feed. | <PRODUCT_KEY_FROM_YOUR_FEED> |
sessionKey Required | A unique key, identifying the session.Using UUIDs as keys are recommended. | 0b05119e-eeb8-418a-bbfb-defa0dde417e |
touchpoint Required | 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|STORE |
notify | A boolean that can be used to disable notifications and behavioural registration for the query. | false |
presentCustom | A pipe-separated list of custom product attributes to include in all listings. | season|manufacturer |
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. Must match supplied custom price identifiers in the data feed. | 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 |
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 |
Supported Content-Type¶
application/json;charset=utf-8
text/plain;charset=utf-8
Request body¶
Example
{
"productGroup" : {
"include" : true
},
"recommendationLists" : [ {
"id" : "RECS1",
"algorithm" : "CART",
"label" : "Recommended for you",
"limit" : 10,
"params" : {
"cart" : [ "string" ],
"productKey" : "<PRODUCT_KEY_FROM_YOUR_FEED>"
},
"productRules" : "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\" } ",
"showMoreLink" : "string",
"visualization" : "CAROUSEL"
} ]
}
Schema
ProductPageRequestSettings¶
A configuration object for the page request.
Name | Type | Description | Example |
---|---|---|---|
productGroup | ProductGroupSettings | ||
recommendationLists | RecListRequestSettings[] | Min items: 0 . Max items: 10 . |
curl -i \
-X POST \
-H 'Accept-Encoding: gzip' \
-H 'Content-Type: application/json;charset=utf-8' \
"https://{cluster-id}.api.esales.apptus.cloud/api/v2/queries/product-page?customerKey=0b05119e-eeb8-418a-bbfb-defa0dde417e&market=UK&productKey=<PRODUCT_KEY_FROM_YOUR_FEED>&sessionKey=0b05119e-eeb8-418a-bbfb-defa0dde417e&touchpoint=DESKTOP&channels=ONLINE|STORE¬ify=false&presentCustom=season|manufacturer&presentPrices=VIP|member&priceId=VIP&stores=240|100&viewId=production" \
-T request-body.file
Response¶
Response codes¶
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. |
Response headers¶
Name | Type | Description | Example |
---|---|---|---|
X-Response-Time | integer | Response time in milliseconds (ms) | 65 |
Response body¶
Example
{
"productGroup" : {
"key" : "PRODGROUP060194",
"products" : [ {
"badges" : {
"primary" : [ {
"attribute" : "is_new",
"label" : "Latest!",
"theme" : "NEW"
} ],
"secondary" : [ {
"attribute" : "is_new",
"label" : "Latest!",
"theme" : "NEW"
} ]
},
"brand" : "Versace",
"custom" : { },
"depth" : {
"amount" : 25.0,
"unit" : "cm"
},
"description" : "Super elastic fit.",
"height" : {
"amount" : 25.0,
"unit" : "cm"
},
"imageInfo" : {
"effect" : "NONE",
"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,
"sellingPrice" : {
"max" : 4500.0,
"min" : 190.5
},
"series" : "Billy",
"swatch" : {
"colors" : [ "#FF0000" ],
"type" : "COLORS"
},
"ticket" : "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7",
"title" : "Country Fit Cowboy Jeans",
"typedCustom" : {
"lengths" : { }
},
"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" : {
"lengths" : { }
},
"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
},
"recommendationLists" : [ {
"id" : "PDP-1",
"label" : "The presentation text of the list.",
"productGroups" : [ {
"key" : "PRODGROUP060194",
"products" : [ {
"badges" : {
"primary" : [ {
"attribute" : "is_new",
"label" : "Latest!",
"theme" : "NEW"
} ],
"secondary" : [ {
"attribute" : "is_new",
"label" : "Latest!",
"theme" : "NEW"
} ]
},
"brand" : "Versace",
"custom" : { },
"depth" : {
"amount" : 25.0,
"unit" : "cm"
},
"description" : "Super elastic fit.",
"height" : {
"amount" : 25.0,
"unit" : "cm"
},
"imageInfo" : {
"effect" : "NONE",
"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,
"sellingPrice" : {
"max" : 4500.0,
"min" : 190.5
},
"series" : "Billy",
"swatch" : {
"colors" : [ "#FF0000" ],
"type" : "COLORS"
},
"ticket" : "Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7",
"title" : "Country Fit Cowboy Jeans",
"typedCustom" : {
"lengths" : { }
},
"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" : {
"lengths" : { }
},
"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"
} ]
}
Schema
ProductPageResult¶
The object representation of a product page.
Name | Type | Description | Example |
---|---|---|---|
productGroup | ProductGroupResult | ||
recommendationLists | RecommendationProductList[] | A list of requested recommendation lists, as specified in request body. |
Schemas¶
Inner schemas
Badges¶
Product badges, split per area.
Name | Type | Description | Example |
---|---|---|---|
primary | ProductBadge[] | ||
secondary | ProductBadge[] |
CustomAttributeResult¶
Custom attributes of the content item, represented as key-value pairs.
Name | Type | Description | Example |
---|---|---|---|
id | string | Id of the attribute (the actual value). | summer |
label | string | The label of the attribute (the name attribute in the feed - currently not available for content items). | Summer |
Image¶
The object representation of an image.
Name | Type | Description | Example |
---|---|---|---|
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. | 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). | The model is 176 cm tall and is wearing size S |
custom | <string, string> | Custom attributes of the image. | |
sources | Source[] |
ImageInfo¶
The object representation of image information.
Name | Type | Description | Example |
---|---|---|---|
effect | string | 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 . | NONE |
images | Image[] | The product images to display. | |
thumbnail | string | The url of the thumbnail for the product. Undefined if images is empty. | https://cdn.example.com/thumbs/j12_prod.jpg |
MeasurementResult¶
Custom lengths of the product matching length attributes requested by the query parameter 'presentCustom'.
Name | Type | Description | Example |
---|---|---|---|
amount | number | The amount of the measurement as provided in the import. | 25 |
unit | string | The unit of the measurement as provided in the import. | cm |
Price¶
Min and max price
Name | Type | Description | Example |
---|---|---|---|
max | number | 4500.0 | |
min | number | 190.5 |
PriceResult¶
Additional prices for presentation. Only available on the product-page productGroup and when using the query parameter 'presentPrices'.
Name | Type | Description | Example |
---|---|---|---|
id | string | The id identifying the custom price. | VIP_EUR |
listPrice | number | The price displayed in the shop as the standard price. | 12.99 |
sellingPrice | number | The price that the customer pays. | 9.99 |
ProductBadge¶
Name | Type | Description | Example |
---|---|---|---|
attribute | string | The attribute in the data feed that the badge is based on. | is_new |
label | string | The presentation text of the badge. | Latest! |
theme | string | The type of badge style used. Supported values: NONE , SALE , DISCOUNT , NEW , THEME_1 , THEME_2 , THEME_3 . | NEW |
ProductFilter¶
Deprecated
This feature will most likely be removed in new versions.
A product filter restricting which products that the listing may contain. Supports single values, lists, and (for numerical attributes) ranges. 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). In addition to built-in attributes, it is also possible to filter on custom facets, through prefixing the attribute to be filtered with custom., for example "custom.season": ["Winter", "Spring"]. At most 200 attribute values can be supplied per attribute and at most 100 product keys can be picked at once.
Name | Type | Description | Example |
---|---|---|---|
price | RangeAttribute |
ProductGroupResult¶
The object representation of the product group result.
Name | Type | Description | Example |
---|---|---|---|
key | string | Product group identifier. | PRODGROUP060194 |
products | ProductResult[] | 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. | 2 |
ProductGroupSettings¶
Name | Type | Description | Example |
---|---|---|---|
include | boolean | Defaults to include: false. Set to include: true to return the product group object | true |
ProductResult¶
The object representation of a product.
Name | Type | Description | Example |
---|---|---|---|
badges | Badges | ||
brand | string | Brand of the product. | Versace |
custom | <string, CustomAttributeResult[]> | Custom attributes of the product. Only available on the product-page productGroup and when using the query parameter 'presentCustom'. | |
depth | MeasurementResult | ||
description | string | Description of the product. Undefined if omitted during import. | Super elastic fit. |
height | MeasurementResult | ||
imageInfo | ImageInfo | ||
inStock | boolean | True if any variant is in stock. | true |
key | string | Product identifier. | p1000-101 |
length | MeasurementResult | ||
link | string | Link to the product page. | men/jeans/country-fit-cowboy-jeans |
listPrice | Price | ||
name | string | Name of the product. | Romeo |
rating | number | Current rating value. Undefined when ratings are disabled. | 4.5 |
sellingPrice | Price | ||
series | string | Series that this product belongs to. | Billy |
swatch | Swatch | ||
ticket | string | The ticket is a unique string for an object generated by eSales. | Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7 |
title | string | Title of the product. | Country Fit Cowboy Jeans |
typedCustom | TypedCustomResult | ||
variants | VariantResult[] | 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 | MeasurementResult | ||
weight | MeasurementResult | ||
width | MeasurementResult |
RangeAttribute¶
Deprecated
This feature will most likely be removed in new versions.
A min and max range value object for a specific attribute.
Name | Type | Description | Example |
---|---|---|---|
max | integer | Defaults to the maximum eligible value if omitted. | 1000 |
min | integer | Defaults to 0 if omitted. | 0 |
RecListRequestSettings¶
A configuration object for the recommendation list request. Most page types support recommendation lists. To include recommendation lists in a page response, the request body must include the recommendation configuration. Be aware that having many lists with complex rules/algorithms on a page may affect response times.
Name | Type | Description | Example |
---|---|---|---|
id Required | 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. Min length: 1 . Max length: 20 . Pattern: ^[A-Za-z0-9_-]*$ . | RECS1 |
algorithm | string | The algorithm to apply on the recommendation listing. Defaults to TOP_PRODUCTS. Note that some algorithms may require additional parameters see here for more information. Supported values: TOP_PRODUCTS , PERSONAL , CART , FAVORITES , UPSELL , STYLE_WITH , ALTERNATIVES , NEWEST_PRODUCTS , MORE_FROM_SERIES , RECENTLY_VIEWED , ADD_TO_CART_RECS . | CART |
label | string | The presentation text of the list. Min length: 1 . Max length: 200 . Pattern: (?:|.[^s].) . | Recommended for you |
limit | integer | The number of product groups to list. Min: 1 . Max: 200 . | 10 |
params | RequestParams | ||
productFilter | ProductFilter | ||
productRules | string | A logical expression used by Voyado Elevate 4 to restrict the data set to a Product Selection. The rules can go from easy, such as to only include a product by its key or items that are in stock, to more complex expressions with multiple attributes for products at the same time. If no rules are provided, the entire data set will be used. Please note that when used in Landing Pages, the "Handpicked" rule must be the first rule, and must contain a set of product keys as its only condition. At most 100 product keys can be handpicked in a single request, and at most 200 attribute values can be supplied for each attribute. | 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" } |
showMoreLink | string | A URL to see a large selection. Undefined if not specified in Elevate Apps. Merchandiser option. Min length: 1 . Max length: 1000 . Pattern: ^(//|/|https?://).* . | |
visualization | string | How the list should be presented. Merchandiser option. Supported values: CAROUSEL , GRID . | CAROUSEL |
RecommendationProductList¶
The object representation of a recommendation product list.
Name | Type | Description | Example |
---|---|---|---|
id | string | The identifier of the list. | PDP-1 |
label | string | The identifier of the list. | The presentation text of the list. |
productGroups | ProductGroupResult[] | 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. | https://example.com/prods/jeans/levis |
visible | boolean | Whether the recommendation list is visible or has been hidden in the apps | |
visualization | string | How the list should be presented. Merchandiser option. Supported values: CAROUSEL , GRID . | CAROUSEL |
RequestParams¶
Any parameters required by the applied algorithm. Conditionally required.
Name | Type | Description | Example |
---|---|---|---|
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. Min items: 0 . Max items: 250 . | |
productKey | string | The base product for the ALTERNATIVES, STYLE_WITH, and UPSELL recommendation algorithms. Defaults to the provided product key parameter for product-page requests. | <PRODUCT_KEY_FROM_YOUR_FEED> |
Source¶
Name | Type | Description | Example |
---|---|---|---|
url Required | string | The URL of the image source. | https://cdn.example.com/img/j12_prod.jpg |
height | integer | The height of the image. Undefined if height was not specified. | 820 |
width | integer | The width of the image. Undefined if width was not specified and hasn't yet been assessed by the image service. | 420 |
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, or MULTI are other possible return types. These are to be used to generate swatches matching these specific properties.
Name | Type | Description | Example |
---|---|---|---|
colors | string[] | An array with 1 - 3 CSS colour codes for SwatchType COLORS. Empty for other types. | #FF0000 |
type | string | Type of colour swatch for the product. Supported values: MISSING_COLORS , COLORS , SILVER , GOLD , MULTI . | COLORS |
TypedCustomResult¶
Typed custom attributes of the product. Only available on the product-page productGroup and when using the query parameter 'presentCustom'.
Name | Type | Description | Example |
---|---|---|---|
lengths | <string, MeasurementResult> | Custom lengths of the product matching length attributes requested by the query parameter 'presentCustom'. |
VariantAvailabilityInfo¶
Represents availability in one store or online.
Name | Type | Description | Example |
---|---|---|---|
channel | string | The channel either STORE or ONLINE. | STORE |
key | string | The key identifying the store. Null if channel = ONLINE. | boardwalk |
stockNumber | integer | The number of items of this variant in stock in this channel/key. | 5 |
VariantResult¶
The object representation of a variant.
Name | Type | Description | Example |
---|---|---|---|
availability | VariantAvailabilityInfo[] | List of availability information. Contains an entry for the online channel and one for each relevant store. | |
custom | <string, CustomAttributeResult[]> | Custom attributes of the variant. Only available on the product-page productGroup and when using the query parameter 'presentCustom'. | |
depth | MeasurementResult | ||
height | MeasurementResult | ||
inStock | boolean | True if the variant is in stock. | true |
key | string | Variant identifier. | 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. | XL |
length | MeasurementResult | ||
link | string | Link to product page with variant selected. | women/pants/khaki/101-v3-red |
listPrice | number | List price of the variant. | 15.0 |
prices | PriceResult[] | 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. | 24.0 |
size | string | A representative size of the variant. Overridden by label if provided. Deprecated, use label instead, | XL |
stockNumber | integer | The amount of this variant that is in stock. | 5 |
ticket | string | Unique ticket for the eSales object. | Oy9mYXNoaW9uL0RFU0tUT1AvQ09OVEVOVF9TRUFSQ0hfUEFHRS9QUklNQVJZX0xJU1Q7Iztjb250ZW50X2tleTtkMDAxOyM7IzsjOyM7 |
typedCustom | TypedCustomResult | ||
volume | MeasurementResult | ||
weight | MeasurementResult | ||
width | MeasurementResult |