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	List of customer segment identifiers. Filters/prioritizes recommendations based on segment-specific rules.

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=user123&productsInCart[0]=item1&productsInCart[1]=item2&expandProductDetails=true

Advanced Filtering with Customer Segments

GET https://<PA_END_POINT>/3.0/recommendations?currentUrl=https://www.example.com&customerSegments[0]=premium&customerSegments[1]=frequent-buyer&indexFilterValue=department:electronics