> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a sort order

> Create a sort order in Layers to control how products rank on collection pages, combining metrics, signals, and priority rules into one configurable order.

## Steps

1. Go to **Sort Orders** and click **Create**.
2. Add simple rules (like newest or price) or combine a few signals.
3. Give it a clear name so your team knows when to use it.
4. Save your sort order.

## Sorting attribute types

The **Add Expression** menu offers simple attributes plus several specialized expression types: **Priority Rules**, **Weighted Groups**, **Soft Boost**, **User Affinity**, **Product Family Diversity**, and **Sequence Grouping**. On relevance sort orders, the relevance expression is labeled **Search Relevance**.

### Simple attributes

Sort by product attributes like price, title, or sales metrics. These are the most common sorting rules.

<Note>
  You can attach an **Only when…** condition to any value sort term so products that don't qualify fall through to the next expression instead of ranking on an unreliable signal. See [Conditional sort expressions](/platform/sorting/conditional-expressions) for the full guide. This feature is in Beta.
</Note>

### Priority rules

Boost or demote products matching specific conditions. Priority rules cluster matching products at the top or bottom of results based on their direction setting:

* **Descending direction**: Promotes matching products to the top
* **Ascending direction**: Demotes matching products to the bottom

Layers applies all sort expressions in the order they appear in the sort group. Earlier expressions take higher priority. The position of a priority rule relative to other expressions determines whether it acts as the primary sort or a tiebreaker.

#### Soft demotion

When demoting products in a search context, enable **Soft Demotion** to apply threshold-based relevance demotion. Items above the relevance threshold are immune to demotion, while items below receive proportional demotion.

**When available:**

* Only appears for priority rules on relevance sort orders
* Only applies in search context (not browse)
* Only available for demotion direction (ASC)

**How it works:**

* Items with relevance score >= threshold → immune to demotion
* Items with relevance score \< threshold → proportional demotion based on distance below threshold

**Relevance threshold:**

* **Default**: 0.5 (range: 0-1)
* **Higher threshold (e.g., 0.7)**: Only highly relevant items are immune; more products receive demotion
* **Lower threshold (e.g., 0.3)**: More items are protected; only weak matches receive demotion

**UI control:**

When creating a demotion priority rule on a relevance sort order, a **Soft Demotion** toggle appears. Enable it to reveal a **Relevance Threshold** slider that controls which products are immune to demotion:

1. Enable the **Soft Demotion** toggle
2. Adjust the **Relevance Threshold** slider (0-100, representing 0.0-1.0)
3. The slider displays the current threshold value
4. Items with relevance at or above this threshold are immune to demotion

Falls back to hard demotion in browse context.

**Available operators:**

**Text operators:**

* `equals` / `does not equal` - Exact match
* `contains` / `does not contain` - Partial text matching
* `begins with` / `does not begin with` - Prefix matching
* `ends with` / `does not end with` - Suffix matching
* `in` / `not in` - Match any value in a list (enables multi-select)
* `is null` / `is not null` - Check if attribute has a value (hides value field)

**Numeric operators:**

* `equals` / `does not equal` - Exact numeric match
* `greater than` / `greater than or equal` - Value comparisons
* `less than` / `less than or equal` - Value comparisons
* `between` / `not between` - Range matching (requires two values)
* `in` / `not in` - Match any value in a list (enables multi-select)
* `is null` / `is not null` - Check if attribute has a value (hides value field)

**Date operators:**

* `equals` / `does not equal` - Exact date match
* `after` / `before` - Date comparisons
* `between` / `not between` - Date range matching (requires two values)
* `in the last (days)` - Matches dates within the last N days of now. The window stays current as time passes, so it always tracks a rolling period — useful for "new arrivals" style rules that should follow the calendar without manual updates.
* `is null` / `is not null` - Check if attribute has a value (hides value field)

**Tag operators:**

* `contains` / `does not contain` - Check if tag exists
* `in` / `not in` - Match any tag in a list (enables multi-select)

**Examples:**

**Promote scenario** - Priority rule with descending direction, placed first:

```
1. Priority Rule: vendor equals "Nike" (Direction: Descending)
2. Sort by: Sales (7d) - Descending
```

Result: All Nike products appear first, then remaining products sorted by sales. The priority rule is the primary sort because it is first in the list.

**Demote scenario** - Priority rule with ascending direction, placed after metric:

```
1. Sort by: Title - Ascending
2. Priority Rule: vendor equals "Nike" (Direction: Ascending)
```

Result: Products are primarily sorted by title. Nike products are demoted to the bottom as a tiebreaker since the priority rule is after the primary sort.

**Soft demotion scenario** - Threshold-based demotion in search:

