Skip to content

Query parameters

Each page type has a set of applicable query parameters, found in the API specification. 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.
0b05119e-eeb8-418a-bbfb-defa0dde417e
sessionKey string A unique key, identifying the session.
Using UUIDs as keys are recommended.
0b05119e-eeb8-418a-bbfb-defa0dde417e

Correct usage of the customer and session keys are essential for the behavioral 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
channels string 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 parameter may not be empty. For more information, see Stores and channels. ONLINE|STORE
stores string The stores to use. Will impact which stock is used and displayed together with the channels parameter. Multiple values are provided with a pipe, |, as a separator. Each store must match a supplied store key in the data feed. For more information, see Stores and channels. 240|100
presentCustom string Custom attributes of products that are used for presentation in product and recommendation lists. Multiple values are provided with a pipe, |, as a separator. Each custom attribute must match a supplied attribute in the data feed. For more information, see Custom attributes. material|sustainable
notify boolean Turns off notifications and behavioral 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.

Stores and channels

Filtering and ranking products based on both online and store specific stock levels are supported in eSales. Filtering can be done either by default for all listings, or by adding the onlyInStock facet to the site. This lets the visitor control when to show out of stock products. If out of stock products are displayed, they are by default buried and displayed after products that are in stock. These behaviors can be modified in the Out of stock settings for Pages in the Experience app.

The channels parameter determines what channels should be used when filtering and ranking based on stock levels, as discussed above. The ONLINE channel will use the online stock level while the STORE channel will use store specific stock levels. Channels also affect the inStock properties on products and variants, and the general stockNumber on variants in the result. Which store specific stocks levels that are used is decided by the stores parameter.

The availability array on each product variant in the result is unaffected by the channels parameter, and displays unmodified stock levels from the data feed. For regular listings, the stores parameter is used to decide which stores to display, but for the main productGroup of the product-page response the array will include all stores that are present on the variant. Note that the online stock is always included as the first item, and that a store is only included if present on the variant in the data feed.

Examples

The following example has three products, each having one variant, witch stock levels online and in two physical stores identified by store keys 240 and 100.

Product Online stock level Store stock levels
P1 10 240: 5, 100: 0
P2 10 240: 0, 100: 0
P3 0 100: 1

The effect of some parameter combinations on a landing page displaying all products is shown below.

Channels Stores Displayed when filtering P1 result P2 result P3 result
ONLINE 240 P1, P2 inStock: true
stockNumber: 10
availability: online: 10, store 240: 5
inStock: true
stockNumber: 10
availability: online: 10, store 240: 0
inStock: false
stockNumber: 0
availability: online: 0
ONLINE|STORE 240 P1, P2 inStock: true
stockNumber: 15
availability: online: 10, store 240: 5
inStock: true
stockNumber: 10
availability: online: 10, store 240: 0
inStock: false
stockNumber: 0
availability: online: 0
STORE 240 P1 inStock: true
stockNumber: 5
availability: online: 10, store 240: 5
inStock: false
stockNumber: 0
availability: online: 10, store 240: 0
inStock: false
stockNumber: 0
availability: online: 0
STORE 100 P3 inStock: false
stockNumber: 0
availability: online: 10, store 100: 0
inStock: false
stockNumber: 0
availability: online: 10, store 100: 0
inStock: true
stockNumber: 1
availability: online: 0, store 100: 1

Invalid queries

When the STORE value is present in the channels parameter, the stores parameter is required and must not be empty. Failing to supply the stores parameter in this case will result in HTTP status 400 Bad Request.

Custom attributes

Customers and integrators that would like to control what custom attributes of products that are available in product lists and recommendation lists of a page can use the query parameter presentCustom. The attributes returned by the query parameter are valid for all lists on the page.

This parameter is not needed for the main product returned in a Product page query, but the parameter will affect any recommendation lists on a product page if included.

Product rules

Only for Export

The productRules query parameter is only for use with the Export product groups endpoint. The functionality is also available as a Page configuration.

The productRules parameter is equal to defining a Product selection in the eSales Apps. The product rules are a form of logical expressions that are used to restrict the data set used in a query. Rules can go from easy, such as to only include a single product using its product key or items that are in stock, to more complex with multiple attributes for the product selection.

An expression may consist of multiple rules where each rule must have at least one restriction. A restriction must include a condition, which in turn consist of an attribute that is either a list if strings, an interval, or a specified newness.

Definitions Description
Rule A rule, rule, must have at least one restriction. Rules are separated with a space.
Restriction A restriction is either an include, incl, or an exclude, excl, followed by a condition.
Condition A condition must consist of an attribute and is either a list of strings, a numeric interval, or a specified newness.
Attribute An attribute as defined in the data feed. Can be either product_key, department, brand, pattern, custom., price, discount, rating, stock_number, or newness.
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, \.
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.
Newness The age of the products in days, calculated using the release_date attribute in the data feed. Can be a positive integer suffixed by the character d, or default. If default is used, the number of days as defined in the Page settings will be used.
Number Any decimal number from 4.9e-324 up to and including 1.7976931348623157e308.
Positive integer Any positive integer between 1 up to and including 2 147 483 647.

When productRules is used with Category and Landing Pages, the first rule in the page configuration must be Handpicked and must contain a set of product keys as the only condition.

Examples

Handpick products p1234 and p5678.

rule incl product_key { "p1234" "p5678" }

Include only products with the pattern striped with default newness.

rule incl pattern { "striped" } incl newness default

Include products from the brands Bosch or Dewalt, but exclude products with a price above 2000.

rule incl brand { "Bosch" "Dewalt" } excl price [ 2000.01, infinity ]

Include products from the department Kids where newness is three days or less, and the products have a rating between 3 and 5.

rule incl department { "Kids" } incl newness 3d incl rating [ 3, 5 ]

Include in-stock products from the categories Kitchen and Dining with a discount that is less than 30%.

rule incl custom.category_name { "Kitchen" "Dining" } incl discount [ -infinity, 30 ] incl stock_number [ 1, infinity ]

Include all products that match any of the included rules.

rule incl product_key { "ABC123" "DEF456" "GHJ789" }
rule incl custom.material { "leather" } excl price [ -infinity, 100.00 ]
rule incl newness 10d
rule incl brand { "Birkenstock" } excl custom.isActive { "false" }

Notify

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 behavior 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, so called "facets". 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 has an id, which should be provided along with the selected values as query parameters, when selected by the visitors.

Value facet syntax

Applicable for Text, Color 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. No escaping is needed as pipes that are part of the value id itself will be pre-escaped.

f.[id]=[value1.id]|[value2.id]

Range facet syntax

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

f.[id].min=[min]&f.[id].max=[max]

Checkbox facet syntax

Checkbox facets are similar to Value facets but consist only of one boolean value, represented by the selected property. By default, the selected property can be either true or false. To actively select or deselect the Checkbox facet, and thus apply or clear the filter, the value true or false must be provided as shown below.

f.[id]=[true or false]

Request example

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

https://{cluster-id}.api.esales.apptus.cloud/api/v2/queries/landing-page?
f.brand=adidas&f.custom.season=winter|spring&f.price.min=500&f.price.max=2500&
f.onlyInStock=true

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.

/women/dresses

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

mms-campaign-S2020

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.

https://{cluster-id}.api.esales.apptus.cloud/api/v2/queries/category-page?sort=NEWEST_FIRST

Last update: May 13, 2022
Back to top
×
Copyright

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.

CLOSE