> ## 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.

Depict recommendations are rendered by a theme section called **Depict
Recommendations**. Enabling recommendations creates the surfaces that decide
*what* to recommend; you decide *where* they appear by adding the 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, either by the Depict team or
by clicking **Enable recommendations** on the Recommendations page of the
Depict app. That seeds your first surfaces and starts the first computation.

## 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 three:

| Surface      | Made for                                                                             |
| ------------ | ------------------------------------------------------------------------------------ |
| `pdp`        | Product pages. The classic "You may also like".                                      |
| `cart`       | Cart page.                                                                           |
| `storefront` | Anywhere without a product to anchor on, such as the home page or a collection page. |

Edit these or add your own in the Depict app under Recommendations: change the
recommenders, reorder the steps and set how many products each contributes.

A surface that recommends *relative to a product* only fills on product pages,
because it needs that product as its anchor. `cart` and `storefront` work
anywhere.

## 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.

<Steps>
  <Step title="Open the theme editor">
    In Shopify admin go to **Online Store → Themes** and click **Customize**
    on the theme you want to change.
  </Step>

  <Step title="Choose the template">
    In the template selector at the top of the editor, choose **Products →
    Default product**.
  </Step>

  <Step title="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**.
  </Step>

  <Step title="Pick the surface">
    In the section settings, set **Recommendation surface** to `pdp`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

The section can only be added to product, cart, home and collection templates.
For the other pages, use the home page template with `storefront`, **Cart**
with `cart`, and **Collections → Default collection** with `storefront`.

## Section settings

| Setting                 | What it does                                                                                                                                                 |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Recommendation surface  | Which surface to render. Leave it unset and the section falls back to products from your catalog.                                                            |
| Max products to show    | How many cards to fetch, 1 to 48 (default 12). Cards beyond the visible row stay reachable in the carousel.                                                  |
| Items per row (desktop) | 2 to 8, default 4.                                                                                                                                           |
| Items per row (mobile)  | 1 to 4, default 2.                                                                                                                                           |
| Navigation arrows       | Style of the prev/next buttons shown when the row overflows: none, chevron, arrow, circle or square button. "None" keeps the row scrollable without buttons. |
| Heading                 | Text above the carousel. Leave blank to hide it.                                                                                                             |
| Heading size            | Large, medium or small.                                                                                                                                      |
| Heading alignment       | Left, center or right.                                                                                                                                       |

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.

## 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.

Two 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 `storefront` for
  the home and collection pages.
* **The first computation hasn't finished.** Right after enabling
  recommendations, give it some time and reload the editor.

<Note>
  Recommendations are recomputed for each of your markets on a schedule, so you
  don't need to refresh anything when your catalog changes.
</Note>