API Reference
API Reference

Category Result Pages

When integrating our product on your Category or Collection pages your team will utilize the Category API endpoint with the background filter parameter (bgfilter) to pre-filter a specific result sets based on indexed product data.

Category



Background Filters

To pre-filter results based on specific product data, the background filter parameter (bgfilter) should be used in Category API Requests and not the filter parameter (filter). The bgfilter parameter is required to define the category scope. Some examples of what fields you can pre-filter category results by could be collection_handle, category_hierarchy, 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:





Filtering

Filtering Results

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



Documentation:





Rendering Filter Data

The filters displayed on a results page should be displayed in the order they are returned by the Category API in the facets object and be displayed as collapsed or expanded per the Category API response. It is important that the order of the filters follows the order seen in the Category 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:





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 Category 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 Category API, attempting to handle sorting client side will adversely affect Searchspring's reporting and merchandising capabilities.



Documentation:





Results Per Page

Only the required number of results for the current page should be requested from the Category 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:





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 Category API, attempting to handle pagination client side will adversely affect Searchspring's reporting and merchandising capabilities.



Documentation:





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.

  • userId will receive its value from the ssUserId cookie
  • sessionId will receive its value from the ssSessionId cookie
  • pageLoadId will be a randomly generated UUID v4 value. This should be updated with every physical page load. If the integration is a Single Page Application(SPA) or Headless, this value will change for every URL route change.
  • domain will receive its value from the current page URL. This shouled be sourced from window.location.href



Documentation:





Category Personalization Parameters

The Preflight API endpoint and the Category 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 Category 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:



Query string parameters

  • shopper
  • cart
  • lastViewed



Documentation



Beacon Tracking

Category pages require tracking events to capture shopper interactions with the search results, filters, and products. This includes tracking when results are rendered, which products are viewed (impressions), and when items are clicked or added to cart. For complete implementation details and event requirements, see the Category Tracking Guide.

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

beacon Parameter

Set beacon=true in your Category 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.

Example:

https://{siteId}.a.searchspring.io/api/search/category.json?siteId=abc123&beacon=true&bgfilter=...



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.

Example:

https://{siteId}.a.searchspring.io/api/search/category.json?siteId=abc123&beacon=true&test=true&bgfilter=...

Updated 5 months ago

Updated 5 months ago