> ## Documentation Index
> Fetch the complete documentation index at: https://product-discovery.developer.voyado.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query parameters

> Reference for common Storefront API query parameters, including market, locale, keys, price IDs, templates, facets, sort orders, and user context.

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.

| Name          | Description                                                                                                                                                                                    | Example                                |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `market`      | The visitor market. Must match the corresponding [market identifier](/elevate/docs/integration/essentials/markets-and-locales#markets) in the configuration import.                            | `UK`                                   |
| `locale`      | The visitor locale. Must match an available [locale identifier](/elevate/docs/integration/essentials/markets-and-locales#locales) on the current market in the configuration import.           | `en-GB`                                |
| `touchpoint`  | The visitor’s touchpoint. Valid values are `DESKTOP` and `MOBILE`.                                                                                                                             | `DESKTOP`                              |
| `customerKey` | A key that uniquely identifies the current visitor. Using [UUIDs](https://en.wikipedia.org/wiki/Universally_unique_identifier) <Icon icon="external-link" size={12} /> as keys is recommended. | `0b05119e-eeb8-418a-bbfb-defa0dde417e` |
| `sessionKey`  | A unique key identifying the session. Using [UUIDs](https://en.wikipedia.org/wiki/Universally_unique_identifier) <Icon icon="external-link" size={12} /> as keys is recommended.               | `0b05119e-eeb8-418a-bbfb-defa0dde417e` |
| `userContext` | A flag indicating how visitor data should be treated. See [User context](#user-context).                                                                                                       | `PERSONALIZED`                         |

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](#user-context) with `ANONYMOUS` and omit both `customerKey` and `sessionKey`.

For more information about customer keys, see [Visitor identification](/elevate/docs/integration/site-integration/session-management#visitor-identification).

## Applied price

| Parameter | Description                                                                                                                                 | Example |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `priceId` | A custom price identifier. Must match supplied custom price identifiers in the [catalog import](/elevate/docs/api/admin/v4/import/catalog). | `EUR`   |

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

| Parameter       | Description                                                                                                                                                                                                                                                                                                                       | Example                  |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| `templateId`    | Which template to apply on products and variants in listings. Cannot be used in combination with `presentCustom`.                                                                                                                                                                                                                 | `templateName`           |
| `presentPrices` | Include multiple price identifiers from the supplied custom price identifiers in the [catalog import](/elevate/docs/api/admin/v4/import/catalog). Multiple values are provided with a pipe (`\|`) as separator.                                                                                                                   | `memberBasic\|memberVIP` |
| `presentCustom` | Custom attributes of products used for presentation in product and recommendation lists. Multiple values are provided with a pipe (`\|`) as separator. Each custom attribute must match a supplied attribute in the [catalog import](/elevate/docs/api/admin/v4/import/catalog). Cannot be used in combination with `templateId`. | `material\|sustainable`  |

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](/elevate/docs/api/admin/v4/import/templates) 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](/elevate/docs/api/storefront/v3/queries/product-page). It only applies to included recommendation lists.

For more details, see [Product list response templates](/elevate/docs/guides/storefront-responses/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](/elevate/docs/api/storefront/v3/queries/product-page). 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

| Parameter  | Description                                                                                                                                                                                                                                                                                                                              | Example         |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| `channels` | Which channels to use. Valid values are `ONLINE` and `STORE`. Multiple values are provided with a pipe (`\|`) as separator. Channels default to `ONLINE\|STORE` if none are provided. If `STORE` is explicitly included, the `stores` parameter may not be empty. For more information, see [Stores and channels](#stores-and-channels). | `ONLINE\|STORE` |
| `stores`   | The stores to use. This affects which stock is used and displayed together with the `channels` parameter. Multiple values are provided with a pipe (`\|`) as separator. Each store must match a supplied store key in the [catalog import](/elevate/docs/api/admin/v4/import/catalog).                                                   | `240\|100`      |

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](https://help.elevate.voyado.com/hc/en-gb/articles/27611322098076-FAQ-Pages-settings) <Icon icon="external-link" size={12} /> 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](/elevate/docs/api/admin/v4/import/catalog).

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](/elevate/docs/api/admin/v4/import/catalog).

### 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`.

| 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<br />`stockNumber`: 10<br />`availability`: online: 10, store `240`: 5 | `inStock`: true<br />`stockNumber`: 10<br />`availability`: online: 10, store `240`: 0 | `inStock`: false<br />`stockNumber`: 0<br />`availability`: online: 0                |
| `ONLINE\|STORE` | `240`  | `P1`, `P2`               | `inStock`: true<br />`stockNumber`: 15<br />`availability`: online: 10, store `240`: 5 | `inStock`: true<br />`stockNumber`: 10<br />`availability`: online: 10, store `240`: 0 | `inStock`: false<br />`stockNumber`: 0<br />`availability`: online: 0                |
| `STORE`         | `240`  | `P1`                     | `inStock`: true<br />`stockNumber`: 5<br />`availability`: online: 10, store `240`: 5  | `inStock`: false<br />`stockNumber`: 0<br />`availability`: online: 10, store `240`: 0 | `inStock`: false<br />`stockNumber`: 0<br />`availability`: online: 0                |
| `STORE`         | `100`  | `P3`                     | `inStock`: false<br />`stockNumber`: 0<br />`availability`: online: 10, store `100`: 0 | `inStock`: false<br />`stockNumber`: 0<br />`availability`: online: 10, store `100`: 0 | `inStock`: true<br />`stockNumber`: 1<br />`availability`: online: 0, store `100`: 1 |

<Warning>
  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`.
</Warning>

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

```bash icon="terminal" theme={null}
/women/dresses
```

For external requests, use an identifier understood by merchandisers:

```bash icon="terminal" theme={null}
mms-campaign-S2020
```

<Tip>
  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.
</Tip>

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

```bash icon="terminal" theme={null}
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.

```http icon="code" theme={null}
https://{cluster-id}.elevate-api.cloud/api/storefront/v3/queries/landing-page?sort=NEWEST_FIRST
```

## Facet selections

| Parameter | Description                                                                                  | Example |
| --------- | -------------------------------------------------------------------------------------------- | ------- |
| `f.[id]`  | The applied facet selection in the search result. Each facet attribute is prefixed with `f`. | `false` |

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.

<AccordionGroup>
  <Accordion title="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 separator.

    No escaping is needed, as pipes that are part of the value ID itself are pre-escaped.

    ```bash icon="terminal" theme={null}
    f.[id]=[value1.id]|[value2.id]
    ```
  </Accordion>

  <Accordion title="Range facet syntax">
    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.

    ```bash icon="terminal" theme={null}
    f.[id].min=[min]&f.[id].max=[max]
    ```
  </Accordion>

  <Accordion title="Checkbox facet syntax">
    Checkbox facets are similar to [value facets](#value-facet-syntax), 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`.

    ```bash icon="terminal" theme={null}
    f.[id]=[true or false]
    ```
  </Accordion>
</AccordionGroup>

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

```http icon="code" theme={null}
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

| Parameter | Description                                                                                                                                                                             | Example          |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| `origin`  | The search origin of the search phrase. Defaults to `ORGANIC`. Supported values: `ORGANIC`, `DID_YOU_MEAN`, `UNDO_AUTO_CORRECT`, `PHRASE_SUGGEST`, `RELATED_SEARCHES`, `RECENT_SEARCH`. | `PHRASE_SUGGEST` |

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.

| Origin              | Description                                                                                       | Example                                                                                                   |
| ------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `ORGANIC`           | Indicates a standard user-initiated search.                                                       | The user types a query in the search bar and presses **Enter**.                                           |
| `DID_YOU_MEAN`      | Indicates that the user clicked a “Did you mean” suggestion returned in the search-page response. | The search response includes “Did you mean: sneakers”, and the user clicks it.                            |
| `UNDO_AUTO_CORRECT` | Indicates that the user chose to revert an automatic correction made by Elevate.                  | The user types `iphon`, Elevate corrects it to `iphone`, but the user clicks the original phrase `iphon`. |
| `PHRASE_SUGGEST`    | Indicates that the user selected a suggested phrase from autocomplete.                            | While typing `snea`, autocomplete suggests `sneakers adidas`, and the user clicks it.                     |
| `RELATED_SEARCHES`  | Indicates that the user clicked a related search phrase displayed in a previous search response.  | The search results for `running shoes` include a related search `trail shoes`, and the user clicks it.    |
| `RECENT_SEARCH`     | Indicates that the user selected a recent search phrase from autocomplete.                        | In the autocomplete recent searches section, the user clicks a previous query.                            |

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](/elevate/docs/integration/site-integration/session-management#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.

| User context     | Description                                                                                                                                                                                                           |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PERSONALIZED`   | The default behavior. Personalization is enabled and user behavior is analyzed to understand trends and product performance.                                                                                          |
| `UNPERSONALIZED` | Personalization is disabled, but user behavior is still analyzed to understand general trends. `customerKey` must be excluded when sending unpersonalized queries.                                                    |
| `ANONYMOUS`      | The visitor is completely anonymous: no personalization is applied, A/B tests are disabled, and most metrics are not updated. Both `customerKey` and `sessionKey` must be excluded from all requests.                 |
| `SYNTHETIC`      | The query is considered faux and no metrics are collected. Personalization is disabled and `customerKey` and `sessionKey` are optional (although if a customer key is supplied, a session key must also be provided). |

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