Skip to content
Tutorials Center
My learning

Topics

Lesson 1 of 33 ยท Getting Started

What Is Medusa?

Learn what Medusa is, how headless commerce differs from a monolithic shop, what Medusa 2 ships in the box and when to choose it, with a runnable mini API.

Most online shops start as one program that does everything: it stores products, renders the pages, takes payments and sends the emails. That is quick to launch, but it ties the look of the shop to the code that runs it. Medusa takes the opposite approach. It is an open-source commerce engine for Node.js that exposes everything a shop needs through APIs and leaves the storefront entirely to you.

This lesson explains the idea behind headless commerce, what you get when you install Medusa, how Medusa 2 differs from the older Medusa 1 and from monolithic platforms, and how to decide whether it fits a project. At the end you run a tiny headless API of your own. It is a stand-in, not Medusa itself: Medusa needs a Postgres database and a Node project, so the real code in this track is shown read-only, and every lesson pairs it with a small runnable model of the same idea.

The headless idea

A head is the part of a shop customers see: pages, buttons, a checkout form. A headless system has no built-in head. It only has a body: data, rules and APIs. The head can be anything that speaks HTTP: a Next.js site, a mobile app, a kiosk, a voice assistant, a marketplace feed.

flowchart LR
    W["Web storefront"] --> API["Store API"]
    M["Mobile app"] --> API
    K["In-store kiosk"] --> API
    API --> C["Commerce engine<br/>products, carts, orders"]
    A["Admin dashboard"] --> C
    C --> DB[("Postgres")]

Several "heads" talk to one engine; the engine owns the data and the business rules.

Two benefits follow. First, the frontend team can use any framework and redeploy the storefront without touching the backend. Second, the business rules (how a cart total is computed, when stock is reserved) live in one place, so a mobile app and a website can never disagree about them. The cost is that you must build and host the head yourself. For the shared vocabulary of carts, orders and payments, see What Is E-commerce? and Choosing a Commerce Platform.

What ships in the box

A fresh Medusa project gives you three things:

  1. Commerce modules. Packages that each own one area of commerce: products, pricing, inventory, carts, orders, customers, payments, fulfillment, taxes, promotions and more. The Commerce Modules tours them.
  2. The APIs. A Store API (under /store) for shoppers and an Admin API (under /admin) for staff. Both are REST over JSON.
  3. The Admin dashboard. A React single-page app, served by the same backend in development, where staff manage products, prices, orders and settings. It can be extended with your own widgets and pages.

What does not ship is a finished storefront. There is an optional starter built with Next.js that you can copy and change (The Next.js Starter Storefront), but it is a starting point, not the product.

Here is how the real thing is started. These commands are read-only here; you will run them in the next lesson.

Terminal
npx create-medusa-app@latest my-store
cd my-store
npx medusa develop
# API on http://localhost:9000, Admin on http://localhost:9000/app

Medusa 2, Medusa 1 and monoliths

Medusa 1 was a single large backend with services, a plugin system and a shared database layer. Plugins could reach into each other's tables, which made upgrades risky. Medusa 2 (the current line, released in late 2024) was rebuilt around ideas that make the system easier to extend:

  • Modules are isolated packages with their own data models and their own service. A module does not query another module's tables; it receives an ID and asks for the rest through a defined channel.
  • Workflows are multi-step operations (for example "complete a cart") built from steps that can be undone if a later step fails.
  • Links connect records across modules without joining their tables.
  • A dependency-injection container wires services together.

Compared with a monolithic platform such as a hosted theme-based shop, you gain control and give up convenience: you run the servers, choose the database host, write the storefront, and own upgrades. Compared with Medusa 1, tutorials and plugins written for the old version do not apply directly, so check which major version any article describes before copying code.

This track teaches Medusa 2. Package names, configuration keys and file locations can change between minor releases, so when a detail matters for production, confirm it in the documentation of the version you install.

When to choose Medusa

Medusa is a good fit when:

  • you need a custom checkout, custom pricing or unusual business rules that hosted platforms restrict;
  • the same catalog must feed several channels (web, app, B2B portal);
  • your team is comfortable with TypeScript and Postgres and can operate a backend;
  • you want to own the code and data rather than rent them.

It is a weaker fit when you want to launch a small store this week with no developers, when you depend on a large marketplace of ready-made themes and apps, or when nobody can maintain servers. A hosted platform is often the better choice there, and there is no shame in choosing it.

A tiny headless API (stand-in)

The program below is not Medusa. It is a stand-in that shows the headless contract in about forty lines: a server owns the data, a client sends HTTP requests, and a header carries a key that says which storefront is calling (Medusa calls this a publishable API key, you will meet it in The Store API). Prices are integers in cents, as explained in Representing Money Correctly.

Node.js A headless catalog API on loopback

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice that the client never sees how products are stored. It could be a database, a spreadsheet or another service; the contract is the URL and the JSON. That separation is the heart of headless commerce.

Two heads, one body (stand-in)

To see why a shared engine matters, render the same product data in two different "heads". Neither head knows about the other, and neither contains pricing logic.

JS Two storefronts, one catalog

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does "headless" mean in headless commerce?

    The "head" is the customer-facing presentation. A headless engine only provides data, rules and APIs, and any frontend can use them.
  2. 2. Which of these ships with a fresh Medusa 2 project?

    Medusa provides the engine, the two APIs and the dashboard. The storefront, the database host and payment accounts are yours to supply.
  3. 3. What is the main architectural change from Medusa 1 to Medusa 2?

    Medusa 2 isolates each commerce area in a module with its own data models, and coordinates multi-step operations with workflows.
  4. 4. Which project is the weakest fit for Medusa?

    Medusa rewards teams that can write and run TypeScript and Postgres. Someone without developers is usually better served by a hosted platform.

Summary

  • Headless commerce separates the customer-facing "head" from the engine that owns data and rules.
  • Medusa 2 ships commerce modules, a Store API, an Admin API and a React-based Admin dashboard, but no finished storefront.
  • Medusa 2 is built on isolated modules, workflows, links and a dependency-injection container; Medusa 1 material does not apply directly.
  • Choose Medusa for custom logic, multiple channels and ownership; choose a hosted platform when speed and zero maintenance matter most.
  • The API in this lesson is a stand-in that shows the contract; real Medusa code is shown read-only in this track.

Next: Create a Medusa Project