Medusa

Medusa is an open-source headless commerce platform written in Node.js and TypeScript, distributed under the MIT license. The Medusa server exposes two REST APIs - a public Store API consumed by storefronts and end-customer clients, and a privileged Admin API consumed by the Medusa Admin dashboard and back-office tooling - both documented with OpenAPI. Around the server the project ships a modular Framework (API Routes, Modules, Module Links, Workflows, Subscribers, Scheduled Jobs, Admin Extensions), the Commerce Modules (cart, payment, customer, pricing, promotion, product, order, inventory, fulfillment, stock location, region, sales channel, tax, currency, API keys, user, auth), the @medusajs/js-sdk TypeScript client, the Medusa CLI (create-medusa-app), the Next.js storefront starter, a remote MCP server that exposes the docs to LLM coding assistants, and Medusa Cloud as an optional managed hosting offering with predictable per-environment pricing and no GMV fees.

9 APIs 10 Features

CommerceHeadlesseCommerceOpen SourceNode.jsTypeScriptFrameworkModulesWorkflowsMCP

APIs

Medusa Store API

Public REST API consumed by storefronts and end-customer clients - carts, products, collections, categories, regions, customers, orders, payments, shipping, returns, gift cards,...

Medusa Admin API

Privileged REST API consumed by the Medusa Admin dashboard and back-office tooling - product, inventory, pricing, order, customer, user, and store administration, plus configura...

Medusa JS SDK (@medusajs/js-sdk)

Official TypeScript / JavaScript SDK wrapping the Store and Admin REST APIs - typed clients, auth helpers, and ergonomic resource methods. Distributed via npm as @medusajs/js-sd...

Medusa Framework (Modules, Workflows, Routes)

Server-side framework primitives for extending Medusa - custom API Routes, Modules with their own data models (DML), Module Links, Workflows for transactional business logic, Su...

Medusa Commerce Modules

First-party domain modules that compose into a Medusa application - Cart, Payment, Customer, Pricing, Promotion, Product, Order, Inventory, Fulfillment, Stock Location, Region, ...

Medusa CLI (create-medusa-app)

Command-line tooling for scaffolding new Medusa projects, generating modules and migrations, running the server in dev, and managing common project tasks.

Medusa Next.js Storefront Starter

Reference Next.js storefront talking to the Medusa Store API - cart, checkout, account, product browse, payments, and search. Used as the canonical starting point for headless s...

Medusa Docs MCP Server

Remote Model Context Protocol server exposing the Medusa documentation to LLM-powered coding assistants - lets agents look up commerce modules, framework concepts, and APIs whil...

Medusa Core Repository

Monorepo with the Medusa server, Admin, Commerce Modules, Framework, and packages. MIT-licensed reference for self-hosting and for building modules and plugins.

Collections

Medusa Store API

OPEN

Pricing Plans

Medusa Js Plans Pricing

1 plans

PLANS

Rate Limits

Medusa Js Rate Limits

2 limits

RATE LIMITS

FinOps

Medusa Js Finops

FINOPS

Features

Modular Commerce Modules

First-party domain modules (cart, order, product, inventory, pricing, promotion, payment, fulfillment, region, sales channel, tax, currency, auth) that can be swapped or extended.

Workflows Engine

Transactional, durable business-logic workflows with compensation steps for orchestrating multi-step commerce operations.

Admin Dashboard

Customizable React-based Medusa Admin UI with first-class admin extensions for adding screens, widgets, and routes.

Store and Admin REST APIs

Two distinct REST surfaces - public Store API and privileged Admin API - both described with OpenAPI.

JS / TypeScript SDK

Typed JS SDK (@medusajs/js-sdk) for both Store and Admin APIs with shared types from @medusajs/types.

Next.js Starter

Reference Next.js storefront wired to the Store API as a launchpad for custom storefronts.

CLI Tooling

create-medusa-app and the Medusa CLI for scaffolding projects, running dev servers, and managing migrations.

