Place sponsored products in search results

This guide shows how to inject sponsored products at fixed positions in your using a Smart Group. The example below uses a Recommend trending-items model as the source, but the same pattern works with search or external sources. The steps walk through both the API and Merchandising Studio paths.

Before you begin, review the Composition API requirements.

API

Create the composition with the Update and insert composition endpoint, then apply the behavior defined below. To scope the behavior to a specific , category, or context, send the same behavior inside a composition rule’s consequence.behavior with the Update and insert composition rule endpoint.

1. Configure the main organic results

   Set the main organic results to your products index. To narrow them to in-stock items, add a filter on the inStock attribute:

   JSON

   {
     "behavior": {
       "injection": {
         "main": {
           "source": {
             "search": {
               "index": "products",
               "params": {
                 "filters": "inStock:true"
               }
             }
           }
         }
       }
     }
   }
   
2. Add a recommend Smart Group of trending items

   Add a Smart Group by appending an entry to injection.injectedItems, using source.recommend to populate it from the trending-items Recommend model. The position and length fields control where the group appears in your organic results and how many items it includes.

   JSON

   {
     "behavior": {
       "injection": {
         "main": {
           "source": {
             "search": {
               "index": "products",
               "params": {
                 "filters": "inStock:true"
               }
             }
           }
         },
         "injectedItems": [
           {
             "key": "trending-products",
             "source": {
               "recommend": {
                 "indexName": "products",
                 "model": "trending-items",
                 "threshold": 50,
                 "queryParameters": {
                   "filters": "inStock:true"
                 }
               }
             },
             "position": 0,
             "length": 4
           }
         ]
       }
     }
   }
   

Merchandising Studio

1. Open the Composition Rule Editor

   In the Merchandising Studio, go to Merch tools > Compositions > Composition Rules, select your composition, and click + New Composition Rule.

2. Add a Smart Group

   In the rule editor, click + Add Group.

   
3. Choose the data source

   By default, the Smart Group is populated from your composition’s Algolia . To populate it from a Recommend model instead (for example, Trending items), choose Recommend.

4. Filter by new arrivals

   If using your Algolia index as the source, add a filter where the New_in attribute is true.

   The New_in attribute must be declared in attributesForFaceting so it can be used for filtering.

5. Review and publish

   Select Review & publish to apply the rule.

Sorting strategy

Sort the organic results by price in descending order, while keeping the sponsored products in place.

JSON

{
  "behavior": {
    "sortingStrategy": {
      "Price descending": "products_price_descending"
    },
    "injection": {
      "main": {
        "source": {
          "search": {
            "index": "products",
            "params": {
              "filters": "inStock:true"
            }
          }
        }
      },
      "injectedItems": [
        {
          "key": "trending-products",
          "source": {
            "recommend": {
              "indexName": "products",
              "model": "trending-items",
              "threshold": 50,
              "queryParameters": {
                "filters": "inStock:true"
              }
            }
          },
          "position": 0,
          "length": 4
        }
      ]
    }
  }
}

See also

• Smart Groups
• Search-based groups
• External source groups
• Recommend-based groups
• Composition REST API reference