Query parameters¶

All Storefront API endpoints expect a set of query parameters. This section highlights some shared parameters as well as some noteworthy query parameters and concepts, providing more detailed explanations of each.

Please refer to the API specification for the exact set of parameters available for each endpoint.

Common parameters¶

The following query parameters are required for almost all Storefront API queries, with some also applicable to notification requests.

Correct usage of the customer and session keys are essential for the behavioral data to be analyzed 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.

Applied price¶

When supplying a priceId to a request, this price will be used for all price-related properties in the response. This includes the selling_price and list_price of all returned variants as well as the price range for filtering and what price value to use for sorting.

Response templates¶

There are several ways to control which fields are included in the response for product and variant lists. Using templates (templateId) is the recommended approach over custom attributes (presentCustom). Prices for presentation (presentPrices) is compatible with both methods.

Templates¶

Templates can be used to control which fields are included in the response for product and variant lists. Templates specifying the fields to include are imported separately via the Import template endpoint in the Admin API. To apply a template to a query, the id of the template should be specified with the parameter templateId. Templates are the recommended way to consistently return the same fields for products and variants.

• templateId cannot used in combination with presentCustom.
• templateId will not affect the main product returned in a Product page query, it only applies to included recommendation lists.

For more details, see Product list response templates.

Custom attributes¶

The query parameter presentCustom can be used to control which custom attributes of products that are returned in product lists and recommendation lists in query responses.

• presentCustom can't be used in combination with templateId.
• presentCustom will not affect the main product returned in a Product page query, it only applies to included recommendation lists.
• templateId usage is the recommended approach over custom attributes.

Prices for presentation¶

The query parameter presentPrices allows for prices to be included in the response of all variants in addition to it's default price. This, unlike priceId does not affect filtering or sorting.

Stores and channels¶

Filtering and ranking products based on both online and store specific stock levels are supported in Elevate. 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 catalog import. 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 catalog import.

Examples¶

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

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

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 Elevate Apps, where merchandisers are provided with control of listings for each individual page. The max length of a page id is 200 characters.

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}.elevate-api.cloud/api/storefront/v3/queries/landing-page?sort=NEWEST_FIRST

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][vfs] 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}elevate-api.cloud/api/storefront/v3/queries/landing-page?
f.brand=adidas&f.custom.season=winter|spring&f.price.min=500&f.price.max=2500&
f.onlyInStock=true

Search origin¶

The origin parameter in search queries identifies how the search was initiated. This is essential for behavioral analysis and is strongly recommended to include in all search-page queries. The table below describes when each origin value should be used.

It’s recommended to keep the same origin value when filtering or paginating results, especially for UNDO_AUTO_CORRECT where omitting the origin can lead to different search results.

Notify¶

The notify parameter should normally be set to true in production for all visitor-facing parts of the e-commerce site. Setting it accurately is important for accurate behavioral analysis and statistics.

Set notify=false in the following cases:

• When queries are used in internal administrative tools
• When performing load testing
• When tracking visitor activity is not legally permitted