Skip to content

Core Concepts ​

The handful of words Shaped Recommend uses precisely. Learn them once and every screen reads the way it's meant to.

The plugin uses a small, deliberate vocabulary. The same words show up in the builder, on the Analytics screen and in these docs, and they always mean the same thing. This page is the reference. If a screen ever confuses you, it's usually because two of these words have got mixed up.

Recommendation ​

One block you've decided to show shoppers: which products go in it, where it sits, how it looks, and when it appears.

"Products from the same category as the one being viewed, after the product tabs, as a grid" is one Recommendation. So is "a single upsell on the thank-you page for orders over $30".

You build each one on a single screen, the builder, in three tabs:

TabDecides
SetupWhich page it reasons from, the exact spot on that page, and which products qualify and in what order.
DesignHow the block looks: the display style, the heading, how many products, and the columns.
Display ConditionsWhether the block shows at all for this shopper, right now.

Placement (Deployment) ​

Where and how a Recommendation appears: one position on the page, one display, and its conditions.

In this release, every Recommendation has exactly one placement. To show the same idea in two places, say a grid on the product page and a list in the cart, make two Recommendations. The quickest way is Duplicate on the All Recommendations list.

You'll see the word Deployment in developer docs, exports and the REST API. It means the same thing as placement.

Show On (context) ​

The page the Recommendation reasons from, and so where it's allowed to go.

Show On is the first control on the Setup tab, drawn as a row of tiles:

Show OnReasons fromTier
ProductThe product the shopper is viewingFree (default)
CategoryThe category or tag archive being viewedFree
CartWhat's in the cart. Also serves the checkout page, because the order doesn't exist yet thereFree
Thank YouThe order that was just placedPro
AnywhereThe whole catalogue, not tied to any page. Placed by shortcodePro

Developer docs call this the context. The plugin never guesses it from the page. You pick it, and that's what makes a shortcode placement work: a Cart Recommendation knows it needs a cart, even when you drop its shortcode onto some other page.

If you change Show On on a Recommendation that's already live, the builder asks first (Change what this recommendation reads?). Any filters, sorts or conditions the new page can't use are removed, not left there silently doing nothing.

How Products Are Chosen (selection method) ​

How the starting list of products is built, before filters narrow it and sorting puts it in order.

  • Rules (the default): You set the filters and the sorting below. This works from day one on any store.
  • Store Statistics Pro: Mined from your real orders. It ranks products by what your shoppers actually buy together.

If Store Statistics doesn't have enough order history yet, it falls back to Rules automatically. The shopper sees a normal block, with no error and no empty space. See Store Statistics.

It's called "signal source" in developer docs

In the code and the developer reference, this is the signal source. On screen, the control is labelled How Products Are Chosen. They're the same thing.

Filters ​

Which products are allowed into a block.

There are two modes:

  • Automatic (the default). The page picks a sensible set of products for you and says what it is: Same Category & Tags on a product page, From This Category & Tags on an archive, Pairs With The Cart in the cart, Complements The Order on the thank-you page, Best-sellers for Anywhere. Turn on Additional Filters to narrow that set further. Your filters add to the automatic set. They don't replace it.
  • Choose Specific Filters: you build the set yourself.

Free includes Category, Tag, On Sale, In Stock, Featured and Price. Pro adds Brand, Attribute, Min Rating, Relative Price, Recently Viewed, Exclude Cart Items and Exclude Purchased.

Filters sit in groups. A product has to match every group (Add AND Group). Inside a group, a product only has to match one of the rows (Add OR Condition, Pro). Inside a single row, the values are alternatives: Category Is Any Of [Beans] [Mugs] means either one.

Full reference: Setup → Filters.

Sorting ​

The order the qualifying products appear in.

You can add several sorting rules, and the plugin blends them into one order. Each rule counts equally, and there are no weights to tune. You decide the order by choosing which rules apply. A product that a rule can't measure, like a product with no reviews under Rating, gets a middle score, not the bottom one. So blending Rating with Popularity keeps review-less products mixed in, instead of dumping them at the end.

Two of the sorts come from purchase data: Frequently Bought Together (free, and never locked) and Others Also Bought (Pro). That's where the "what sells together" intelligence lives. There's no separate "engine" to configure.

Full reference: Setup → Sorting.

Position On Page (location) ​

The exact spot on the page where the block sits.

Positions read as Page · Spot: Product page · After tabs, Cart · After totals, Thank-you · After details. Fifteen ship in this release: ten in Free and five more in Pro. The builder only offers the ones that suit your Show On choice. The others are greyed out and marked not available on this page, not hidden.

Two positions aren't on any particular page: Custom placement · Shortcode and Custom placement · Block. Use them to put a block anywhere at all.

Developer docs call this the location. Full list: Locations.

Display Style ​

How the block looks.

Free has Grid and Inline list. Pro adds Bundle box, Single-offer card and Popup. A display never changes which products are recommended, only how they're drawn. So if you switch a grid to a list, you get the same products in a different layout.

Full list: Displays.

Display conditions ​

Rules for whether the block shows at all, and to whom.

They live on the Display Conditions tab, under Only show this recommendation when the conditions match. With no conditions, this block is always shown.

Free includes the Device condition: Is Mobile, Is Desktop or Is Tablet. Pro adds Cart Total (Order Total on the thank-you page), Visitor, Schedule and Viewing Category, and lets you combine them with AND / OR.

Conditions are checked on the server and fail closed. If the plugin can't evaluate a condition, the block doesn't show. A missing block is better than an offer shown to the wrong shopper.

Developer docs call these visibility conditions. Full reference: Display Conditions.

Filters vs display conditions: the difference that matters most ​

These two get mixed up more than anything else in the plugin, and they do completely different jobs:

FiltersDisplay conditions
Decidewhich products go inside the blockwhether the block appears at all
Look atyour cataloguethe shopper and the visit
Live onthe Setup tabthe Display Conditions tab
Example"only products under $50""only for shoppers on a phone"

Read them together as one sentence and the difference is obvious: "Show products under $50 (filter) to shoppers on a phone (display condition)." If you're trying to say "only show this to mobile shoppers" with a filter, you want the Display Conditions tab instead.

Recommendation Manager ​

The part of the plugin that decides which blocks actually show for this shopper, on this page, right now.

Every block in the plugin goes through it, without exception. Depending on how you set it up under Settings → Recommendation Manager, it can:

  • stop the same product appearing twice on one page (No repeated products)
  • cap how many blocks one page can show (Limit blocks per page)
  • cap how many recommendations one shopper sees per visit (Limit recommendations per session)
  • pick a winner when two Recommendations want the same spot (by priority, Pro only)

All three limits are off on a new install, so nothing is held back until you choose to. Whatever you set, it always hides a block that would end up empty. Every time it holds a block back, it records why. On the list, a Recommendation held back by a limit shows a Limit reached chip.

The Recommendation Manager is why your third Recommendation doesn't turn a product page into a wall of boxes. It's also usually the answer to "why didn't my block show on this page?"

Read Recommendation Manager before you build your third Recommendation.

Session ​

One shopper visit. It ends after 30 minutes without activity.

Limit recommendations per session counts within a session. A visit that's ended doesn't count against the next one, so a cap you set for one visit never becomes a cap for that shopper forever.

Status ​

Every Recommendation is either on or off:

StatusMeaning
ActiveLive and eligible to show on your storefront. A new Recommendation becomes Active the moment you save it, if it's complete.
InactiveSwitched off, with all its settings kept. A new Recommendation that isn't complete yet is saved as Inactive, and the plugin tells you what to fix. Duplicates start Inactive too.

You switch a Recommendation on or off from the All Recommendations list. Saving changes in the builder never flips it.

You may also see a Limit reached chip on an Active Recommendation. That isn't a status you set. It means the Recommendation Manager held it back on a recent page view because of a page or session limit.

Saving and the published snapshot ​

When you click Save Changes, the plugin checks the whole Recommendation, then rebuilds a snapshot: one ready-made copy of everything the storefront needs.

That's why the storefront is fast. It's also why a half-finished change can't leak onto a product page: the storefront only ever reads the snapshot. If an edit to an Active Recommendation can't go live as it stands, the builder asks first (This change can't go live). You can then Save as inactive, which takes the block off your storefront, or Keep editing. Changing a Recommendation Manager setting also rebuilds the snapshot, so the next page load follows the new rules.

Next ​