Agentic Development (MCP)

Remote MCP server exposing the docs and a Development Agent that lets LLM coding assistants build on Medusa.

Medusa Cloud

Optional managed hosting with GitHub-based deploys, autoscaling, and no GMV-based fees.

MIT License

Permissive open-source license with no vendor lock-in and the ability to self-host the full stack.

Use Cases

Headless DTC Storefronts

Power Next.js / React Native / native storefronts for direct-to- consumer brands using the Store API and JS SDK.

B2B Commerce

Build company-account, quoting, and approval flows on top of the Commerce Modules and Workflows engine.

Marketplaces

Use sales channels, regions, and stock locations to model multi- vendor and multi-store marketplaces.

Composable Commerce Replatforming

Replace Shopify, BigCommerce, or Magento with a fully owned, self-hostable commerce backend.

AI-Native Commerce

Drive merchandising, support, and operations from LLM agents using the MCP server and admin tooling.

Custom Checkout Experiences

Implement bespoke checkout, payment, and pricing flows by composing modules and workflows.

Quick Commerce & Logistics

Model stock locations, fulfillment, and regions for last-mile and on-demand delivery models.

Internal Commerce Platforms

Stand up an internal commerce backbone for catalog, orders, and fulfillment shared across brands or business units.

Integrations

Next.js

Official Next.js storefront starter (nextjs-starter-medusa) wired to the Store API.

Stripe

Payment provider integration for card payments and saved methods via the Payment module.

PayPal

PayPal payment provider integration via the Payment module.

Algolia / MeiliSearch / Typesense

Search integrations for product catalog indexing and storefront search.

SendGrid / Resend

Notification providers for transactional email through the Notification module.

AWS S3 / MinIO

File storage providers for product images and assets.

PostgreSQL

Primary supported database engine for the Medusa server.

Redis

Used for caching, event bus, and queues in production deployments.

Model Context Protocol (MCP)

Remote MCP server exposes the Medusa docs to Claude, Cursor, and other MCP-aware coding assistants.

GitHub

GitHub-based deployments and source-of-truth for Medusa Cloud environments.

Solutions

Medusa Core (Self-Hosted)

Free, MIT-licensed open-source server, Admin, framework, and commerce modules deployable to any Node.js host.

Medusa Cloud - Develop

Entry managed tier with GitHub deploys, dev agent, and a shared server starting at $29/mo.

Medusa Cloud - Launch

Production-ready managed tier with autoscaling, custom domains, automatic backups, and zero-downtime deploys at $99/mo.

Medusa Cloud - Scale

Growth tier with background workers, priority support, and higher edge request quotas at $299/mo.

Medusa Cloud - Enterprise

SLA-backed enterprise tier with core-team access, custom agentic workflows, and implementation support.

Medusa Experts

Curated partner network of agencies and consultancies delivering Medusa implementations.

Resources

GitHubOrganization

Sources

opencollection: 1.0.0
info:
  name: Medusa Store API
  version: '2'
request:
  auth:
    type: apikey
    key: x-publishable-api-key
    value: '{{x-publishable-api-key}}'
    placement: header
items:
- info:
    name: Auth
    type: folder
  items:
  - info:
      name: Authenticate as a customer
      type: http
    http:
      method: POST
      url: '{medusaApplicationUrl}/auth/customer/:auth_provider'
      params:
      - name: auth_provider
        value: ''
        type: path
      body:
        type: json
        data: '{}'
      auth:
        type: apikey
        key: x-publishable-api-key
        value: '{{x-publishable-api-key}}'
        placement: header
    docs: Authenticate as a customer
  - info:
      name: Exchange a JWT for a cookie session
      type: http
    http:
      method: POST
      url: '{medusaApplicationUrl}/auth/session'
    docs: Exchange a JWT for a cookie session
