> ## Documentation Index > Fetch the complete documentation index at: https://docs.depict.ai/llms.txt > Use this file to discover all available pages before exploring further. # Recommendations > Add a Depict recommendation carousel to your theme, for example "You may also like" on product pages. Enabling recommendations creates the surfaces that decide *what* to recommend; you decide *where* by adding the **Depict Recommendations** section to your theme in the Shopify theme editor. Nothing shows up on the storefront until you do. ## Before you start Recommendations has to be enabled for your store by the Depict team — [contact us](mailto:hello@depict.ai) to get set up. Enabling seeds your first surfaces and starts the first computation. Behavior that applies to every surface: * Recommendations only ever include in-stock products. * Results are precomputed per surface and market; a combination without a computed result renders nothing rather than falling back. * 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: | Surface | Made for | | - | - | | `pdp` | Product pages. The classic "You may also like". | | `cart` | Cart page. | | `home_page` | The home page, or anywhere else without a product or collection to anchor on. | | `collection_page` | Collection pages. | The Recommendations page showing metric tiles for revenue via recommendations, click-through, add to cart and orders, and a table of four surfaces named Cart, Collection Page, Home Page and Pdp with the pages each shows on, its step count and limit, impressions, click-through and revenue Edit these or add your own in the Depict app under Recommendations: change the recommenders, reorder the steps, set how many products each contributes and [filter](#filters) what each step is allowed to pick. The available recommenders are: similar products, bought together, viewed together, best sellers, most viewed, new arrivals, and generative cross-sell. Which of them a step can use depends on the surface's context — a product-anchored recommender is only available on product-anchored surfaces. A surface that recommends *relative to a product* only fills on product pages, because it needs that product as its anchor. `cart` and `home_page` work anywhere. 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 for the cart surface: metric tiles for the surface, an Algorithm card with two ordered best sellers steps carrying two filters and one filter, a Your overrides card for products pinned everywhere and hidden products, and a live preview of the recommended products next to Discard changes and Save buttons ### 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). ## 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**: | Filter | What it does | | - | - | | **Price** | Keep products priced within a range relative to your catalog's median price. | | **Category** | Keep products from specific collections, or from the same (or a different) collection as the surface's anchor. | | **On sale** | Keep only sale items — or only full-price items. | 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 **On sale** filter to a step shows a single checkbox. Ticked (the default), it reads **Only products currently on sale** and the step recommends sale items only. Unticked, it reads **Only products not currently on sale** and the step recommends full-price items only — useful when you'd rather keep discounted products out of a carousel. In the Depict app go to **Recommendations** and click the surface you want to change, for example `cart`. Click a step to expand it. The collapsed row shows a summary such as "No filters" or "1 filter". Under **Filters**, click **On sale**. The filter is added with **Only products currently on sale** ticked. Leave the box ticked to recommend only sale items, or untick it to recommend only full-price items. 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. Click **Save**. Saving starts a recomputation of the surface; the change reaches the storefront when it finishes, typically within a few minutes. **Result:** the step's collapsed row shows "1 filter", and after the recomputation finishes (typically within a few minutes) the storefront carousel serves only products matching the filter. **What counts as "on sale":** a product whose price is below its compare-at price in Shopify. This is evaluated per market, so a product discounted only in some markets counts as on sale only there — a sale-filtered carousel can show different products per market. A product without a compare-at price counts as not on sale. New setups already use the sale filter: the default `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 — recommendations are also always limited to in-stock products, sale or not. Filtering by product type, tags or other product attributes isn't possible yet. ## Adding the section to your theme The example below puts "You may also like" on the product page. The same steps work for the cart, home and collection pages; pick the matching template and surface. In Shopify admin go to **Online Store → Themes** and click **Customize** on the theme you want to change. In the template selector at the top of the editor, choose **Products → Default product**. In the left sidebar click **Add section** where you want the recommendations to appear, usually below the product information, and pick **Depict Recommendations**. In the section settings, set **Recommendation surface** to `pdp`. Type a **Heading** such as "You may also like", or leave it blank for no heading, then adjust the layout settings below. 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. **Result:** the carousel renders in the theme editor's preview with products from the chosen surface (or a grey placeholder stating why it's empty — see [troubleshooting](#troubleshooting)). On the storefront, it appears once the theme change is saved — on an unpublished theme, when that theme is published. The section can only be added to product, cart, home and collection templates. For the other pages, use the home page template with `home_page`, **Cart** with `cart`, and **Collections → Default collection** with `collection_page`. ## Section settings | Setting | Options / range | Default | | - | - | - | | Recommendation surface | Which surface to render. Unset falls back to products from your catalog. | unset | | Max products to show | 1–48. Never more than the surface's own limit. Cards beyond the visible row stay reachable in the carousel. | 12 | | Hide products without images | on / off | on | | Items per row (desktop) | 2–8 | 4 | | Items per row (mobile) | 1–4 | 2 | | Navigation arrows | None, Chevron, Arrow, Circle button, Square button. Shown when the row overflows; hidden on touch devices. | Chevron | | Arrow placement | Overlay (on the cards) or Sides (space beside them). Shown when arrows are enabled. | Overlay | | Color scheme | Your theme's color schemes | Scheme 1 | | Show secondary image on hover | on / off. Available on themes where Depict renders the product card itself; otherwise the card follows its own settings. | on | | Show image carousel on cards | on / off. Ignored by cards without an image carousel. | off | | Heading | Text above the carousel. Blank hides it. | blank | | Heading size | 14–40 px | 20 px | | Heading alignment | Left, Center, Right | Left | 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](/shopify-lite/recommendations-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](mailto:hello@depict.ai) 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 `pdp` has nothing to work from outside a product page. Use `home_page` for the home page and `collection_page` for 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](#filters) 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. Recommendations are recomputed for each of your markets on a schedule, so you don't need to refresh anything when your catalog changes. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.