```
1. Sort by: Relevance Score - Descending
2. Priority Rule: tags contains "clearance" (Soft Demotion: enabled, Threshold: 0.6)
```

Result: Clearance items above the 0.6 threshold are immune to demotion. Clearance items below the 0.6 threshold receive proportional demotion based on how far below the threshold they are. Only works in search context.

**Multi-value selection** - Using `in` or `notIn` operators:

When you select the `in` or `notIn` operator in the UI, the UI automatically enables multi-select, allowing you to select multiple values in a single rule.

```
1. Priority Rule: vendor in ["Nike", "Adidas", "Puma"]
2. Sort by: Sales (7d) - Descending
```

Result: All products from Nike, Adidas, or Puma appear first, then other brands sorted by sales.

```
1. Priority Rule: tags in ["featured", "bestseller", "new-arrival"]
2. Sort by: Price - Ascending
```

Result: Products with any of the specified tags appear first, sorted by price, then remaining products.

**Null operators** - Check if attributes are set:

When you select `is null` or `is not null`, the UI automatically hides the value field since these operators check for presence/absence of data.

```
1. Priority Rule: compare_at_price is not null
2. Sort by: Discount Percentage - Descending
```

Result: Products on sale (with compare-at price set) appear first, sorted by discount.

```
1. Sort by: Sales (7d) - Descending
2. Priority Rule: inventory_quantity is null
```

Result: Products with inventory tracking appear first, products without tracking at the bottom.

**Range exclusion** - Using `not between`:

```
1. Sort by: Sales (7d) - Descending
2. Priority Rule: variant_price not between [100, 200]
```

Result: Products priced outside $100-$200 appear first, products in that range at the bottom.

### Weighted groups

Combine multiple attributes and metrics into a single sort score. Each feature contributes a configurable share of the blend, and you choose whether higher or lower values are better on a per-attribute basis. See [Weighted groups](/platform/sorting/weighted-groups) for the full guide.

**Configuration:**

* **Expressions** — the attributes and metrics to blend. Use the picker on each row to choose a feature. A group can contain a single feature, though a blend is most useful with two or more.
* **Preference** (attribute rows only) — **Higher is better** or **Lower is better**. Sets the direction each attribute contributes in. Metric rows default to higher is better.
* **Weight** — a share of 100, controlled with a slider. Layers automatically normalizes weights so they always sum to 100; dragging one slider rebalances the others proportionally.
* **Final Sort Direction** — set in the group settings sheet. Controls how products are ordered by the final blended score (Descending by default).
* **Conditions** — optional contextual conditions in the group settings sheet that gate the entire group. When the conditions don't match a request, the whole weighted group is skipped.

A **Blend preview** appears on hover in the group header, showing how the configured weights divide up the final score.

**Compose with other expressions:**

A weighted group is a first-class base in the sort pipeline. You can drop a [soft boost](/platform/sorting/soft-boost) or [User Affinity](/platform/sorting/user-affinity) row directly below the weighted group, and the modifier attaches to the blended score the same way it would attach to a single attribute or metric.

### Soft boost

Lift products matching conditions toward a target score while maintaining natural ranking. Unlike priority rules, soft boost creates interleaving rather than clustering. Each soft boost appears with a **Modifier** badge and is visually grouped beneath the metric or attribute it modifies. This lets you see at a glance which expression the boost targets.

**Key differences from priority rules:**

* **Natural interleaving**: Boosted products are distributed throughout results based on their base score.
* **Capped lift**: Products are only lifted as far as needed to reach the target band.
* **Requires a target expression**: Soft boost modifies the next metric or attribute in the list.

**Configuration:**

* **Attribute**: The product attribute to check (for example, tags, vendor, options).
* **Operator**: Condition operator (see available operators below).
* **Value**: The value to match (multi-select available for `in` and `notIn` operators, hidden for `is null` and `is not null`).
* **Boost Mode**: Select **Amplify strong performers** (multiplicative, default) or **Lift matches into view** (additive).
  * **Amplify strong performers**: Best for amplifying products that already perform well on the base metric.
  * **Lift matches into view**: Best for products that may not have metric data yet, like new arrivals or restocks. Lifts matched products in value space toward a percentile target on the same metric.
* **Boost Strength**: Intensity of the boost (default: 0.25, range: 0-10).
  * In **Amplify strong performers**, this is the multiplier amplitude.
  * In **Lift matches into view**, this is the fraction of the gap between the base score and the percentile target that gets closed (0 = no lift, 1 = pulls exactly to target, > 1 = overshoots).