- info:
    name: Products
    type: folder
  items:
  - info:
      name: List products
      type: http
    http:
      method: GET
      url: '{medusaApplicationUrl}/store/products'
      params:
      - name: limit
        value: ''
        type: query
      - name: offset
        value: ''
        type: query
      - name: fields
        value: ''
        type: query
      - name: order
        value: ''
        type: query
    docs: List products
  - info:
      name: Get a product
      type: http
    http:
      method: GET
      url: '{medusaApplicationUrl}/store/products/:id'
      params:
      - name: id
        value: ''
        type: path
    docs: Get a product
- info:
    name: Carts
    type: folder
  items:
  - info:
      name: Create a cart
      type: http
    http:
      method: POST
      url: '{medusaApplicationUrl}/store/carts'
      body:
        type: json
        data: '{}'
    docs: Create a cart
  - info:
      name: Retrieve a cart
      type: http
    http:
      method: GET
      url: '{medusaApplicationUrl}/store/carts/:id'
      params:
      - name: id
        value: ''
        type: path
    docs: Retrieve a cart
  - info:
      name: Update a cart
      type: http
    http:
      method: POST
      url: '{medusaApplicationUrl}/store/carts/:id'
      params:
      - name: id
        value: ''
        type: path
      body:
        type: json
        data: '{}'
    docs: Update a cart
  - info:
      name: Add a line item to a cart
      type: http
    http:
      method: POST
      url: '{medusaApplicationUrl}/store/carts/:id/line-items'
      params:
      - name: id
        value: ''
        type: path
      body:
        type: json
        data: '{}'
    docs: Add a line item to a cart
- info:
    name: Orders
    type: folder
  items:
  - info:
      name: List the authenticated customer's orders
      type: http
    http:
      method: GET
      url: '{medusaApplicationUrl}/store/orders'
      auth:
        type: apikey
        key: x-publishable-api-key
        value: '{{x-publishable-api-key}}'
        placement: header
    docs: List the authenticated customer's orders
  - info:
      name: Get an order
      type: http
    http:
      method: GET
      url: '{medusaApplicationUrl}/store/orders/:id'
      params:
      - name: id
        value: ''
        type: path
    docs: Get an order
- info:
    name: Customers
    type: folder
  items:
  - info:
      name: Register a customer
      type: http
    http:
      method: POST
      url: '{medusaApplicationUrl}/store/customers'
      body:
        type: json
        data: '{}'
    docs: Register a customer
  - info:
      name: Get the authenticated customer
      type: http
    http:
      method: GET
      url: '{medusaApplicationUrl}/store/customers/me'
      auth:
        type: apikey
        key: x-publishable-api-key
        value: '{{x-publishable-api-key}}'
        placement: header
    docs: Get the authenticated customer
- info:
    name: Collections
    type: folder
  items:
  - info:
      name: List collections
      type: http
    http:
      method: GET
      url: '{medusaApplicationUrl}/store/collections'
    docs: List collections
- info:
    name: Categories
    type: folder
  items:
  - info:
      name: List product categories
      type: http
    http:
      method: GET
      url: '{medusaApplicationUrl}/store/categories'
    docs: List product categories
- info:
    name: Regions
    type: folder
  items:
  - info:
      name: List regions
      type: http
    http:
      method: GET
      url: '{medusaApplicationUrl}/store/regions'
    docs: List regions
  - info:
      name: Get a region
      type: http
    http:
      method: GET
      url: '{medusaApplicationUrl}/store/regions/:id'
      params:
      - name: id
        value: ''
        type: path
    docs: Get a region
- info:
    name: Shipping
    type: folder
  items:
  - info:
      name: List available shipping options
      type: http
    http:
      method: GET
      url: '{medusaApplicationUrl}/store/shipping-options'
      params:
      - name: cart_id
        value: ''
        type: query
    docs: List available shipping options
- info:
    name: Payments
    type: folder
  items:
  - info:
      name: Create a payment collection
      type: http
    http:
      method: POST
      url: '{medusaApplicationUrl}/store/payment-collections'
      body:
        type: json
        data: '{}'
    docs: Create a payment collection
bundled: true