API Reference
API Reference

Personalized Recommendations

When using Personalized Recommendations sourced from the Personalized Recommendations API endpoint, it is required to also send Beacon events so that our personalization engine can compile and generate personalized products to the specific customer(s) as the site is traversed and when the website is revisited.

🚧

In order to allow personalization to function, product/pageview and order/transaction Beacon events must be setup prior to implementing Personalized Recommendations or Personalized Search & Merchandising.

This feature does require a plan upgrade, please reach out to your Searchspring Point of Contact for more information.

📘

Note Personalized Recommendations are available via both GET and POST endpoints. We recommend using POST as the primary method to ensure better handling of complex request bodies.

Profile Tags

The tags parameter is required for GET requests and identifies which recommendation profile(s) configured in the Searchspring Management Console should return results. Multiple profiles can be requested by passing a comma-separated list of profile tags. Each profile tag corresponds to a unique profile configuration.

For POST requests, profile tags are specified within the profiles array in the request body along with profile-specific parameters.


Documentation:



Products Parameter

The products parameter should be passed as a comma-separated list of product IDs or SKUs currently being viewed by the shopper. This parameter is required for recommendation profiles that use cross-sell or similar recommendation types and is recommended for all requests made on Product Detail Pages (PDPs).

While this will often be a single value on a PDP, it could contain multiple values on pages like wishlists or product bundles.


Documentation:



Blocked Items

If there are products already displayed on the page that should not be returned by the Recommendations API, use the blockedItems parameter. This accepts a comma-separated list of product IDs or SKUs to exclude from the results. This is useful when you have curated products or other recommendations already shown on the page.

For POST requests, blockedItems can be specified at the top level (affects all profiles) or within individual profile configurations (affects only that profile).


Documentation:



Limits

The limits parameter controls the maximum number of products returned by each recommendation profile. For GET requests, pass a comma-separated list of integers corresponding to each profile tag in order. For POST requests, specify the limit parameter within each profile configuration.

If no limit is defined, the default is 20 products per profile.

❗️

Note There is an additional limit of 20 recommendation profiles per batch. If the profile limit is exceeded the Recommendations API will respond with an error of 400 bad Request

Documentation:



Filtering

Filtering Recommendations

The filter parameter can be used to filter the recommended products being returned. A field must have the Recs Filter column selected in the Field Settings page in the Searchspring Management Console in order to be used for filtering.

For GET requests, use the format filter.[field]=[value] (e.g., filter.color=blue). For range filtering on numerical values, append .low and/or .high after the field name (e.g., filter.price.low=2&filter.price.high=120).

For POST requests, filters can be specified at the top level (affects all profiles) or within individual profile configurations using an array of filter objects with field, type, and values properties.

⚠️

Important: Because the data science only creates a limited number of recommendations for each product, filtering has a high chance of filtering out all recommendations. This is best used when showing nothing is better than showing the wrong product.


Documentation:



Category & Brand Trending

When using Category Trending or Brand Trending recommendation profiles, you must specify which categories or brands you want recommendations for using the categories or brands parameters respectively.

For GET requests, pass comma-separated lists. For POST requests, pass arrays of category IDs or brand names within the profile configuration.


Documentation:



Personalization Parameters

The shopper, cart, and lastViewed parameters are used to enable personalized recommendations based on the shopper's behavior and history. These parameters help curate recommended products as the shopper navigates the site.


Shopper ID

The shopper parameter should contain the ID of the currently logged-in shopper from your ecommerce platform. This is required for personalization based on shopper history. If the shopper is anonymous (not logged in), this parameter should be omitted.


Cart

The cart parameter should contain a comma-separated list (or array for POST requests) of product IDs or SKUs currently in the shopper's cart. This parameter is required for cart cross-sell recommendations and helps curate recommendations based on what the shopper intends to purchase.


Last Viewed

The lastViewed parameter should contain a comma-separated list (or array for POST requests) of product IDs or SKUs the shopper has recently viewed. List the most recently viewed product first. This parameter is required to curate recommended products as the shopper navigates the site.


Documentation:


Beacon Tracking

Personalized Recommendations require tracking events to capture shopper interactions with the recommendation widgets. This includes tracking when recommendations are rendered, which products are viewed (impressions), and when items are clicked or added to cart. These events are critical for the personalization engine to learn and improve recommendations. For complete implementation details and event requirements, see the Recommendations Tracking Guide.

IMPORTANT: When using the Beacon 2.0 tracking system, you must include the beacon=true parameter in your Recommendations API requests. This enables automatic tracking event generation by the API.

beacon Parameter

Set beacon=true in your Recommendations API requests to enable the new Beacon tracking system. This tells the API to generate an auto-beacon event that is sent to the tracking system automatically.

For GET requests, add beacon=true as a query parameter:

https://{siteId}.a.searchspring.io/boost/{siteId}/recommend?tags=similar&products=123-ABC&beacon=true&...

For POST requests, include beacon: true in the request body:

{
  "products": ["123-ABC"],
  "beacon": true,
  "profiles": [...]
}

test Parameter

Set test=true to mark events as test events during development and testing. This prevents the tracking system from processing the event as a real user interaction, ensuring your test data doesn't skew analytics and reporting.

For GET requests:

https://{siteId}.a.searchspring.io/boost/{siteId}/recommend?tags=similar&products=123-ABC&beacon=true&test=true&...

For POST requests:

{
  "products": ["123-ABC"],
  "beacon": true,
  "test": true,
  "profiles": [...]
}

Updated 2 months ago

Updated 2 months ago