Category

Background Filters

To pre-filter results based on specific product data, the background filter parameter (bgfilter) should be used in Search API Requests and not the filter parameter (filter). Some examples of what fields you can pre-filter search results by could be search_only, availability, on_sale, etc. This allows for our reporting to differentiate between customer applied filters and background filter parameters for pre-filtering results.

Documentation:

Search API - See bgfilter query string parameter
Search API: Filtering Results - use cases

Filtering

Filtering Results

All filtering should be done by making requests to the Search API and using the filter query string parameter. Attempting to handle filtering client side will adversely affect Searchspring’s reporting and merchandising capabilities.

Documentation:

Search API - See filter query string parameter
Search API: Filtering Results - use cases

Rendering Filter Data

The filters displayed on a results page should be displayed in the order they are returned by the Search API in the facets object and be displayed as collapsed or expanded per the Search API response. It is important that the order of the filters follows the order seen in the Search API response. It is also important that the extra data returned for each facet in the API response is implemented as well as that data is used to describe each filters appearance and behavior. This is important as the data found within each facet can be configured within our tool.

Documentation:

Search API - See facets object in the 200 response code below the query string parameters
Filtering - How to configure filters
Merchandising - Custom Filter Order

Sorting

The sorting options displayed on a results page should be displayed in the order they are returned and use the labels returned in the Search API response. When initially loading a page a sort query string parameter should not be passed as part of the API request. This will allow for merchandising rules to be applied to the results.

All sorting should be done by making requests to the Search API, attempting to handle sorting client side will adversely affect Searchspring’s reporting and merchandising capabilities.

Documentation:

Sorting & Pagination
Sorting Options
How Products are Arranged on Search Result Pages
Boosting Rules

Results Per Page

Only the required number of results for the current page should be requested from the Search API. This is used to limit the number of results that should be returned in the API response. All results returned must be rendered.

Documentation:

Sorting & Pagination

Pagination

Your team can choose to utilize traditional pagination or opt to build an infinite scroll feature within your integration. To do this your team can reference the data returned within the pagination object in the API response to build this navigation.

All pagination should be done by making requests to the Search API, attempting to handle pagination client side will adversely affect Searchspring’s reporting and merchandising capabilities.

Documentation:

Sorting & Pagination

User Tracking Parameters

The query string parameters userId, sessionId, pageLoadId, and domain are required for our reporting and personalization features to work properly for API requests.

Documentation:

Search API - see query string parameters userId, sessionId, pageLoadId, domain
Searchspring Cookies

Category Personalization Parameters

The Preflight API endpoint and the Search API query string parameters here are only applicable if the account is signed up and configured for Personalized Search & Merchandising. The first step is to ensure a call to the Preflight API is made when a shopper logs into your website and all relevant data is sent to the endpoint. If any of the relevant data notated in the endpoint changes as the customer is interacting with the website, ensure the new data is sent to the endpoint before a call to the Autocomplete API or Search API endpoints are made so that our system can allow personalization to occur within the returned result sets.

To learn more about the Personalized Search & Merchandising feature and the requirements, please refer to the following documents:

Personalized Search & Merchandising
Can I use Personalized Search & Merchandising?

Query string parameters

shopper
cart
lastViewed

Documentation