Medusa Sellers Plugin

Plugin for managing sellers, commissions, and withdrawals in MedusaJS v2.

Features

• Sellers Management: Complete CRUD for sellers with independent authentication
• Customer Assignment: Seller-customer relationship for sales tracking
• Commissions: Calculation and management of sales commissions
• Withdrawals: Commission withdrawal requests
• Orders Management: Seller-specific order filtering and tracking
• Admin UI: Custom admin dashboard page for seller management

Compatibility

This plugin is compatible with @medusajs/medusa >= 2.12.x.

Structure

src/
├── modules/
│   └── seller/              # Main module
│       ├── models/          # Data models
│       │   ├── seller.ts         # Seller entity
│       │   ├── seller-customer.ts # Seller-customer relationship
│       │   ├── commission.ts      # Sales commissions
│       │   └── withdrawal.ts      # Commission withdrawals
│       ├── service.ts       # Business logic
│       └── index.ts         # Module exports
├── api/
│   ├── admin/               # Admin panel routes
│   │   └── sellers/
│   │       ├── route.ts         # GET/POST sellers
│   │       └── [id]/route.ts    # GET/POST/DELETE seller by id
│   ├── seller/              # Authenticated seller routes
│   │   ├── me/route.ts          # Seller profile
│   │   ├── orders/route.ts      # Seller-specific orders
│   │   ├── stats/route.ts       # Statistics
│   │   ├── customers/route.ts   # Assigned customers
│   │   ├── commissions/route.ts # Commissions
│   │   └── withdrawals/route.ts # Withdrawals
│   └── middlewares.ts
├── admin/
│   └── routes/
│       └── sellers/
│           └── page.tsx         # Admin UI page for sellers

Installation

As a Git Submodule (Development)

1. Add the plugin as a submodule:

git submodule add <repository-url> packages/medusa-sellers
git submodule update --init --recursive

2. Install dependencies:

cd packages/medusa-sellers
pnpm install
pnpm build - or other, confirm your manager package - 

3. Add the plugin to medusa-config.ts:

import { defineConfig } from '@medusajs/framework/utils'

module.exports = defineConfig({
  plugins: [
    {
      resolve: "@csbeker/medusa-sellers",
      options: {}
    }
  ]
})

4. Run migrations:

npx medusa db:migrate

As an NPM Package (Production)

pnpm add @csbeker/medusa-sellers

API Endpoints

Admin Routes

Sellers

• GET /admin/sellers - List all sellers
• POST /admin/sellers - Create a new seller
• GET /admin/sellers/:id - Get seller by ID
• POST /admin/sellers/:id - Update seller
• DELETE /admin/sellers/:id - Delete seller

Customers

• GET /admin/customers - List all customers with pagination
• GET /admin/customers/:id - Get customer details with orders and assigned seller
• GET /admin/customers/:id/seller - Get seller assigned to a customer
• POST /admin/customers/:id/seller - Assign/reassign seller to a customer (body: { seller_id: string | null })

Seller Routes (Authenticated)

• GET /seller/me - Get seller profile
• GET /seller/orders - Get orders filtered by seller's assigned customers
• POST /seller/orders - Create a persisted draft order with seller metadata (for creating orders on behalf of customers)
• GET /seller/customers - Get assigned customers with pagination (limit, offset)
• GET /seller/customers/:id - Get customer detail with addresses (seller-scoped)
  • Returns: id, email, first_name, last_name, phone, has_account, company_name, created_at, updated_at, metadata, addresses
• GET /seller/customers/:id/orders - Get orders for a specific customer with pagination
  • Query params: limit (default: 11), offset, q (search by order ID), status (pending/all)
• POST /seller/customers/:id/addresses - Add new address to customer
• POST /seller/customers/:id/addresses/:addressId - Update existing address
• DELETE /seller/customers/:id/addresses/:addressId - Delete address
• GET /seller/customers/summary - Get assigned customers with statistics (nro_pedidos, gasto_total)
  • Query params: limit (default: 11), offset, q (search), status (active/inactive)
• GET /seller/commissions - Get commissions
• GET /seller/withdrawals - Get withdrawals
• POST /seller/withdrawals - Request a withdrawal

Order Creation by Seller

When a seller creates an order using POST /seller/orders, the order metadata includes:

{
  "created_by_seller": true,
  "seller_id": "sell_xxx",
  "seller_email": "[email protected]",
  "seller_name": "Juan Pérez",
  "created_at_seller_portal": "2026-01-16T12:00:00.000Z",
  "notes": "Optional notes"
}

The request body requires items entries to include variant_id, quantity, and unit_price. If sales_channel_id isn't provided, the endpoint attempts to use the first available sales channel.

Customer-Seller Relationship

Important: Each customer can only be assigned to ONE seller. This is enforced at the service level.

To assign a seller to a customer from the Admin:

1. Go to the customer detail page in Medusa Admin
2. Use the "Vendedor Asignado" widget
3. Select a seller from the dropdown
4. Click "Asignar" or "Cambiar"

To reassign or remove:

• Select a different seller to reassign
• Click the X button to remove the assignment

Admin UI Widgets

Order Detail Widgets (order.details.side.after zone)

The plugin includes a widget that displays on order detail pages:

1. For Seller-Created Orders (created_by_seller: true):

   • Shows "Pedido creado por Vendedor" section
   • Displays seller name, email, creation date, and notes
   • Purple "Creado por vendedor" badge

2. For Customer Orders (Storefront) (order_note in metadata):

   • Shows "Nota del cliente" section
   • Displays the customer's order notes

⚠️ Technical Note: This widget is placed in the medusa-sellers plugin due to a known Vite/esbuild bug in Medusa v2 that causes "The symbol 'inWebWorker' has already been declared" errors when creating custom widgets directly in medusa/src/admin/widgets/. The workaround is to place widgets inside plugin directories.

Customer Detail Widget (customer.details.after zone)

• "Vendedor Asignado" widget for assigning sellers to customers

Admin UI Pages

The plugin adds a "Vendedores" (Sellers) page to the Medusa Admin dashboard at /app/sellers with complete CRUD functionality:

Features:

• ✅ Create: Add new sellers via interactive drawer form
• ✅ Read: View all sellers in a table with detailed information
• ✅ Update: Edit seller data using the three-dots menu → Edit
• ✅ Delete: Remove sellers with confirmation dialog via three-dots menu → Delete

Seller Information Displayed:

• Name (first_name + last_name or email)
• Email address
• Phone number
• Commission rate (%)
• Assigned customers count (badge)
• Active/Inactive status (badge)
• Creation date (AR locale)

Form Fields (Create/Edit):

Información Básica:

• Email (required)
• First name
• Last name
• Phone
• Commission rate (0-100%)
• Active/Inactive toggle

Información Fiscal:

• Razón Social
• CUIT
• Condición IVA

Ubicación Fiscal:

• Dirección
• Provincia
• Localidad
• Barrio

Development

# In the plugin directory
pnpm install

# Build the plugin
pnpm build

# Watch mode for development
pnpm dev

Troubleshooting

Admin UI not showing "Vendedores" menu item

1. Ensure the plugin is built:

   cd packages/medusa-sellers
   pnpm build

2. Clear Medusa admin cache:

   cd ../../medusa
   rm -rf .medusa

3. Restart Medusa:

   npx medusa develop

Submodule not updating

git submodule update --remote --merge