Overview
Icon for Wishlist

Wishlist

Let customers save and share wishlist items

Medusa Wishlist

A wishlist plugin for Medusa v2 that allows customers to save products for later and share their wishlists with others.

Features

  • πŸ›οΈ Customer Wishlists - Each customer gets their own wishlist, automatically created when they add their first item
  • βž• Add/Update Items - Customers can add products to their wishlist and update quantities
  • πŸ—‘οΈ Remove Items - Easy removal of items from the wishlist
  • πŸ”— Share Wishlists - Generate shareable links using JWT tokens
  • 🌐 Public Access - Shared wishlists can be viewed without authentication
  • πŸ”’ Secure - JWT-based token system for sharing

Installation

Option 1: Install as NPM Package

  1. Install the plugin:
npm install @rsc-labs/medusa-wishlist
# or
yarn add @rsc-labs/medusa-wishlist
  1. Add the plugin to your Copy to clipboardmedusa-config.js:
const plugins = [
// ... other plugins
{
resolve: "@rsc-labs/medusa-wishlist",
options: {
jwtSecret: process.env.JWT_SECRET || "supersecret"
}
}
]

Or simply:

const plugins = [
// ... other plugins
"@rsc-labs/medusa-wishlist"
]
  1. Run database migrations:
npx medusa db:migrate

Option 2: Copy Source Code

You can also copy the source code directly into your Medusa project:

  1. Copy the Copy to clipboard/src directory contents into your project
  2. Add the module to your Copy to clipboardmedusa-config.js:
const modules = [
// ... other modules
{
resolve: "./src/modules/wishlist",
options: {
jwtSecret: process.env.JWT_SECRET || "supersecret"
}
}
]
  1. Install required dependencies:
npm install jsonwebtoken
# or
yarn add jsonwebtoken
  1. Run database migrations:
npx medusa db:migrate

Configuration

JWT Secret

The wishlist sharing feature uses JWT tokens. It's recommended to set a strong secret in your environment variables:

# .env
JWT_SECRET=your-super-secret-key-here

Then configure it in Copy to clipboardmedusa-config.js:

{
resolve: "@rsc-labs/medusa-wishlist",
options: {
jwtSecret: process.env.JWT_SECRET
}
}

API Endpoints

Authenticated Endpoints (Require Customer Token)

Get Customer's Wishlist

GET /store/customers/me/wishlist
Authorization: Bearer {customer-token}

Add or Update Item

POST /store/customers/me/wishlist/items
Authorization: Bearer {customer-token}
Content-Type: application/json
{
"productId": "prod_01XXXXX",
"productVariantId": "variant_01XXXXX",
"quantity": 1
}

Remove Item

DELETE /store/customers/me/wishlist/items?productId={productId}&productVariantId={productVariantId}
Authorization: Bearer {customer-token}

Generate Share Token

POST /store/customers/me/wishlist/share-token
Authorization: Bearer {customer-token}
Response:
{
"shared_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Public Endpoints (No Authentication Required)

View Shared Wishlist

GET /store/wishlists?token={shared-token}

Usage Example

1. Customer Login

curl -X POST http://localhost:9000/store/auth/customer/emailpass \
-H "Content-Type: application/json" \
-d '{
"email": "customer@example.com",
"password": "password123"
}'

2. Add Item to Wishlist

curl -X POST http://localhost:9000/store/customers/me/wishlist/items \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"productId": "prod_01XXXXX",
"productVariantId": "variant_01XXXXX",
"quantity": 1
}'

3. Get Wishlist

curl -X GET http://localhost:9000/store/customers/me/wishlist \
-H "Authorization: Bearer {token}"

4. Generate Share Token

curl -X POST http://localhost:9000/store/customers/me/wishlist/share-token \
-H "Authorization: Bearer {token}"

5. View Shared Wishlist (Public)

curl -X GET "http://localhost:9000/store/wishlists?token={shared-token}"

Database Schema

The plugin creates the following tables:

Copy to clipboardwishlist

  • Copy to clipboardid - Primary key
  • Copy to clipboardcreated_at - Timestamp
  • Copy to clipboardupdated_at - Timestamp

Copy to clipboardwishlist_item

  • Copy to clipboardid - Primary key
  • Copy to clipboardwishlist_id - Foreign key to wishlist
  • Copy to clipboardproduct_id - Product identifier
  • Copy to clipboardproduct_variant_id - Product variant identifier
  • Copy to clipboardquantity - Item quantity
  • Copy to clipboardcreated_at - Timestamp
  • Copy to clipboardupdated_at - Timestamp

Copy to clipboardlink_customer_wishlist

  • Links customers to their wishlists (1:1 relationship)

How It Works

  1. Automatic Creation: When a customer adds their first item, a wishlist is automatically created and linked to their account
  2. Item Management: Customers can add, update quantities, or remove items from their wishlist
  3. Sharing: Customers can generate a JWT token to share their wishlist with others
  4. Public Access: Anyone with the share token can view the wishlist without authentication

API Documentation

For detailed API specifications, see the OpenAPI documentation.

Development

Prerequisites

  • Node.js 20+
  • Medusa v2
  • PostgreSQL

Local Setup

# Install dependencies
npm install
# Run migrations
npx medusa db:migrate
# Start development server
npm run dev

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.

Credits

Created by RSC Labs

Support

For issues and questions:

Built for Medusa v2 πŸš€

You may also like

Browse all integrations

Build your own

Develop your own custom integraiton

Build your own integration with our API to speed up your processes. Make your integration available via npm for it to be shared in our Library with the broader Medusa community.

gift card interface

Ready to build your custom commerce setup?