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

📚 Table of Contents

• ✨ Features
• 📦 Installation
• 🔧 Plugin Options
• 📦 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

📦 Installation

Install the plugin via npm:

1
npm install @alphabite/medusa-wishlist

In your Copy to clipboardmedusa-config.js, register the plugin:

12345678910111213
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 Copy to clipboardwishlistFields Copy to clipboardstring[] Copy to clipboard["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 Copy to clipboardwishlistItemsFields Copy to clipboardstring[] Copy to clipboard["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 Copy to clipboardincludeWishlistItems Copy to clipboardboolean Copy to clipboardfalse Automatically populate wishlist items in Copy to clipboardGET /store/wishlists Copy to clipboardincludeWishlistItemsTake Copy to clipboardnumber Copy to clipboard5 Limit number of items if Copy to clipboardincludeWishlistItems is true Copy to clipboardallowGuestWishlist Copy to clipboardboolean Copy to clipboardfalse Enables wishlist creation & usage without authentication (cookie-based)

📦 API Endpoints

All endpoints are available under Copy to clipboard/store/wishlists.

Method Endpoint Auth Description GET Copy to clipboard/store/wishlists ✅ List wishlists for the current customer POST Copy to clipboard/store/wishlists ➖ (optional) Create a new wishlist GET Copy to clipboard/store/wishlists/:id ➖ (optional) Retrieve a wishlist by ID PUT Copy to clipboard/store/wishlists/:id ✅ Update wishlist metadata DELETE Copy to clipboard/store/wishlists/:id ✅ Delete a wishlist POST Copy to clipboard/store/wishlists/:id/transfer ✅ Transfer guest wishlist to logged-in user GET Copy to clipboard/store/wishlists/:id/items ➖ (optional) Get items in a wishlist POST Copy to clipboard/store/wishlists/:id/add-item ➖ (optional) Add an item to the wishlist DELETE Copy to clipboard/store/wishlists/:id/items/:item_id ➖ (optional) Remove an item from the wishlist

🧑‍💻 SDK Usage

❗❗❗Read more about our Medusa compatible SDK here

1234567891011121314151617181920
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',

🧪 Guest Wishlist Flow

Guest wishlists work like guest carts:

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

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

After that, the cookie is no longer needed.

🧩 Requirements

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

📭 Postman Collection

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

1
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 🛍️