Skip to main content
To promote groups of results dynamically, see Smart Groups.
If typoTolerance is min or strict, promoted results might not appear if they contain more typos than the top results.

​
Promote a single items

For example, a book store wants to recommend a Harry Potter box set whenever the words “Harry Potter” form part of a search.

​
Rule

If the query is Harry Potter, promote the Harry Potter box set.
By default, you can pin up to 300 records per rule.

​
With the API

var response = await client.SaveRuleAsync(
  "ALGOLIA_INDEX_NAME",
  "promote-harry-potter-box-set",
  new Rule
  {
    ObjectID = "promote-harry-potter-box-set",
    Conditions = new List
    {
      new Condition { Pattern = "Harry Potter", Anchoring = Enum.Parse("Contains") },
    },
    Consequence = new Consequence
    {
      Promote = new List
      {
        new Promote(new PromoteObjectID { ObjectID = "HP-12345", Position = 0 }),
      },
    },
  }
);

​
With the Visual Editor

  1. Go to the Algolia dashboard and select your Algolia application.
  2. On the left sidebar, select Search.
  3. Select your Algolia index.
  4. Select Rules from the left sidebar.
  5. Select Create your first Rule or New rule.
  6. Click Visual Editor.
  7. Under Conditions:
    1. Click Set query condition(s).
    2. In Your search, type Harry Potter and click Apply.
  8. Under Consequences:
    1. Click Pin items.
    2. In Pinned items, find and select the item you want to promote (for example, HP-12345) and click Apply.
  9. Review and Publish your rule.

​
With the Manual Editor

  1. Go to the Algolia dashboard and select your Algolia application.
  2. On the left sidebar, select Search.
  3. Select your Algolia index.
  4. Select Rules from the left sidebar.
  5. Select Create your first Rule or New rule.
  6. Click Manual Editor.
  7. In the Condition(s) section, enter Harry Potter in the Query field.
  8. In the Consequence(s) section:
    1. Click Add consequence and select Pin an item.
    2. Find and select the item you want to promote. For example, HP-12345.
  9. Save your rule.

​
Promote the newest release

For example, you’ve placed “best-selling items” at the top of your search results by using custom ranking. But the newest release? Set up a rule that promotes the newest iPhone for searches containing iPhone, while keeping other phones sorted by most-sold.

​
Rule

If query is iphone, promote the newest iPhone release.

​
With the API

var response = await client.SaveRuleAsync(
  "ALGOLIA_INDEX_NAME",
  "Promote-iPhone-X",
  new Rule
  {
    ObjectID = "Promote-iPhone-X",
    Conditions = new List
    {
      new Condition { Pattern = "iPhone", Anchoring = Enum.Parse("Contains") },
    },
    Consequence = new Consequence
    {
      Promote = new List
      {
        new Promote(new PromoteObjectID { ObjectID = "iPhone-12345", Position = 0 }),
      },
    },
  }
);

​
With the Visual Editor

  1. Go to the Algolia dashboard and select your Algolia application.
  2. On the left sidebar, select Search.
  3. Select your Algolia index.
  4. Select Rules from the left sidebar.
  5. Select Create your first Rule or New rule.
  6. Click Visual Editor.
  7. Under Conditions:
    1. Click Set query condition(s).
    2. In Your search, type iPhone and click Apply.
  8. Under Consequences:
    1. Click Pin item.
    2. In Pinned items, find and select the item you want to promote (for example, iPhone-12345) and then click Apply.
  9. Review and Publish your rule.

​
With the Manual Editor

  1. Go to the Algolia dashboard and select your Algolia application.
  2. On the left sidebar, select Search.
  3. Select your Algolia index.
  4. Select Rules from the left sidebar.
  5. Select Create your first Rule or New rule.
  6. Click Manual Editor.
  7. In the Condition(s) section, enter iPhone in the Query field and change the drop-down from Is to Contains.
  8. In the Consequence(s) section:
    1. Click Add consequence and select Pin an item.
    2. Find and select the item you want to promote (for example, iPhone-12345).
  9. Save your rule.

​
Promote several results

For example, you’re running a promotion on the newest Apple products. Set up a rule that promotes the newest Apple releases at the top of results for searches containing apple.

​
Rule

If query is apple, promote the newest Apple releases.

​
With the API

var response = await client.SaveRuleAsync(
  "ALGOLIA_INDEX_NAME",
  "Promote-Apple-Newest",
  new Rule
  {
    ObjectID = "Promote-Apple-Newest",
    Conditions = new List
    {
      new Condition { Pattern = "apple", Anchoring = Enum.Parse("Is") },
    },
    Consequence = new Consequence
    {
      Promote = new List
      {
        new Promote(
          new PromoteObjectIDs
          {
            ObjectIDs = new List { "iPhone-12345", "watch-123" },
            Position = 0,
          }
        ),
      },
    },
  }
);

​
With the Visual Editor

  1. Go to the Algolia dashboard and select your Algolia application.
  2. On the left sidebar, select Search.
  3. Select your Algolia index.
  4. Select Rules from the left sidebar.
  5. Select Create your first Rule or New rule.
  6. Click Visual Editor.
  7. Under Conditions:
    1. Click Set query condition(s).
    2. In Your search, type apple and click Apply.
  8. Under Consequences:
    1. Click Pin items.
    2. Click Pin multiple items.
    3. One per line, enter the object IDs of the items you want to pin, for example, iPhone-12345 and watch-123, in the input field and then click Pin items.
    4. Click Apply.
  9. Review and Publish your rule.
You can’t promote more than one item with the Manual Editor.

​
Promote results matching active filters

#For example, you only want to promote items if they match the user’s active filters, such as stock availability, color, or category. This prevents irrelevant items such as out-of-stock products from appearing.

​
Rule

Create a rule with a consequence that pins the item only if it matches active filters.

​
With the API

To pin an item only if it matches active filters, set filterPromotes to true in the rule’s consequence. 
var rule = new Rule
{
    ObjectID = "rule_with_filterPromotes",
    Conditions = new List<Condition>
    {
      new Condition { Anchoring = "is", Pattern = "{facet:brand}" },
    },
    Consequence = new Consequence
    {
        FilterPromotes = true,
        Promote = new List<ConsequencePromote>
        {
            new ConsequencePromote {ObjectID = "promoted_items", Position = 0}
        }
    }
};

​
With the Visual Editor

  1. Go to the Algolia dashboard and select your Algolia application.
  2. On the left sidebar, select Search.
  3. Select your Algolia index.
  4. Select Rules from the left sidebar.
  5. Select Create your first Rule or New rule.
  6. Click Visual Editor.
  7. Under Conditions:
    1. Click Set query condition(s).
    2. In Your search, enter the item you want to promote (for example, shoes) and click Apply.
  8. Under Consequences:
    1. Click Pin items.
    2. In Pinned items, find and select the item you want to promote.
    3. Keep the checkbox Pinned items must match active filters to be displayed selected and click Apply.
  9. Review and Publish your rule.

​
With the Manual Editor

  1. Go to the Algolia dashboard and select your Algolia application.
  2. On the left sidebar, select Search.
  3. Select your Algolia index.
  4. Select Rules from the left sidebar.
  5. Select Create your first Rule or New rule.
  6. Click Manual Editor.
  7. In the Condition(s) section, enter the query (for example, shoes) in the Query field.
  8. In the Consequence(s) section:
    1. Click Add consequence and select Pin an item.
    2. Find and select the item you want to promote (for example, brogue-12345).
  9. In the Additional settings section, keep the checkbox Pinned items must match active filters to be displayed selected.
  10. Save your rule.
⌘I