Skip to main content
All Storefront API endpoints expect a set of query parameters. This section highlights shared parameters, noteworthy query parameters, and related concepts. 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. Some are also applicable to notification requests. Correct usage of the customer and session keys is essential for 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 throughout the visit, unless the visitor is anonymous. For anonymous users, use user context with ANONYMOUS and omit both customerKey and sessionKey. For more information about customer keys, see Visitor identification.

​
Applied price

When supplying a priceId to a request, this price is used for all price-related properties in the response. This includes:
  • selling_price
  • list_price
  • Price ranges for filtering
  • Price values used for sorting

​
Response templates

There are several ways to control which fields are included in responses for product and variant lists. Using templates with templateId is recommended over using custom attributes with presentCustom. Prices for presentation, through presentPrices, are 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 through the Import template endpoint in the Admin API. To apply a template to a query, specify the template ID using the templateId parameter. Templates are the recommended way to consistently return the same fields for products and variants.
  • templateId cannot be used in combination with presentCustom.
  • templateId does 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 product attributes are returned in product lists and recommendation lists in query responses.
  • presentCustom cannot be used in combination with templateId.
  • presentCustom does not affect the main product returned in a Product page query. It only applies to included recommendation lists.
  • Using templateId is recommended over using presentCustom.

​
Prices for presentation

The query parameter presentPrices allows prices to be included in the response for all variants in addition to their default price. Unlike priceId, presentPrices 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 buried by default 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 are used when filtering and ranking based on stock levels:
  • ONLINE uses the online stock level.
  • STORE uses 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 stock levels 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 decides which stores to display. For the main productGroup of the product-page response, the array includes all stores that are present on the variant. The online stock is always included as the first item. A store is only included if present on the variant in the catalog import.

​
Examples

The following example has three products. Each product has 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.
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 results in HTTP status 400 Bad Request.

​
Page IDs

For landing pages and category pages, unique page identifiers must be provided. Page identifiers are visible in the Elevate Apps and are used to distinguish between pages, where merchandisers are provided control of listings for each individual page. The maximum length of a page ID is 200 characters. For pages on the site, use page paths:
For external requests, use an identifier understood by merchandisers:
The page identifier, page ID, or page reference is used to identify an existing page configuration. An existing page configuration created through the Admin API or Elevate Application takes precedence over configuration supplied in the POST request body.

​
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:

​
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.

​
Facet selections

Facet selections are used for visitor-facing product list filters, called facets. Unlike product filters, facets are visualized, applicable, and reversible by 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 visitors.
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 separator.No escaping is needed, as pipes that are part of the value ID itself are pre-escaped.
Range facets are provided with min and max as suffixes 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.
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, provide the value 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.

​
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. It is 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.

​
User context

The userContext parameter controls whether and how Elevate applies personalization and collects behavioral metrics. It can be provided in all queries and notifications. When omitted, the default behavior is PERSONALIZED, which lets Elevate use customerKey and sessionKey for personalization and behavior analysis. The available values below let you reduce personalization or exclude behavioral signals for privacy-sensitive or testing scenarios. For more information, see Consent and privacy. In general, provide as much context as possible when allowed, as it improves personalization and the relevance of the results. However, due to privacy regulations, you may need to limit personalization for certain users, for example if they have not given consent for tracking. In such cases, you can use the userContext parameter to indicate that no personalization should be applied.
  • If the visitor consents to analytics tracking but not personalization, use UNPERSONALIZED.
  • If the visitor does not consent to any tracking, use ANONYMOUS.
  • If the request is for testing purposes, such as load tests, or sent by internal, administrative tools, use SYNTHETIC. Never use this for real customers.
The behavior of SYNTHETIC is identical to supplying the legacy notify=false parameter. Trying to use notify=false together with any user context results in an error.
Last modified on September 11, 2026