🧞♂️ 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:
| Medusa Version | Plugin Version | Install Command |
|---|---|---|
2.14.* and above | latest | npm install @alphabite/medusa-wishlist |
2.13.* | 0.5.8 | npm install @alphabite/[email protected] |
Below 2.13.0 | 0.5.7 | npm install @alphabite/[email protected] |
latest is built and tested against Medusa 2.21.0.
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/[email protected]
Installing version 0.5.7 (Medusa versions below 2.13.0)
npm install @alphabite/[email protected]
ℹ️ 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:
const plugins = [
{
resolve: "@alphabite/medusa-wishlist",
options: {
// all are optional, read bellow about default values
wishlistFields: [],
wishlistItemsFields: [],
includeWishlistItems: true,
includeWishlistItemsTake: 5,
allowGuestWishlist: true,
},
},
];
🔧 Plugin Options
| Option | Type | Default | Description |
|---|---|---|---|
wishlistFields | string[] | ["items.*", "items.product_variant.*", "items.product_variant.prices.*", "items.product_variant.product.thumbnail", "items.product_variant.product.id"] | Selectively include Medusa product or product variant fields on wishlist list/retrieve endpoints that have wishlist items included |
wishlistItemsFields | string[] | ["id", "product_id", "wishlist_id", "created_at", "wishlist.customer_id", "updated_at", "deleted_at", "product_variant.*", "product_variant.prices.*", "product_variant.calculated_price", "product_variant.product.thumbnail",] | Selectively include Medusa product or product variant fields on wishlist items list/retrieve endpoints |
includeWishlistItems | boolean | false | Automatically populate wishlist items in GET /store/wishlists |
includeWishlistItemsTake | number | 5 | Limit number of items if includeWishlistItems is true |
allowGuestWishlist | boolean | false | Enables wishlist creation & usage without authentication (cookie-based) |
🛠️ 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.
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| GET | /store/wishlists | ✅ | List wishlists for the current customer |
| POST | /store/wishlists | ➖ (optional) | Create a new wishlist |
| GET | /store/wishlists/:id | ➖ (optional) | Retrieve a wishlist by ID |
| PUT | /store/wishlists/:id | ✅ | Update wishlist metadata |
| DELETE | /store/wishlists/:id | ✅ | Delete a wishlist |
| POST | /store/wishlists/:id/transfer | ✅ | Transfer guest wishlist to logged-in user |
| GET | /store/wishlists/:id/items | ➖ (optional) | Get items in a wishlist |
| POST | /store/wishlists/:id/add-item | ➖ (optional) | Add an item to the wishlist |
| DELETE | /store/wishlists/:id/items/:item_id | ➖ (optional) | Remove an item from the wishlist |
🧑💻 SDK Usage
❗❗❗Read more about our Medusa compatible SDK here
import { AlphabiteMedusaClient, wishlistPlugin } from '@alphabite/sdk'
const sdk = new AlphabiteMedusaClient({
{
baseUrl,
debug: process.env.NODE_ENV === "development",
publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
},
[wishlistPlugin],
{
getAuthHeader: () => { return { authorization: `Bearer ${customerJwt}` } },
}
})
// Create wishlist
await sdk.alphabite.wishlist.create({ name: 'My Sneakers' })
// Add item
await sdk.alphabite.wishlist.addItem({
id: 'wishlist_id',
product_variant_id: 'variant_id',
})
// List items
const { data } = await sdk.alphabite.wishlist.listItems({ id: 'wishlist_id' })
🧪 Guest Wishlist Flow
Guest wishlists work like guest carts:
- Create a wishlist (no auth required)
- Save the
idin a cookie - Use that ID for listing/adding/removing items
- When the user signs up or logs in, call the
transferendpoint to associate it:
await medusa.alphabite.wishlist.transfer({ id: wishlistId });
After that, the cookie is no longer needed.
🧩 Requirements
- Medusa v2.14.0+
- Works with both
@medusajs/typesand@medusajs/framework
@mikro-orm/*, awilix and pg are provided by Medusa and don't need to be installed alongside the plugin.
📭 Postman Collection
You’ll find the ready-to-import Postman collection at:
alphabite-wishlist-postman.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 🛍️