Schedule a promotion for a limited time

Combine a query condition with a time window to run a campaign pin automatically and expire it without manual cleanup.

Campaigns rarely run forever. A summer sale landing page, a holiday banner, or a product launch should appear at the top of results for a precise window and then disappear without anyone needing to remember to delete the rule. Time conditions pair a query condition with a start and end timestamp, so the rule only applies inside that window.

Search rules are experimental. Enable the dynamicSearchRules flag with PATCH /experimental-features before creating rules. See Getting started.

Example scenario

Your e-commerce team runs a summer sale from June 1 to June 30. During that window, whenever a user’s query contains “summer sale”, you want to pin the summer-sale-landing-page document (in the products index) at the top of the results. Outside that window, the rule must not fire at all, even if the query still contains “summer sale”.

One rule with two conditions (query + time) and one pin action covers this.

Set up from the Meilisearch Cloud dashboard

Open your project in the Meilisearch Cloud dashboard and select the Search rules tab.

1. Create a new rule

Click New rule. Give it a Rule ID such as summer-sale-2026, add a description noting the campaign dates, and keep the Active toggle on. You can leave Priority at 0 unless another rule competes for the same query.

2. Add the query condition

In the Conditions block, click Add condition and pick Query contains. Enter summer sale as the substring. Click Add condition to save.

Because contains is a case-insensitive literal substring match, the rule also fires for “Summer Sale”, “SUMMER SALE discount”, and “buy during the summer sale”. It does not fire for “summer” or “sale” on their own.

3. Add the time condition

Click Add condition again and pick Time window. Enter:

• Start: 2026-06-01T00:00:00Z
• End: 2026-06-30T23:59:59Z

Timestamps are in UTC. Convert your campaign’s local time window before entering them (for example, 2026-06-01T00:00:00-04:00 in New York becomes 2026-06-01T04:00:00Z in UTC).

Click Add condition to save.

The Conditions block now shows two entries. Both conditions are combined with AND, so the rule only fires when the query matches and the current time is inside the window.

4. Pin the campaign page

In the Actions block, click Add pin:

• Index: products
• Document: summer-sale-landing-page
• Position: 0

Click Add pin to save.

5. Save the rule

Click Create rule. The rule now appears in the Search rules list. Before June 1 and after June 30, the rule still exists but stays silent because the time condition never matches.

Set up from the API

Send a PATCH /dynamic-search-rules/summer-sale-2026:

{
  "description": "Promote the summer sale landing page during June 2026",
  "active": true,
  "conditions": [
    { "scope": "query", "contains": "summer sale" },
    { "scope": "time", "start": "2026-06-01T00:00:00Z", "end": "2026-06-30T23:59:59Z" }
  ],
  "actions": [
    {
      "selector": { "indexUid": "products", "id": "summer-sale-landing-page" },
      "action": { "type": "pin", "position": 0 }
    }
  ]
}

• scope: "time" takes a start and an end timestamp in ISO 8601 UTC format.
• You can omit either start or end to create an open-ended window. For example, a rule with only end expires at that date but applies immediately. A rule with only start activates at that date and never expires until you remove it.
• Multiple conditions are combined with AND. You cannot express “this query between these dates OR that query between other dates” in a single rule, create two rules with different uid values instead.

How Meilisearch evaluates the rule

On every search request, Meilisearch:

1. Reads the current UTC time from the server
2. Checks each active rule. For a rule with a time condition, it verifies that the current time is between start and end
3. If any condition in the rule fails, the rule is skipped for this request
4. Otherwise, the rule fires and the pin is inserted

The check happens at search time, not at rule creation time. There is no scheduler to configure and no background job to monitor: a rule that starts tomorrow simply stays silent today and starts firing tomorrow.

Variations and tips

• Always-on promotions with an expiry safety net: if you want a rule to fire immediately but still auto-expire, set start in the past (or omit it) and end to the cutoff date. This is a good pattern for time-limited editorial pushes that you want to guarantee will disappear.
• Overlapping campaigns: if two rules target similar queries during overlapping windows, set different priority values so the winner is deterministic. Lower numbers win.
• Timezones and daylight saving: always convert to UTC. Relying on local time in the stored timestamps causes subtle bugs across daylight-saving transitions.
• Deleting versus pausing versus expiring: you can let the time window expire naturally (simplest), flip active to false to stop it early without deleting (see Pause a rule), or DELETE the rule entirely if you never want to reuse it.
• Auditing upcoming promotions: use POST /dynamic-search-rules with a uid pattern filter to find every scheduled rule before a campaign starts. See List or filter existing rules.

Next steps

Pin one result for a query

Build a rule without a time window

List or filter existing rules

Review the rules that will fire or expire soon

Pause a rule

Stop a rule early without deleting it

Pinning behavior

Learn how pins interact with ranking, filters, and precedence

API reference

Full request and response shapes