Merchandising & Ranking

The Merchandising & Ranking Engine provides layered control over product ordering while preserving compatibility with existing rule-based merchandising capabilities.

The current architecture supports rule-driven actions (Promote, Bury, Hide, Only Show). For PLPs, this is extended to introduce Pinning as a first-class capability.

Merchandising Controls

Each rule applies one control type that determines how matching products behave within the PLP.

Control Type	Action	Behavior
Only Show	Inclusion	Narrows eligibility only to products matching the conditions
Hide	Exclusion	Removes matching products entirely. Overrides Only Show
Bury	Demote	Products remain eligible but are ranked lower (soft demotion)
Promote	Boost	Products remain eligible but are ranked higher (soft boosting)
Pin	Position	Guarantees exact grid slot or row position

Pinning

Pinning is the most critical merchandising requirement for PLPs. It guarantees that a product appears at an exact grid slot or row position within the collection, independent of ranking calculations.

Why Pinning Is Required

Hero placements — Ensure campaign products appear exactly where intended
Campaign certainty — Rule-based boosts influence probability but do not guarantee outcome
Seasonal priorities — Support contractual and inventory-driven positioning
Merchant expectation — Exact placement control is a primary PLP tool

Pinning Modes

Mode	Description
Slot Pinning	Pin a product to a specific grid position (e.g., position 3)
Row Pinning	Pin a product to appear in a specific row

[!IMPORTANT] Pinned products remain in their designated positions regardless of sort order or other ranking rules. Sorting operates around pinned positions.

Precedence Order

Eligibility is always evaluated before ranking. A product must first "survive" the hard gates before any boosting, burying, or pinning takes effect.

The Processing Pipeline

Hide — Highest priority. If hidden, nothing else matters.
Only Show — Filter logic.
Pin — Exact positional placement.
Promote / Bury — Final ranking adjustments for non-pinned items.

[!NOTE] A product must pass both the Hide and Only Show logic checks before Pin, Promote, or Bury changes are applied.

Rule Examples

Promoting New Arrivals

Boost products with a launch date within the last 30 days:

Promote where Launch Date < 30 days ago

Boosting High-Margin Items

Increase visibility for profitable inventory:

Promote where Margin > 25%

Burying Out-of-Stock Products

Reduce visibility without hiding completely:

Bury where Inventory = 0

Hiding Discontinued Items

Remove products entirely from the PLP:

Hide where Theme = Discontinued

Pinning Hero Products

Guarantee a campaign product appears in the first position:

Pin Product ID = 123456 to Position 1

Application Scope

Merchandising controls can be applied to a wide variety of data points:

Scope	Examples
Catalog Attributes	Themes, margins, inventory levels, ratings
Specific Identifiers	Individual Product IDs (SKUs)
Business Logic	Custom attributes defined in your product feed
Time-Based	Launch dates, last updated timestamps

Layered Strategy Example

A complete merchandising strategy might combine multiple rule types:

Rule Type	Logic	Purpose
Only Show	`Price < $250` AND `Inventory > 0`	Gate: In-stock, affordable items only
Hide	`Margin < 5%` OR `Theme = Discontinued`	Block: Remove unprofitable items
Pin	`Product ID = 999888` to `Position 1`	Hero: Campaign product at top
Promote	`Theme = New Arrival` AND `Margin > 30%`	Boost: High-quality new arrivals rise
Bury	`Inventory < 5` OR `Last Updated > 180 days`	Demote: Old or low-stock items sink

Visual Design Goals

The Playground supports visual merchandising configuration:

Visual slot targeting in a grid preview
Row vs item pinning mode selection
Clear distinction between Pinned and Ranked items

[!TIP] Rules created in the Portal will not be displayed back in Shopify. The Portal is the source of truth for PLP merchandising configuration.

Merchandising & Ranking

On this page