Skip to main content

​
Introduction to Medusa

Medusa is a commerce platform with a built-in framework for customization that allows you to build custom commerce applications without reinventing core commerce logic. The framework and modules can be used to support advanced B2B or DTC commerce stores, marketplaces, distributor platforms, PoS systems, service businesses, or similar solutions that need foundational commerce primitives.

​
What Makes Medusa Different

Medusa provides building blocks for digital commerce through a modular architecture that lets you:
  • Customize without limits: Built-in framework with workflows, modules, and API routes
  • Use what you need: 30+ independent commerce modules you can compose
  • Scale confidently: Production-ready architecture with TypeScript throughout
  • Own your data: Open-source, MIT-licensed, and self-hostable

​
Core Capabilities

Commerce Modules

Pre-built modules for products, carts, orders, payments, fulfillment, customers, and more

Workflows SDK

Composable workflows with built-in compensation logic for complex business processes

Admin Dashboard

Customizable React-based admin panel for managing your commerce operations

API-First Design

RESTful APIs with automatic OpenAPI documentation and type-safe clients

​
Commerce Modules

Medusa includes 30+ commerce modules that handle specific domains:
  • Product Module - Product catalog, variants, collections, categories
  • Cart Module - Shopping cart management with promotions
  • Order Module - Order lifecycle and fulfillment
  • Payment Module - Payment processing with multiple providers
  • Customer Module - Customer accounts and groups
  • Fulfillment Module - Shipping and delivery management
  • Inventory Module - Stock levels and reservations
  • Promotion Module - Discounts, campaigns, and offers
  • Auth Module - Authentication and authorization
  • Notification Module - Multi-channel notifications
All modules are:
  • Open-source and published to npm
  • Independently versioned and deployable
  • Fully typed with TypeScript
  • Tested with comprehensive integration tests

​
Workflows

Medusa’s Workflow SDK (@medusajs/workflows-sdk) enables you to compose complex business logic from simple steps: 
import {
  createWorkflow,
  WorkflowResponse
} from "@medusajs/framework/workflows-sdk"

const createProductWorkflow = createWorkflow(
  "create-product",
  (input: WorkflowInput) => {
    const product = createProductStep(input)
    const inventory = reserveInventoryStep(product.id)
    
    return new WorkflowResponse(product)
  }
)
Workflows provide:
  • Automatic compensation: Rollback on errors
  • Retry logic: Built-in resilience
  • Type safety: End-to-end TypeScript support
  • Composability: Reuse steps across workflows

​
Admin Dashboard

The admin dashboard (@medusajs/admin-dashboard) is a customizable React application that provides:
  • Product and inventory management
  • Order processing and fulfillment
  • Customer relationship management
  • Analytics and reporting
  • Extensible UI components
  • Custom pages and widgets

​
API Routes

Build custom API endpoints with full framework support: 
import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { createProductsWorkflow } from "@medusajs/core-flows"

export const POST = async (
  req: MedusaRequest,
  res: MedusaResponse
) => {
  const { result } = await createProductsWorkflow(req.scope)
    .run({
      input: { products: [req.body] }
    })

  res.json({ product: result[0] })
}
Every route has access to:
  • Dependency injection container (req.scope)
  • All registered modules and services
  • Workflow execution engine
  • Type-safe request/response objects

​
Technology Stack

  • Runtime: Node.js 20+
  • Language: TypeScript 5.6+
  • Database: PostgreSQL 13+ (via MikroORM)
  • Package Manager: Yarn 3.2.1 (monorepo with workspaces)
  • Testing: Jest 29 (backend), Vitest 3 (frontend)
  • Admin UI: React 18 + Vite 5

​
Get Started

Quickstart

Get a Medusa application running in under 5 minutes

Installation

Detailed installation guide for all package managers

Architecture

Learn about Medusa’s modular architecture and design patterns

API Reference

Explore the complete API documentation

​
Community & Support

​
License

Medusa is MIT licensed and free to use for commercial projects.

Build docs developers (and LLMs) love

Get started for freeTalk to us