Add To Cart Popup¶

https://{cluster-id}.api.esales.apptus.cloud/api/storefront/v3/queries/add-to-cart-popup

POST¶

The Add To Cart Popup query is used to get recommendations for a product that has just been added to the cart. It is typically used with the ADD_TO_CART_RECS algorithm.

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`
locale Required	The visitor locale. Must match an available locale identifier on the current market in the data feed.
market Required	The visitor market identifier. Must match the corresponding market identifier in the data feed.	`UK`
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`
variantKey Required	The key of the variant added to cart. Must match the key of the variant in the data feed.	`<VARIANT_KEY_FROM_YOUR_FEED>`
cart	A pipe-separated list of keys of the items added to the cart. Must match the key of the variant or product in the data feed. Always use the variant key when possible. If not provided we will use previously notified add to cart items.	`<VARIANT_KEY_FROM_YOUR_FEED>\|<ANOTHER_VARIANT_KEY_FROM_YOUR_FEED>`
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 attributes to include in all listings. Prefix with "variant." to request custom variant attributes.	`season\|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. 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

application/json;charset=utf-8

{
  "recommendationLists" : [ {
    "id" : "RECS1",
    "algorithm" : "ADD_TO_CART_RECS",
    "label" : "Recommended for you",
    "limit" : 5,
    "visualization" : "CAROUSEL"
  } ]
}

Schema

AddToCartPopupRequestSettings¶

The add-to-cart-popup is typically used to return recommendations to show after the user has added a product to the cart. It is typically used with a ADD_TO_CART_RECS recommendation.

Name	Type	Description	Example
recommendationLists	RecListRequestSettings[]	A list of recommendations to be included in the response. 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/storefront/v3/queries/add-to-cart-popup?customerKey=0b05119e-eeb8-418a-bbfb-defa0dde417e&locale=locale&market=UK&sessionKey=0b05119e-eeb8-418a-bbfb-defa0dde417e&touchpoint=DESKTOP&variantKey=%3CVARIANT_KEY_FROM_YOUR_FEED%3E&cart=%3CVARIANT_KEY_FROM_YOUR_FEED%3E%7C%3CANOTHER_VARIANT_KEY_FROM_YOUR_FEED%3E&channels=ONLINE%7CSTORE&notify=false&presentCustom=season%7Cvariant.weight&presentPrices=VIP%7Cmember&priceId=VIP&stores=240%7C100&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

application/json;charset=utf-8

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

AddToCartPopupResult¶

The result object from a successful call to the add-to-cart-popup.

Name	Type	Description	Example
recommendationLists	RecommendationProductList[]	A list of recommendation lists to be included in the response.

Schemas¶

Inner schemas

Badges¶

Name	Type	Description	Example
primary	ProductBadge[]	Badges in the primary area
secondary	ProductBadge[]	Badges in the secondary area

CustomAttributeResult¶

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¶

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¶

Name	Type	Description	Example
max	number		`4500.0`
min	number		`190.5`

PriceResult¶

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"`

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 ~~Deprecated~~	RangeAttribute	An example parameter of a range attribute.

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`

ProductResult¶

The object representation of a product.

Name	Type	Description	Example
badges	Badges	Product badges, split per area.
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	Depth of the product. Undefined if omitted during import.
description	string	Description of the product. Undefined if omitted during import.	`"Super elastic fit."`
height	MeasurementResult	Height of the product. Undefined if omitted during import.
imageInfo	ImageInfo	Product image information.
inStock	boolean	True if any variant is in stock.	`true`
key	string	Product identifier.	`"p1000-101"`
length	MeasurementResult	Length of the product. Undefined if omitted during import.
link	string	Link to the product page.	`"men/jeans/country-fit-cowboy-jeans"`
listPrice	Price	Min and max price
name	string	Name of the product.	`"Romeo"`
rating	number	Current rating value. Undefined when ratings are disabled.	`4.5`
sellingPrice	Price	Min and max price
series	string	Series that this product belongs to.	`"Billy"`
swatch	Swatch	Swatch information.
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	Typed custom attributes of the product. Only available on the product-page productGroup and when using the query parameter 'presentCustom'.
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	Volume of the product. Undefined if omitted during import.
weight	MeasurementResult	Weight of the product. Undefined if omitted during import.
width	MeasurementResult	Width of the product. Undefined if omitted during import.

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	Any parameters required by the applied algorithm. Conditionally required.
productFilter ~~Deprecated~~	ProductFilter	A Json expression restricting the products that the recommendation listing may contain.
productRules	string	A product rule expression restricting the products that the recommendation listing may contain.	`"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?://).*`.	`"/holiday/sale"`
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¶

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`.	`"v1_1"`
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¶

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	Depth of the variant. Undefined if omitted during import.
height	MeasurementResult	Height of the variant. Undefined if omitted during import.
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	Length of the variant. Undefined if omitted during import.
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	Typed custom attributes of the variant. Only available on the product-page productGroup and when using the query parameter 'presentCustom' requesting typed custom attributes.
volume	MeasurementResult	Volume of the variant. Undefined if omitted during import.
weight	MeasurementResult	Weight of the variant. Undefined if omitted during import.
width	MeasurementResult	Width of the variant. Undefined if omitted during import.

Add To Cart Popup¶

POST¶

Request¶

Header parameters¶

Query parameters¶

Supported Content-Type¶

Request body¶

AddToCartPopupRequestSettings¶

Response¶

Response codes¶

Response headers¶

Response body¶

AddToCartPopupResult¶

Schemas¶

Badges¶

CustomAttributeResult¶

Image¶

ImageInfo¶

MeasurementResult¶

Price¶

PriceResult¶

ProductBadge¶

ProductFilter¶

ProductGroupResult¶

ProductResult¶

RangeAttribute¶

RecListRequestSettings¶

RecommendationProductList¶

RequestParams¶

Source¶

Swatch¶

TypedCustomResult¶

VariantAvailabilityInfo¶

VariantResult¶