API Reference
API Reference

Standard Merchandising

Merchandising campaigns in Searchspring influences what the Autocomplete or Search API would naturally return in the API response based on merchandising changes that are made within the configured merchandising campaign. The following features are included in all Searchspring plan levels.


Merchandising Campaign Types

  • Search: The campaign affects specific search result page(s)
  • Search Contains: The campaign affects any search result page that contains a specific word or phrase
  • Category: The campaign affects category page(s)
  • Mixed: The campaign affects a mix of search result and category pages, or other applied filters

Documentation:



Banners

All banners returned in the merchandising section of the Searchspring API response should be displayed on the results page.


The Searchspring merchandising banners feature allows our clients to configure banners to show in several different positions (header, banner, footer, left) on the page. Banners can be configured to display based on the page the customer is on.


When banner content is configured and the campaign is triggered we will find data returned within the merchandising.content object. Each banner will have it's own distinct key to signify the position of the banner on the page.


📘

Note

Banner content is currently wrapped in a <script> tag due to a legacy feature. This <script> tag is not required and can be removed if desired. A future version of our API will remove this script tag.


{
  "pagination": {...},
  "sorting": {...},
  "resultLayout": "grid",
  "results": [...],
  "facets": [...],
  "breadcrumbs": [],
  "filterSummary": [],
  "merchandising": {
    "redirect": "",
    "is_elevated": [],
    "elevated": [],
    "removed": [],
    "content": {
      "header": [
        "<script data-banner-type=\"html\" data-banner-html=\"<h1>Primary Banner</h1>\" type=\"text/widget\"></script><h1>Primary Banner</h1>"
      ],
      "banner": [
        "<script data-banner-type=\"html\" data-banner-html=\"<h1>Secondary Banner</h1>\" type=\"text/widget\"></script><h1>Secondary Banner</h1>"
      ],
      "footer": [
        "<script data-banner-type=\"html\" data-banner-html=\"<h1>Footer Banner</h1>\" type=\"text/widget\"></script><h1>Footer Banner</h1>"
      ],
      "left": [
        "<script data-banner-type=\"html\" data-banner-html=\"<h1>Left Banner</h1>\" type=\"text/widget\"></script><h1>Left Banner</h1>"
      ]
    },
    "facets": [...],
    "facetsHide": [],
    "experiments": [],
    "variants": [],
    "personalized": false,
    "triggeredCampaigns": [...]
  }
}

Banners returned are usually rendered as a full width banner on the page.

  • header: Primary banner - rendered above results
  • banner: Secondary banner - rendered above results below the Primary banner
  • footer: Footer banner - rendered below results
  • left: Left banner - intended to be rendered below filters that are oriented to the side of the results

Documentation:



Redirects

Any redirect returned within the Search API response for merchandising.redirect should be followed. For API performance, site performance, and automation we highly recommend passing the query string parameter redirectResponse=direct for every Search API endpoint.


The Searchspring redirects feature allows our clients to setup redirects for search requests that they’d like to take the customer directly to a certain page in lieu of displaying a search results page.


Documentation: