Before you start
Recommendations is included in some Depict plans; without it, the Recommendations page shows what it does and links to Plan. When your plan includes it, open Recommendations in the Depict app and choose where the first carousel should show. Each option creates a surface you can rename, tune and place, and starts its first computation. Behavior that applies to every surface:- Recommendations include only in-stock products, unless you turn on Include out-of-stock products for a surface.
- Results are precomputed per surface and market; a combination without a computed result renders nothing rather than falling back. The exception is Personalized surfaces, which are built for each shopper as the page loads and fall back to your best sellers.
- On product pages, the anchor product is never included in its own recommendations.
- Recommendations are recomputed on a schedule per market, and after a surface is saved.
Surfaces
A surface is a named recipe for what to recommend: an ordered cascade of steps, where each step contributes products until the surface is full. A new setup starts with four:
The Recommendations page: metrics for the period and the surfaces list.
- For this product: products related to the one being viewed. Only on product-page surfaces.
- Personalized: products based on what this shopper viewed or has in their cart. See Personalized surfaces.
- Any page: products that need no anchor, such as Best sellers.
cart and home_page work
anywhere.
A New arrivals step has a Published within (days) field: it only picks
products published within that many days, newest first. A newly added step
starts at 30 days; leave the field empty for no limit.
A surface also has a limit — the maximum number of products it computes
(25 by default). The theme section’s “Max products to show” can never exceed
it: a section set to 48 on a surface with limit 25 shows at most 25.
The surface editor: the ordered steps of the cart surface, with filters per step.
Pinned products
A surface can carry pinned products: a pin fixes a product to a slot on every page the surface serves, and the algorithm fills the remaining slots.- Pin positions are slot numbers — pinning to slots 1 and 5 leaves slots 2–4 to the algorithm.
- Up to 100 products can be pinned per set.
- On product-anchored surfaces, pins can be set per anchor product; changing a surface’s context removes its product-specific pin sets (the editor warns before saving).
Hidden products
A surface can also hide products: a hidden product never appears in that surface’s recommendations, on any page it serves. Hiding wins over pinning — hiding a pinned product removes its pins, and pinning a hidden product shows it again.Out-of-stock products
Each surface has a Surface settings card with an Include out-of-stock products toggle. It is off by default, so the surface recommends in-stock products only. Turn it on to let sold-out products appear too, both in the recommendations and among your pinned products. Pairs well with steps still use in-stock products only. Save the surface to apply the change.Personalized surfaces
A surface is Personalized when at least one of its steps uses what the shopper has done in your store: the products they viewed or the products in their cart. The editor shows a Personalized badge on such a surface and a P on each step that makes it so. There is no separate switch: the steps decide. A step makes its surface Personalized when it:- is a Recently viewed step, which shows the products this shopper viewed, newest first;
- is Based on Recently viewed or Cart. Similar products, Bought together, Viewed together and Pairs well with can be based on This product (product pages only), on the shopper’s recently viewed products, on their cart, or on a mix. With more than one source, Mix products sets whether they Blend or Take turns;
- uses Sort by similarity with Recently viewed or Cart, which reorders the step’s products by how close they are to what the shopper viewed or has in their cart.
How shoppers get them
- A Personalized surface is built for each shopper as the page loads, from its steps, the page’s product or collection, and the shopper’s recently viewed products and cart. Other surfaces show precomputed results.
- Products already in the shopper’s cart are never recommended.
- The section stays hidden until its products have loaded, so shoppers never see an empty row. If they can’t load, the section shows your store’s best sellers instead.
- Personalized surfaces need the Depict Brand Features app embed. With the embed off, their sections stay hidden.
- The first time a surface in your store becomes Personalized, Depict adds a few files to your published theme that let these sections show your theme’s own product cards. This takes a few minutes. Until then the section stays hidden on the storefront, although the preview in the app already shows products. An unpublished theme gets the files when you publish it.
- After that, changes to a Personalized surface reach shoppers within a few minutes of saving.
Shopper history and privacy
- A shopper’s recently viewed products are stored in their own browser, not by Depict: the last 20 products they viewed, for up to 30 days. Each page sends them along to build that page’s recommendations.
- They are stored only when the shopper allows preferences in your store’s cookie banner (Shopify’s customer privacy settings). If the shopper declines or later withdraws consent, nothing is stored and earlier history is deleted.
- A shopper with no history yet, or who declined, gets nothing from steps that read it. The surface’s later steps fill those slots, so end a Personalized surface with a step that needs no history, such as Best sellers.
Previewing a Personalized surface
The preview in the surface editor has a Simulated shopper: add products to the preview’s cart and recently viewed list to see what a shopper with that cart and history gets. Nothing you add there is saved.Filters
Every step in a surface can carry filters. A filter narrows what that step is allowed to contribute — it never adds products, and it only affects its own step: the other steps of the surface still pick freely, and the same step on another surface is untouched. To filter a whole surface, add the filter to every step of that surface; to filter every carousel in your store, do that on every surface. Open a surface, click a step to expand it, and pick a filter type under Filters:
Each step can carry at most one filter of each type. Remove a filter with its
trash icon to stop filtering.
The sale filter
Adding the Sale status filter to a step shows a choice of two options. Only sale items (the default) makes the step recommend sale items only. Hide sale items makes it recommend full-price items only — useful when you’d rather keep discounted products out of a carousel.1
Open the surface
In the Depict app go to Recommendations and click the surface you want
to change, for example
cart.2
Expand the step
Click a step to expand it. The collapsed row shows a summary such as “No
filters” or “1 filter”.
3
Add the filter
Under Filters, click Sale status. The filter is added with Only
sale items selected.
4
Pick the direction
Keep Only sale items to recommend only sale items, or pick Hide sale
items to recommend only full-price items.
5
Repeat where you want it
Filters are per step and per surface. Add the filter to each step of the
surface — and to each surface — where you want it to apply.
6
Save
Click Save. Saving starts a recomputation of the surface; the change
reaches the storefront when it finishes, typically within a few minutes.
cart surface’s first
step combines it with a price filter to suggest inexpensive sale items as
add-ons.
Filters narrow, they don’t guarantee. If only a handful of products are on
sale, a sale-filtered step contributes only those, and the surface fills the
rest from its later steps. Unless the surface includes out-of-stock
products, recommendations are also limited to in-stock products, sale or
not.
Adding the section to your theme
The example below puts “You may also like” on the product page. The same steps work for the other templates the section supports; pick the matching template and surface.1
Open the theme editor
In Shopify admin go to Online Store → Themes and click Customize
on the theme you want to change.
2
Choose the template
In the template selector at the top of the editor, choose Products →
Default product.
3
Add the section
In the left sidebar click Add section where you want the
recommendations to appear, usually below the product information, and pick
Depict Recommendations.
4
Pick the surface
In the section settings, set Recommendation surface to
pdp.5
Set the heading and layout
Type a Heading such as “You may also like”, or leave it blank for no
heading, then adjust the layout settings below.
6
Position and save
Drag the section to where you want it on the page and click Save. On an
unpublished theme the section goes live when you publish that theme.
home_page, Cart
with cart, and Collections → Default collection with collection_page.
Pages and blog posts
The section can also be added to page, blog and blog post templates. These pages have no product or collection to anchor on, so pick a surface that doesn’t need one:home_page, cart, or your own surface built from
Any page and Personalized steps. Surfaces made for product or
collection pages need that page’s product or collection, so don’t use them
there.
For example, a “Shop the look” carousel on a blog post is a surface with one
Best sellers step and a Collection filter set to Any of
these collections… with the look’s collection. Make one surface per look,
then add the section to the blog post template and pick that surface.
Section settings
The cards reuse your theme’s own product card wherever possible, so fonts,
badges and prices match the rest of the store. Anything beyond that can be
adjusted with custom CSS: see
Styling recommendations with custom CSS.
Troubleshooting
”Depict Recommendations” is missing from the Add section list
The Depict app has not installed its files on that particular theme yet, which happens on a fresh duplicate of a theme. Contact us with the name of the theme you are editing and we will set it up.The section shows no products
In the theme editor an empty section shows a grey placeholder with the reason: either no surface is picked, or the surface returned nothing for this page. On the live storefront the section is hidden completely, so shoppers never see an empty block. Three common causes:- The surface doesn’t fit the page. A product-anchored surface such as
pdphas nothing to work from outside a product page. Usehome_pagefor the home page, pages and blog posts, andcollection_pagefor collection pages. - The first computation hasn’t finished. Right after enabling recommendations, give it some time and reload the editor.
- Filters leave too few products. A step filtered to only sale items has nothing to contribute when nothing is on sale in that market. Loosen or remove the filter, or make sure a later step without it can fill the surface.
A Personalized section is hidden or shows best sellers
In the theme editor, a Personalized section says “Loading live recommendations…” while it loads, and “Live recommendations couldn’t load” if it fails. Common causes:- Depict Brand Features is off. If the editor keeps showing “Loading live recommendations…”, switch the embed on: see Depict Brand Features.
- The surface just became Personalized. Depict is still adding its files to your theme. Reload after a few minutes.
- Your agency manages the theme’s Depict files, or Depict set it up by hand. The files aren’t added automatically. Contact us with the theme’s name.
- Best sellers instead of personalized products. Showing them means the Personalized products couldn’t load, so the section showed your best sellers rather than an empty row.
- Fewer personalized products than expected. A Recently viewed step is empty on a shopper’s first product view, and for shoppers who declined preferences in the cookie banner. Later steps fill those slots.
Recommendations are recomputed for each of your markets on a schedule, so you
don’t need to refresh anything when your catalog changes.