Wishlist

🧞‍♂️ Wishlist Plugin for Medusa

The Alphabite Wishlist Plugin is the most feature-complete wishlist system for MedusaJS. It supports both authenticated and guest users, multiple wishlists per user, and a full-featured SDK client for frontend integration.

This plugin ships with:

• 🔌 A fully typed JS SDK plugin
• 📭 A Postman collection
• ✅ Support for guest & authenticated customers

---

⚠️ Version Compatibility

Please install the plugin version that matches your Medusa version:

Installing the latest version (Medusa 2.14.* and above)

npm install @alphabite/medusa-wishlist

Installing version 0.5.8 (Medusa 2.13.*)

npm install @alphabite/medusa-wishlist@0.5.8

Installing version 0.5.7 (Medusa versions below 2.13.0)

npm install @alphabite/medusa-wishlist@0.5.7

ℹ️ Using a mismatched version may result in compatibility issues. Make sure to check your Medusa version (npm list @medusajs/medusa) before installing.

---

📚 Table of Contents

• ✨ Features
• 📦 Installation
• 🔧 Plugin Options
• 🛠️ Admin
• 📦 API Endpoints
• 🧑‍💻 SDK Usage
• 🧪 Guest Wishlist Flow
• 🧩 Requirements
• 📭 Postman Collection
• 🤝 Contributing

---

✨ Features

• ✅ Multiple wishlists per customer
• ✅ Add/remove items to/from any wishlist
• ✅ Guest wishlist supported + transfer when registered
• ✅ Fully typed Medusa JS SDK integration with our SDK client
• ✅ Pagination and filtering built-in
• ✅ Admin page with Settings + Analytics tabs

---

📦 Installation

Install the plugin via npm:

npm install @alphabite/medusa-wishlist

In your medusa-config.js, register the plugin:

1const plugins = [
2  {
3    resolve: "@alphabite/medusa-wishlist",
4    options: {
5      // all are optional, read bellow about default values
6      wishlistFields: [],
7      wishlistItemsFields: [],
8      includeWishlistItems: true,
9      includeWishlistItemsTake: 5,
10      allowGuestWishlist: true,
11    },
12  },
13];

---

🔧 Plugin Options

---

🛠️ Admin

The plugin adds a Wishlists page to the admin sidebar (/app/wishlists) with two tabs: Settings (guest / multiple-wishlist toggles) and Analytics (a read-only dashboard of KPIs, an activity trend, and the most-wishlisted products and variants).

See docs/admin-analytics.md for the analytics endpoint and response shape.

---

📦 API Endpoints

All endpoints are available under /store/wishlists.

---

🧑‍💻 SDK Usage

❗❗❗Read more about our Medusa compatible SDK here

1import { AlphabiteMedusaClient, wishlistPlugin } from '@alphabite/sdk'
2
3const sdk = new AlphabiteMedusaClient({
4  {
5    baseUrl,
6    debug: process.env.NODE_ENV === "development",
7    publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
8  },
9  [wishlistPlugin],
10  {
11    getAuthHeader: () => { return { authorization: `Bearer ${customerJwt}` } },
12  }
13})
14
15// Create wishlist
16await sdk.alphabite.wishlist.create({ name: 'My Sneakers' })
17
18// Add item
19await sdk.alphabite.wishlist.addItem({
20  id: 'wishlist_id',
21  product_variant_id: 'variant_id',
22})
23
24// List items
25const { data } = await sdk.alphabite.wishlist.listItems({ id: 'wishlist_id' })

---

🧪 Guest Wishlist Flow

Guest wishlists work like guest carts:

1. Create a wishlist (no auth required)
2. Save the id in a cookie
3. Use that ID for listing/adding/removing items
4. When the user signs up or logs in, call the transfer endpoint to associate it:

await medusa.alphabite.wishlist.transfer({ id: wishlistId });

After that, the cookie is no longer needed.

---

🧩 Requirements

• Medusa v2.5.0+
• Works with both @medusajs/types and @medusajs/framework

---

📭 Postman Collection

You’ll find the ready-to-import Postman collection at:

docs/postman/WishlistPlugin.postman_collection.json

Use it to explore and test all endpoints interactively.

---

🤝 Contributing

We welcome issues, feedback, and PRs. Fork it, build it, improve it.

Let’s make commerce more personalized 🛍️