API Parameters Reference

This page provides a comprehensive reference for all parameters supported by the Recommendations API.

Required Parameters

At least one of these parameters is required for every API call:

Parameter	Type	Description
currentUrl	string	URL used to determine which route to use. Required unless routeName is provided.
routeName	string	Directly specify which recommendation route to use. Can be used instead of currentUrl.

Common Parameters

These parameters are frequently used to customize recommendations:

Parameter	Type	Default	Description
customerId	GUID	-	User identifier for personalized recommendations. Required for personalized results like Recently Viewed items.
refId	string	-	Product ID/reference for PDP recommendations. Critical for "Similar Items" and "Frequently Bought Together" recommendations.
productsInCart[]	array	-	Array of product IDs currently in the cart. Format: productsInCart[0]=product1&productsInCart[1]=product2
expandProductDetails	boolean	false	When true, returns complete product information. When false, returns only refId and isInStock.
showInStockOnly	boolean	true	Controls whether out-of-stock products are included in recommendations.

Content Customization Parameters

These parameters control the content returned in recommendations:

Parameter	Type	Default	Description
returnMultipleProductsInSlot	boolean	false	When true, may return multiple products per slot based on configuration.
maxNumberOfProductWithinASlot	integer	-	Limits the maximum number of products per slot. Only applies when returnMultipleProductsInSlot is true.
languageTag	string	-	Language code for localized content (e.g., "en-US", "fr-FR"). When provided, returns product information in this language if available.
currencyCode	string	-	ISO currency code (e.g., "USD", "EUR") for pricing. When provided, converts and displays prices in this currency if supported.

Advanced Filtering Parameters

These parameters provide advanced filtering capabilities:

Parameter	Type	Description
indexFilterValue	string	Filters recommendations based on specific indexed values/attributes in your catalog.
searchQuery	string	Incorporates a search term to influence recommendations, returning products related to both the current context and the search.
elements	array	Advanced targeting using CSS-like selectors and values. Each ElementSelector contains a selector (s) and array of values (v).
customerSegments	array	Audience Feed Ids that have been added in the Audience Feed.

Runtime Filters

Runtime filters allow you to narrow down recommendation results at request time without changing your campaign or tactic configuration. Filters are evaluated against each candidate product before the response is returned.

info

Limits: A maximum of 5 filters are evaluated per request — filters beyond the first 5 are ignored. Each filter value must be 50 characters or less — values exceeding this limit are ignored. Filters are applied in the following order: brand → price → ref_id → string_attribute → scalar_attribute.

Filter Operators

Filters follow one of two structures, depending on whether the target field is a string or a numeric value:

String filter — for string fields (brand, ref_id, string_attribute)

Operator	Query syntax	Description
eq	brand[eq]=nike	Exact match (case-insensitive).
in	brand[in]=nike,puma	Includes only products whose value matches one of the listed values.
not_in	brand[not_in]=foo,bar	Excludes products whose value matches any of the listed values.

Scalar filter — for numeric fields (price, scalar_attribute)

Operator	Query syntax	Description
eq	price[eq]=99.99	Exact numeric match.
gte	price[gte]=50	Greater than or equal to.
gt	price[gt]=50	Strictly greater than.
lte	price[lte]=200	Less than or equal to.
lt	price[lt]=200	Strictly less than.

Combining Filter Operators

AND conditions — Multiple operators on the same field are evaluated as AND. For example, price[gte]=50&price[lte]=200 matches only products priced between 50 and 200.

OR conditions — Multiple values inside a single in operator are evaluated as OR. For example, brand[in]=nike,puma matches products from either Nike or Puma.

---

Built-in Filter Parameters

Parameter	Query syntax examples	Description
brand	brand[in]=nike,puma | brand[not_in]=foo	Filter by product brand name.
ref_id	ref_id[not_in]=123,456 | ref_id[in]=789	Include or exclude specific product reference IDs.
price	price[gte]=50&price[lte]=200	Filter by product price. Uses currencyCode when provided; otherwise falls back to the first available price. Applies to the discounted price when a discount is active.

---

Dynamic Attribute Filters

For product attributes beyond the built-ins, use the string_attribute and scalar_attribute dictionaries. The attribute name is specified as part of the query key.

string_attribute (string filter per attribute)

string_attribute[<attributeName>][<operator>]=<value>

Example	Description
string_attribute[category][in]=football,sport	Returns only products in the football or sport category.
string_attribute[color][eq]=red	Returns only products with a color value of red.
string_attribute[color][in]=red,blue	Returns only products with a color value of red or blue.
string_attribute[color][not_in]=black,white	Excludes products with a color value of black or white.

scalar_attribute (RangeFilter per attribute)

scalar_attribute[<attributeName>][<operator>]=<value>

Example	Description
scalar_attribute[rating][gte]=4.5	Returns only products with a rating of 4.5 or higher.
scalar_attribute[weight][lte]=10	Returns only products with a weight value of 10 or less.

---

ElementSelector Format

The elements parameter uses a special format for advanced content selection:

// Example elements parameter structure
elements: [
  {
    s: "category", // Selector
    v: ["mens", "clothing"] // Values
  },
  {
    s: "price-range",
    v: ["100-200"]
  }
]

When making API calls, these would be formatted as query parameters:

&elements[0][s]=category&elements[0][v][0]=mens&elements[0][v][1]=clothing&elements[1][s]=price-range&elements[1][v][0]=100-200

Parameter Usage Examples

Basic Product Detail Page Request

GET https://<PA_END_POINT>/3.0/recommendations?currentUrl=https://www.example.com/product/12345&refId=12345

Language and Currency Specific Request

GET https://<PA_END_POINT>/3.0/recommendations?currentUrl=https://www.example.com&languageTag=fr-FR&currencyCode=EUR

Personalized Recommendations with Cart Context

GET https://<PA_END_POINT>/3.0/recommendations?currentUrl=https://www.example.com&customerId=3fa85f64-5717-4562-b3fc-2c963f66afa6&productsInCart[0]=item1&productsInCart[1]=item2&expandProductDetails=true

Advanced filtering with audience feed IDs

GET https://<PA_END_POINT>/3.0/recommendations?currentUrl=https://www.example.com&customerSegments[0]=3fa85f64-5717-4562-b3fc-2c963f66afa6&customerSegments[1]=8b4fcb98-5b10-4e2a-9c7d-1a2b3c4d5e6f&indexFilterValue=department:electronics

Runtime Filter Examples

Filter by brand (inclusion)

GET https://<PA_END_POINT>/3.0/recommendations?currentUrl=https://www.example.com&brand[in]=nike,adidas

Filter by price range

GET https://<PA_END_POINT>/3.0/recommendations?currentUrl=https://www.example.com&price[gte]=50&price[lte]=200&currencyCode=USD

Exclude specific products from results

GET https://<PA_END_POINT>/3.0/recommendations?currentUrl=https://www.example.com&ref_id[not_in]=123,456,789

Filter by category and minimum rating

GET https://<PA_END_POINT>/3.0/recommendations?currentUrl=https://www.example.com&string_attribute[category][in]=football,sport&scalar_attribute[rating][gte]=4.0

Combine multiple filters

GET https://<PA_END_POINT>/3.0/recommendations
  ?currentUrl=https://www.example.com
  &brand[in]=nike,puma
  &price[gte]=30&price[lte]=150
  &string_attribute[color][not_in]=black