Skip to content

Query parameters

Each page type has a set of applicable query parameters, found in the specification for each page type. The query parameters which apply to multiple pages, are detailed and listed in this section.

Base query parameters

Base query parameters apply to all pages. Those which are mandatory must be supplied for all requests, while optional ones are likely to be either be supplied in an equivalent manner for all page types or not at all.

Mandatory parameters

Name Type Description Example
market string The visitor market. Must match the corresponding market identifier in the data feed. UK
touchpoint string The visitor's touchpoint. Valid values are DESKTOP and MOBILE. DESKTOP
customerKey string A key that uniquely identifies the current visitor.
Using UUIDs as keys are recommended.
sessionKey string A unique key, identifying the session.
Using UUIDs as keys are recommended.

Correct usage of the customer and session keys are essential for the behavioural data to be analysed correctly. A session starts when a visitor arrives at a site, and is identified through a unique sessionKey. The same sessionKey must be used though out the visit. For more information about customer keys, see Visitor identification.

Optional parameters

Name Type Description Example
priceId string A custom price identifier. Must match supplied custom price identifiers in the data feed. EUR
notify boolean Turns off notifications and behavioural registration for the query. false

Price ID

When supplying a price ID to a request, the selling_price and list_price property of all products will be provided as the price in the data feed for that price ID. Sorting, faceting, and filtering on price will also be based on prices with the specified identifier.


The notify parameter should always be enabled in production for visitor facing parts of the e-commerce site. However, if any query is used for other purposes such as internal administrative tools or if a load test is run on the production environment with simulated data, ensure that notify=false is applied. This will prevent tests and internal tools to cause noise in statistics as well as erroneous behaviour analysis.

Note that this is not an issue for small scale testing, but rather something to consider when lots of non-visitor generated traffic is expected.

Facet selections

Facet selections are used for visitor facing product list filters. As opposed to product filters, facets are to be visualized and applicable and reversible by the visitors. All applicable facets are part of the response for Primary Listings. Each facet have an id, and should be provided along with the selected values as query parameters, when selected by the visitors.

Value facet syntax

Applicable for Text, Colour and Size Facets. All facet ids and value ids are found in the response for each facet. Multiple values are provided with a pipe, |, as a separator.


Range facet syntax

Range Facets are provided with min and max as suffix to the facetId with values for the desired range. Both min and max are inclusive and default to 0 and the maximum eligible value respectively.


Request example

The following example illustrates a category page request with a brand, a season (custom attribute), and a price range selected as facets. Other request parameters have been omitted for brevity.


Page IDs

For landing pages and category pages, unique page identifiers must be provided. Page identifiers will be visible and used to distinguish between pages in the eSales Apps, where merchandisers are provided with control of listings for each individual page.

For pages on the site, page paths should be used.


For external requests, an identifier understood by merchandisers should be used.


Sort orders

The sort parameter determines the applied sort order of the listing. All eligible sort orders are found in the Primary Listing response. Sort orders are sent as a query parameter with the id as the value which is one of the listed Sort types, sort=[id].

Request example

The following example illustrates a category page request with the sort order NEWEST_FIRST applied. Other request parameters have been omitted for brevity.


Last update: October 8, 2021
Back to top

This online publication is intellectual property of Apptus Technologies. Its contents can be duplicated in part or whole, provided that a copyright label is visibly located on each copy and the copy is used in conjunction with the product described within this document.

All information found in these documents has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Apptus Technologies nor the authors shall be held liable for possible errors or the consequences thereof.

Software and hardware descriptions cited in these documents might be registered trademarks. All trade names are subject to copyright restrictions and may be registered trademarks. Apptus Technologies essentially adheres to the manufacturer’s spelling. Names of products and trademarks appearing in this document, with or without specific notation, are likewise subject to trademark and trade protection laws and may thus fall under copyright restrictions.