Table of Contents

• Features
• Installation
• Usage
• Configuration
• Models
• API Routes
• Database Schema
• Postman Collection

Features

• ✅ Create and manage multiple wishlists per customer
• ✅ Add/remove products to/from wishlists
• ✅ Update product quantities in wishlists
• ✅ Convert wishlist items to cart items
• ✅ Full TypeScript support
• ✅ RESTful API endpoints
• ✅ Automatic customer association

Installation

To install the plugin, run the following command in your Medusa project:

yarn add @webexpr-agency/medusa-plugin-wishlist

Usage

After installation, add the plugin to your medusa-config.js file:

const plugins = [
	// ... other plugins
	{
		resolve: `@webexpr-agency/medusa-plugin-wishlist`,
		options: {
			// ℹ️ Plugin options can be added here if needed in the future
		},
	},
]

Models

Wishlist

The main entity representing a customer's wishlist:

• id: Unique identifier
• title: Name of the wishlist
• customer_id: Reference to the customer who owns the wishlist
• metadata: Optional custom key-value pairs
• items: Collection of wishlist items
• created_at: Timestamp of creation
• updated_at: Timestamp of last update

WishlistItem

Represents a product variant in a wishlist:

• id: Unique identifier
• wishlist_id: Reference to the parent wishlist
• variant_id: Reference to the product variant
• quantity: Number of items (defaults to 1)
• metadata: Optional custom key-value pairs
• created_at: Timestamp of creation
• updated_at: Timestamp of last update

API Routes

Store Routes

List Wishlists

GET /store/wishlists

Query Parameters:

• limit: (number) Maximum number of wishlists to return. Default: 50
• offset: (number) Number of wishlists to skip. Default: 0
• q: (string, optional) Search query to filter wishlists by title
• order: (string, optional) Field to sort by
• expand: (string, optional) Expand related relations

Get Wishlist

GET /store/wishlists/:id

Query Parameters:

• expand: (string, optional) Expand related relations

Create Wishlist

POST /store/wishlists

Request Body:

{
	"title": "My Wishlist",
	"metadata": {} // optional
}

Update Wishlist

POST /store/wishlists/:id

Request Body:

{
	"title": "Updated Title",
	"metadata": {} // optional
}

Delete Wishlist

DELETE /store/wishlists/:id

Add Item to Wishlist

POST /store/wishlists/:id/items

Request Body:

{
	"variant_id": "variant_123",
	"quantity": 1 // optional, defaults to 1
}

Update Wishlist Item

POST /store/wishlists/:id/items/:itemId

Request Body:

{
	"quantity": 2
}

Remove Item from Wishlist

DELETE /store/wishlists/:id/items/:itemId

Create Cart from Wishlist

POST /store/wishlists/:id/checkout

Request Body:

{
	"region_id": "region_123",
	"cart_id": "cart_123" // optional, if it's defined, we will add the items to the existing cart
}

Note: This will return a cart object with the items from the wishlist.

Database Schema

Wishlist Table

CREATE TABLE "wishlist" (
  "id" character varying NOT NULL,
  "created_at" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
  "updated_at" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
  "title" character varying NOT NULL,
  "customer_id" character varying,
  "metadata" jsonb,
  CONSTRAINT "PK_wishlist_id" PRIMARY KEY ("id")
)

Wishlist Item Table

CREATE TABLE "wishlist_item" (
  "id" character varying NOT NULL,
  "created_at" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
  "updated_at" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
  "wishlist_id" character varying NOT NULL,
  "variant_id" character varying NOT NULL,
  "quantity" integer NOT NULL DEFAULT 1,
  "metadata" jsonb,
  CONSTRAINT "PK_wishlist_item_id" PRIMARY KEY ("id")
)

Indexes and Constraints

CREATE INDEX "IDX_wishlist_customer_id" ON "wishlist" ("customer_id")
CREATE INDEX "IDX_wishlist_item_wishlist_id" ON "wishlist_item" ("wishlist_id")
CREATE INDEX "IDX_wishlist_item_variant_id" ON "wishlist_item" ("variant_id")

ALTER TABLE "wishlist"
ADD CONSTRAINT "FK_wishlist_customer"
FOREIGN KEY ("customer_id")
REFERENCES "customer"("id")
ON DELETE CASCADE
ON UPDATE NO ACTION

ALTER TABLE "wishlist_item"
ADD CONSTRAINT "FK_wishlist_item_wishlist"
FOREIGN KEY ("wishlist_id")
REFERENCES "wishlist"("id")
ON DELETE CASCADE
ON UPDATE NO ACTION

ALTER TABLE "wishlist_item"
ADD CONSTRAINT "FK_wishlist_item_product_variant"
FOREIGN KEY ("variant_id")
REFERENCES "product_variant"("id")
ON DELETE CASCADE
ON UPDATE NO ACTION

Download Postman Collection