Medusa — Open Source Headless Commerce Engine

What Medusa Does

• Product Management: Products, variants, categories, collections, inventory, and pricing
• Order Processing: Cart, checkout, payment capture, fulfillment, returns, and exchanges
• Customer Management: Accounts, addresses, groups, and order history
• Payment Integration: Stripe, PayPal, and custom payment providers
• Shipping: Custom shipping options, fulfillment providers, and rate calculation
• Multi-Region: Per-region pricing, currencies, tax rates, and shipping options
• Promotions: Discount codes, percentage/fixed, free shipping, and buy-X-get-Y
• Admin Dashboard: React-based admin panel with full commerce management
• Storefront: Next.js starter storefront included

Architecture (Medusa v2)

┌──────────────┐     ┌──────────────────────┐     ┌──────────────┐
│  Storefront  │────▶│  Medusa Application   │────▶│  PostgreSQL  │
│  (Next.js)   │     │  ┌────────────────┐   │     └──────────────┘
└──────────────┘     │  │  Modules       │   │
                     │  │  ┌──────────┐  │   │
┌──────────────┐     │  │  │Product   │  │   │
│  Admin UI    │────▶│  │  │Order     │  │   │
│  (React)     │     │  │  │Customer  │  │   │
└──────────────┘     │  │  │Payment   │  │   │
                     │  │  │Shipping  │  │   │
                     │  │  │Inventory │  │   │
                     │  │  └──────────┘  │   │
                     │  └────────────────┘   │
                     └──────────────────────┘

Getting Started

# Create new Medusa project
npx create-medusa-app@latest my-store

# Choose:
# - PostgreSQL database
# - Next.js storefront (optional)
# - Seed data for testing

cd my-store
npx medusa develop

Project Structure

my-store/
├── src/
│   ├── modules/        # Custom commerce modules
│   ├── workflows/      # Business logic workflows
│   ├── api/           # Custom API routes
│   ├── subscribers/   # Event subscribers
│   └── jobs/          # Background jobs
├── medusa-config.ts   # Configuration
└── package.json

Key Features

Modular Commerce

Each commerce capability is an independent module:

// medusa-config.ts
module.exports = defineConfig({
  modules: [
    { resolve: "@medusajs/medusa/product" },
    { resolve: "@medusajs/medusa/order" },
    { resolve: "@medusajs/medusa/customer" },
    { resolve: "@medusajs/medusa/payment" },
    { resolve: "@medusajs/medusa/inventory" },
    // Add custom modules
    { resolve: "./src/modules/loyalty" },
  ],
});

Workflows (Business Logic)

import { createWorkflow, createStep } from "@medusajs/framework/workflows-sdk";

const validateInventoryStep = createStep("validate-inventory", async ({ items }) => {
  // Check stock availability
  for (const item of items) {
    if (item.quantity > item.available) {
      throw new Error(`Insufficient stock for ${item.title}`);
    }
  }
  return items;
});

export const customCheckoutWorkflow = createWorkflow("custom-checkout", (input) => {
  const validated = validateInventoryStep(input);
  // Add more steps: apply discount, calculate tax, create order
  return validated;
});

JS SDK (Storefront)

import Medusa from "@medusajs/js-sdk";

const medusa = new Medusa({ baseUrl: "http://localhost:9000", publishableKey: "pk_..." });

// List products
const { products } = await medusa.store.product.list();

// Add to cart
const cart = await medusa.store.cart.create({});
await medusa.store.cart.createLineItem(cart.id, {
  variant_id: "variant_123",
  quantity: 2,
});

// Complete checkout
await medusa.store.cart.complete(cart.id);

Custom API Routes

// src/api/store/custom/route.ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework";

export async function GET(req: MedusaRequest, res: MedusaResponse) {
  const productModule = req.scope.resolve("product");
  const products = await productModule.listProducts({
    tags: { value: ["featured"] },
  });
  res.json({ products });
}

Medusa vs Alternatives

FAQ

Q: What's the difference between Medusa v1 and v2? A: v2 is a complete rewrite that introduces a modular architecture, a Workflows business-logic engine, and a new JS SDK. It's more flexible than v1 and better suited to complex commerce scenarios. New projects should use v2.

Q: Which frontend frameworks can I use? A: Any framework works. The official starter template uses Next.js. The community offers templates for Nuxt.js, Gatsby, and SvelteKit. Connect to the Medusa backend via the JS SDK or REST API.

Q: Is it suitable for e-commerce in the Chinese market? A: Medusa's multi-region features support RMB pricing and China-specific tax configurations. Payment integration requires custom payment providers for WeChat Pay and Alipay. For logistics, you can hook up Chinese courier APIs via custom fulfillment providers.

Sources & Credits

• GitHub: medusajs/medusa — 32.6K+ ⭐ | MIT
• Website: medusajs.com