* **Percentile Target** (Lift matches into view only): The target value for boosted products, expressed as a percentile of the base metric (default: 50, range: 0-100).
* **Min positions between** (both modes): Minimum number of non-matched products between two consecutive boosted matches in the final results (default: 10, range: 1–50). Prevents clustered matches from landing adjacent. In **Amplify strong performers**, a single match stays put and only clustered matches are spread. In **Lift matches into view**, matches are laid out from the percentile anchor with this stride.

**Available operators for soft boost:**

All the same operators available for priority rules can be used with soft boost, including:

* Text operators: `equals`, `does not equal`, `contains`, `does not contain`, `begins with`, `does not begin with`, `ends with`, `does not end with`, `in`, `not in`, `is null`, `is not null`
* Numeric operators: `equals`, `does not equal`, `greater than`, `greater than or equal`, `less than`, `less than or equal`, `between`, `not between`, `in`, `not in`, `is null`, `is not null`
* Date operators: `equals`, `does not equal`, `after`, `before`, `between`, `not between`, `is null`, `is not null`
* Tag operators: `contains`, `does not contain`, `in`, `not in`

**Example (Amplify strong performers):** Boost products tagged "featured" while sorting by sales:

```
1. Soft Boost: tags contains "featured" (Boost Mode: Amplify strong performers, Boost Strength: 0.5, Min positions between: 10)
2. Sort by: Sales (7d) - Descending
```

**Example (Lift matches into view):** Sprinkle new arrivals with zero sales into best sellers:

```
1. Soft Boost: tags contains "new-arrival" (Boost Mode: Lift matches into view, Boost Strength: 0.6, Percentile Target: 75)
2. Sort by: Sales (7d) - Descending
```

**Example (Multi-value):** Boost products with any of multiple tags using `in` operator:

When you select the `in` or `notIn` operator in the UI, multi-select is automatically enabled.

```
1. Soft Boost: tags in ["featured", "bestseller", "trending"] (Boost Mode: Amplify strong performers, Boost Strength: 0.5, Min positions between: 10)
2. Sort by: Sales (7d) - Descending
```

**When to use Lift matches into view:**

* Boosting products with zero or near-zero base values (new arrivals with no sales)
* Creating a specific target position in the sort order
* "Sprinkling" new products into established rankings

<Warning>
  Soft boost requires a metric or product attribute to modify. If no sortable expression exists yet, an error dialog asks you to add one first. When you add a soft boost, Layers automatically inserts it above the last metric or attribute so that it targets the correct expression.
</Warning>

Learn more about soft boost in the [Soft Boost Sorting documentation](/platform/sorting/soft-boost).

### User Affinity

Personalize browse results for each individual shopper by lifting products that match the tastes Layers learns from that shopper's own cart and purchase history. Like soft boost, User Affinity is a modifier that lifts matching products within the next sort expression below it — so **User Affinity cannot be the last expression** in a sort order; it always requires a following sort attribute to modify. It applies on collection/browse pages only and never demotes.

Learn more in the [User Affinity documentation](/platform/sorting/user-affinity).

### Product Family Diversity

Spread products from the same group across results so a single group doesn't dominate the top of a collection. Add one or more **diversity axes** — each axis caps repeats on a different dimension (product family, product type, vendor, or any categorical attribute). See [Diversity expressions](/platform/merchandising/diversity) for the full set of options. (Previously labeled **Diversity**.)

### Sequence Grouping

Keep related products grouped together according to a configured sequence while the rest of the sort order ranks around them.

## AI-suggested expression names

When you add or edit a sort expression, Layers automatically suggests a short, plain-language label for it based on the attribute, operator, and values you configured. The suggested name appears as the card title in the editor.

**How it works:**

* As soon as you finish editing an expression, Layers sends the configuration to a small language model and replaces the placeholder title with the generated name.
* Names are deterministic for the same configuration and cached, so identical expressions across different sort orders share the same label.
* You can always rename an expression manually by clicking the title — your edit is preserved and won't be overwritten.

**Examples:**

| Expression configuration                                     | Suggested name             |
| ------------------------------------------------------------ | -------------------------- |
| `tags contains "featured"` (priority rule, ascending)        | Demote featured products   |
| `inventory_quantity less than 5` (priority rule, descending) | Promote low-stock items    |
| Sort by `revenue_30d` descending                             | Top revenue (last 30 days) |
| Soft boost on `tags contains "new-arrival"`, additive        | Sprinkle new arrivals      |

<Tip>
  Suggested names make sort orders easier to scan when you have many expressions. They are especially helpful for priority rules and soft boosts, where the configuration alone can be hard to read at a glance.
</Tip>

## Tip

* Start simple. You can refine weights over time.
* Use soft boost for subtle promotion that maintains organic ranking.