# Merchandising Rules

Recommendations come from the engine, but you decide what it may show. The
Merchandising page in the dashboard holds a small set of rules that apply to
every recommendation and trending response, the second you save them:

- **Boost a category, a brand or an attribute value.** Products that match
  rank higher. If the engine's own candidates carry too few of them, the
  widget fills up from your catalog so a boosted brand gets at least half of
  the grid whenever you have matching products in stock. Shown with
  `source: "boost_fill"` on the item.
- **Exclude a category, a brand or an attribute value.** Matching products are
  never shown, in any widget.
- **Pin or hide a single product.** A pinned product goes to the front of
  every response; a hidden one never appears.

Attribute rules take a `name:value` pair, such as `color:red` or `size:xl`,
using the names and values your catalog sends (see `attributes` on
[POST /v1/items](v1-api-reference.md)). A category rule matches the category
name as sent in `categories`.

## What the engine learns on its own

Brand and attributes are also handed to the recommendation engine as item
labels. Its ranker learns each shopper's affinity for them from what that
shopper views and buys, and its look-alike recommender uses shared labels to
suggest similar products even for items with no history yet. That happens
without any rule: rules are for the cases where you want to override what the
data says, for example to push a house brand or to keep clearance out of the
grid.

## Trending by category

The trending widget can be limited to one category with the `data-category`
attribute (or `category=` on `GET /v1/trending`), so a category page shows
what sells in that category. Merchandising rules and the price floor apply
there too, and the fill stays inside the category.

## API

Dashboard sessions manage rules through `/recommender/property-rules`
(`GET`, `POST {field, value, action}`, `DELETE /{id}`) where `field` is
`categories`, `brand` or `attribute_values` and `action` is `boost` or
`exclude`; `/recommender/brands` and `/recommender/attributes` list the
values your catalog carries. Single-product rules live under
`/recommender/merch-rules`.

Store plugins and the Shopify app use the same rules with the secret
`X-API-Key` instead of a login: `GET/POST /integration/property-rules`,
`DELETE /integration/property-rules/{id}`, `GET /integration/brands` and
`GET /integration/attributes` take and return exactly what the dashboard
routes do.

## Shopify

The Shopify app stores each product's vendor and its options (Color, Size,
...) with the product it syncs, so the same brand and attribute rules are
available on the app's Merchandising page without any extra setup. On a
collection page the app's trending block can be limited to the collection
being viewed.
