Concepts: how the custom order works

This page explains the ideas behind Product Sorting: why the canvas looks the way it does, what happens to products you haven't placed, and how sales channels share or split an order. You don't need it to use the plugin, but it answers most "why does it do that?" questions.

Tiles, not products

A storefront listing is made of tiles. A tile isn't always one product. Shopware groups products into tiles by their display group, and the product's display mode (its Storefront presentation setting) decides how variants become tiles:

Product	Tiles on the storefront
Simple product without variants	One tile
Variant product shown as a single product (parent)	One tile
Variant product shown as its main variant	One tile
Variant product with expanded property values, such as expanded by colour	One tile per expanded value: a red tile, a blue tile, …

The canvas shows exactly these tiles, never one row per product or per variant. A T-shirt expanded by colour shows up as one tile per colour, each with its own image, so you can put the red one first and the blue one third. Each tile shows the representative product, the same product the storefront shows on that tile.

This is tile parity: the canvas and the storefront listing of the previewed sales channel show the same tiles in the same order. It works because the canvas isn't a copy of the storefront logic. It asks Shopware's own listing for the category, the same one the storefront uses, for one concrete sales channel. That's why:

• you always preview a specific preview channel. Visibility, availability and language differ per sales channel, and so can the tiles;
• inactive or unavailable products aren't on the canvas, because shoppers can't see them either;
• the preview shows what a guest sees. Prices from rules tied to a logged-in customer or customer group don't apply to it, so a price-based fallback sorting can look different for such customers.

The canvas uses a four-column grid like a typical storefront. The column count doesn't matter: parity means the same tiles in the same order, not the same layout.

One order, two parts

A category's custom order is one order, but it's built from two parts:

1. Pinned products. These are the products you placed. They hold fixed slots at the top of the listing, 1, 2, 3 … in your order. Together they form the pinned prefix.
2. Everything else. This is the rest of the listing, sorted by the fallback sorting: the sales channel's default sorting, such as Topseller, newest or price. This part is called the flow.

Most merchants care about the first one or two rows of a category. With this model you pin a dozen products and let the fallback sorting carry the other 800, instead of hand-ordering all of them. It also keeps catalogue changes painless:

• New products join by themselves. A new product isn't pinned, so it enters the flow at the place the fallback sorting gives it. Imports don't need any re-sorting.
• Nothing needs refreshing. Your placements are stored as a small overlay on the live listing, not as a snapshot of it. Stock changes, re-indexing and cache clears change the flow, and your pins stay where they are.

When you drop a tile at slot 5, the tiles in slots 1–4 are pinned where they are too. Without that, the fallback sorting could reorder the tiles above your product, and slot 5 would no longer be slot 5. The canvas doesn't draw a line between pinned products and the flow. You see one order and drag it into shape.

Move to bottom is the opposite of pinning. It sends a product below the flow, to the very end of the listing, without hiding it. Back to automatic position returns a product to the flow in either case.

Positions follow the tile, not the product ID

Pins are stored by display group, the same key the storefront groups tiles by. This is why an order survives product edits, imports, re-indexing and Shopware updates that change how the key is calculated.

It also means a pin belongs to a tile. If you change a product's display mode, for example from main variant to expanded by colour, the old tile no longer exists and its pin becomes stale (see below). Pin the new tiles where you want them.

Stale pins

A stale pin is a placed product that's no longer part of any listing its order applies to. The product may have been deleted, deactivated or removed from the category, or its display mode changed.

Stale pins are ignored on the storefront, but the plugin doesn't delete them automatically. A product that's temporarily deactivated, such as a seasonal item, gets its slot back when it returns. Instead, the Sorting tab reports them and offers Clean up, which removes only the stale ones. See Clean up products that left the listing.

For the shared order, "stale" is judged across every sales channel that serves it. A product missing from the channel you're previewing but still listed in another channel isn't stale, just not visible here. It's never removed.

Shared order and channel orders

Every category has one shared order, which applies to all sales channels. A sales channel can also have its own channel order. Which of the two you're editing is the scope.

• A sales channel without its own order inherits the shared order. On the canvas it's shown read-only, like an inherited setting elsewhere in the Shopware Administration.
• Unlinking a channel copies the shared order into a new channel order. From then on the two are independent.
• Linking the channel again deletes its own order, and it inherits the shared order once more.

A channel order is a copy, not a set of changes layered over the shared order. A layered model sounds flexible, but on a canvas it's impossible to follow: moving one shared product would shift another channel's slots in ways nobody could predict. With copies, every canvas is a plain list that its owner fully controls.

You edit the shared order under All Sales Channels. The canvas still has to show some concrete listing, so it previews the shared order through one of your sales channels, preferably a storefront that carries the category. Products that channel doesn't sell keep their slots and are counted as "Positioned but hidden in this channel".

The Recommended sorting option

On the storefront, the custom order is one extra sorting option, Recommended (German: Empfohlen). It never replaces or edits your other sortings:

• It's only offered on categories whose custom order is active. Everywhere else the dropdown is unchanged.
• By default a category with an active custom order opens in it. A default sorting chosen explicitly in the category's layout takes precedence. Both are covered in Configure the storefront sorting.
• Shoppers can still choose price, name or any other sorting.
• It's managed by the plugin, so it doesn't appear in the Shopware sorting settings. You rename it in the plugin configuration.

The same order is served on MySQL and Elasticsearch/OpenSearch, on the storefront and through the Store API (order=ssd-product-sorting), in manually assigned categories and in categories filled by a dynamic product group. Saving an order refreshes the category's cached pages right away.

Glossary

Term	Meaning
Custom order	The order you define for a category. Switched on per category with Custom order active.
Tile	One box in the storefront product listing. It represents a display group, not necessarily one product.
Display group	Shopware's grouping key for listing tiles. Positions are stored by it.
Display mode	A product's Storefront presentation setting, which decides how its variants become tiles.
Representative product	The product whose data a tile shows.
Preview channel	The sales channel whose listing the canvas shows.
Tile parity	The canvas and the storefront listing of the preview channel show the same tiles in the same order.
Pin / slot	A placed product holds a fixed slot (a 1-based position). The admin calls these positioned products.
Pinned prefix	All pinned products together, occupying slots 1 … k at the top of the listing.
Fallback sorting	The sales channel's default sorting. It orders everything after the pinned prefix.
Flow	The products that aren't pinned, in fallback-sorting order. New products join it automatically.
Scope	Which order you're editing: the shared order or a sales channel's own order.
Stale pin	A pinned product that's no longer part of any listing its order applies to.
Recommended	The storefront name of the custom order's sorting option. German: Empfohlen.