> For the complete documentation index, see [llms.txt](https://the-wishlist-documentation.gitbook.io/the-wishlist-documentation-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://the-wishlist-documentation.gitbook.io/the-wishlist-documentation-docs/developer-reference/recommendation-widgets.md).

# Recommendation Widgets

## Setup Guide for Shopify

Follow these steps to enable The Wishlist Recommendations widgets on your Shopify store.

***

### Prerequisites

* The Wishlist account (contact us for onboarding)
* Shopify store with an Online Store 2.0 theme
* The Wishlist Pixel App installed and configured — see Customer Events Pixel
* The Wishlist Proxy App installed and configured — see Proxy App Install Guide

***

### Step 1: Install the Proxy App

The TWC Proxy App handles authentication between your store and The Wishlist services.

See the **TWC Proxy App Setup Guide** for full instructions.

Once installed, verify the proxy is working by opening your store in an incognito window and running the following in the browser console:

```js
fetch('/apps/twc-sdk/auth/token')
  .then(r => r.json())
  .then(console.log)
```

Expected response:

```json
{
  "success": true,
  "data": {
    "access_token": "eyJ...",
    "shop": "abc123"
  }
}
```

If this fails, refer to the Proxy App setup guide before continuing.

***

### Step 2: Install the Pixel App

The Wishlist Customer Events Pixel App tracks customer behaviour events (product views, cart additions, etc.) to power personalised recommendations.

See the **Customer Events Pixel** for full instructions.

***

### Step 3: Deploy the Theme App Extension

The recommendation widgets are delivered as a Shopify Theme App Extension.

#### Prerequisites

* Shopify CLI installed
* Access to the The Wishlist Shopify app codebase

#### Deploy

From the `shopify/` directory:

```bash
# Link to the app (first time only)
shopify app config link

# Deploy to all stores with the app installed
shopify app deploy
```

This pushes the theme extension (`extensions/twc-recommendations/`) to Shopify, making the blocks available in the theme editor for all stores with the The Wishlist Shopify app installed.

#### Verify Deployment

1. Go to your Shopify Partners Dashboard
2. Navigate to your app → **Extensions**
3. Confirm `twc-recommendations` shows as **Deployed**

***

### Step 4: Add Recommendation Blocks to Your Theme

Once the extension is deployed, recommendation blocks appear in the Shopify theme editor.

Available blocks:

| Block                    | Description                   |
| ------------------------ | ----------------------------- |
| **TWC For You**          | Personalised recommendations  |
| **TWC Trending**         | Popular products              |
| **TWC Similar Products** | Related items (product pages) |

Refer to `INSTALL.md` for detailed instructions on adding each block.

***

### Troubleshooting

| Issue                         | Solution                                                               |
| ----------------------------- | ---------------------------------------------------------------------- |
| 403 error on `auth/token`     | Proxy App secret key not configured                                    |
| 401/422 error on `auth/token` | Proxy App not installed or misconfigured                               |
| Widgets not appearing         | Verify blocks are added in the theme editor and the section is visible |
| Empty recommendations         | Product catalogue may not be synced — contact us                       |
| Products show but no images   | Check the `handle` field is being returned from the The Wishlist API   |

***

### Support

* **Email:** <support@thewishlist.io>
* **Documentation:** Contact your account manager