# Cart & PDP Upsells

## Recommended products

Shopify Product Recommendations (Cart Drawer & Cart Page)

***

### Overview

This system controls the "You might also like" or "Pair it with" products displayed in the Cart.

* **Clients/Admins:** Use the **Search & Discovery App** to manually pin specific products.
* **Developers:** Refer to the provided GitHub repositories for the implementation logic.

***

### 1. For Store Managers: Manually Populating Products

**Goal:** Manually select specific products to display for a certain item, overriding Shopify's automated algorithm.

We use the native **Shopify Search & Discovery** app for this.

#### **Steps to Override Automation**

1. **Open the App:** In Shopify Admin, go to **Apps > Search & Discovery**.
2. **Navigate to Recommendations:** Click **Product recommendations** in the menu.
3. **Add Recommendation:** Click **Add recommendations** and select the "source" product (the product currently in the cart).
4. **Choose Type:**
   * **Complementary Products:** Best for Carts. These are add-ons (e.g., Socks for Shoes, Batteries for Toys).
   * **Related Products:** These are usually similar alternatives (e.g., A different style of shirt).
5. **Select Products:** Browse and add the specific products you want to show as upsells.
6. **Disable Auto-fill:**
   * By default, if you only pick 1 product but the design shows 2, Shopify will fill the empty slot with an automated suggestion.
   * To **strictly avoid automated recommendations**, ensure you manually pin enough products to fill the design slots (usually 2–4 items).
7. **Save.**

**Result:** The cart will now prioritize these manually selected items over the algorithm.

***

### 2. For Developers: Implementation Guide

**Goal:** Fetch and display recommendations programmatically using the existing codebase.

#### **Source Code References**

Please refer to the following files in the Orion Theme for the logic and structure:

* Liquid Structure:

  [FIle link](https://github.com/Studio-Almond/orion-theme/blob/main/snippets/cart-recommended.liquid)
* JavaScript Logic:

  [File link](https://github.com/Studio-Almond/orion-theme/blob/main/src/js/includes/cart-recommended.js)

#### **Implementation Notes**

1. Intent Handling:

   The API requires an intent parameter. You can swap this within the JS logic based on client requirements:

   * Use `intent=complementary` if the client wants to show **Add-ons** (recommended for Cart Drawers).
   * Use `intent=related` if the client wants to show **Similar Products**.
2. Manual Priority:

   The code logic provided automatically respects the Search & Discovery app settings. If a merchant manually pins products, the API returns those first. If no manual products exist, it falls back to Shopify's algorithm.
3. Filtering:

   Ensure the logic continues to filter out products that are already in the cart to prevent recommending an item the user has already purchased.

***

### 3. Stopping Recommendations on certain products

If a brand wants to not have upsells on some products, then a simple trigger can be added on a product, tag, category or even collection level scenario to indicate that any products matching or meeting this rule, will not show recommended upsells.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.almond.studio/promotions/cart-and-pdp-upsells.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.