API Reference
API Reference

Advanced 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. These features are included in Searchsprings Expert and Advanced plan levels. If you are interested in these features please reach out to your Searchspring Point of Contact for more information.

Inline Banners

📘

Note

If inline banners are configured to be returned they will reduce the number of results returned from the Autocomplete and Search API response to accomodate their positioning on the page. This is so that they can be rendered within the results of the page, will have the same dimensions of a result product card.


Inline banner content is found within merchandising.content.inline as an array of objects in the Autocomplete and Search API response . Each object will contain the banner content within the value key, and the position of the inline banner to be rendered within the results is returned within config.position.index.


📘

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": [],
      "banner": [],
      "footer": [],
      "left": [],
      "inline": [
        {
          "value": "<script data-banner-type=\"html\" data-banner-html=\"<h1>Inline Banner</h1>\" type=\"text/widget\"></script><h1>Inline Banner</h1>",
          "config": {
            "position": {
              "index": 2
            }
          }
        }
      ]
    },
    "facets": [...],
    "facetsHide": [],
    "experiments": [],
    "variants": [],
    "personalized": false,
    "triggeredCampaigns": [...]
  }
}

Documentation:



Landing Page Campaign

To use a landing page merchandising campaign for a landing page on your site, the tag URL parameter for the given page should be implemented to indicate the page is a landing page.


In the integration it should be built to see if the tag URL parameter is passed, if it is then take the value passed to the tag URL parameter and pass it to the Search API endpoint as the value for the landing-page query string parameter. Doing this will allow the Search API to trigger the landing page merchandising campaign and return all configuration changes within the API response to be rendered on the page.


🚧

Warning

Tags must always be:

  • Lowercase
  • Include only letters, numbers, and hyphens
  • Underscores and other special characters are not supported

Otherwise, they will not trigger correctly


Documentation:



Segmented Merchandising Campaign

To use a segmented merchandising campaign for a specific page on your site, the tag URL parameter for the given page should be implemented to indicate the page should trigger a segmented merchandising campaign. The structure of the URL parameter that should trigger a segmented merchandising campaign should be tag=merch.segment/[your-tag-here], where [your-tag-here] is referenced that would be replaced by the tag that is configured for the segmented merchandising campaign.


In the integration it should be built to see if tag=merch.segment/ is present in the URL, if it is then take the entire tag URL parameter tag=merch.segment/[your-tag-here] and pass it to the Search API endpoint. Doing this will allow the Search API to trigger the segmented merchandising campaign and return all configuration changes within the API response to be rendered on the page.


🚧

Warning

Tags must always be:

  • Lowercase
  • Include only letters, numbers, and hyphens
  • Underscores and other special characters are not supported

Otherwise, they will not trigger correctly


Documentation:



A/B Test Merchandising Campaign

Allows you to test and compare up to 5 different variations on a single merchandising campaign, each of which you can make a change using any of Searchspring's Visual Merchandising tools. If the merchandising campaign context is passed to the Search API and the campaign is triggered, then you will be able to view what variation the current user is exposed to within the Search API response by reviewing the content returned within merchandising.experiments.


A/B Testing is available on any campaign type, so you can test across your entire site, on a specific page, or anything in between.


Documentation:



Geographic Merchandising Campaign

Using the IP address of the current shopper on the site will trigger geographic merchandising if a Location based merchandising campaign is configured in the Visual Merchandising tool. Our API will automatically get the IP.


Documentation: