How to Build a Custom Ecommerce Store with Medusa and Claude Code

If you're technically aware but not a developer yourself, this guide is for you. You don't need to know how to write code, you need to know what you want your store to do. Claude Code handles the implementation, and Medusa's well-documented framework gives it the structure to do that reliably. The same framework powers commerce operations for brands like Eight Sleep and INSPIRED Pet Nutrition, by the end of this tutorial, you'll have a working store and a workflow you can keep building on.

What is Medusa?

Medusa is a headless, open-source ecommerce platform. "Headless" means the backend (where your products, orders, pricing, and customers live) is completely separate from the frontend (what your customers actually see and click). With Medusa, you get a fully-featured commerce engine out of the box.

Medusa's architecture is organized around three core building blocks:

Commerce Modules: Pre-built, ready-to-use features for everything ecommerce: Products, Cart, Orders, Payments, Customers, Inventory, Promotions, Tax, and more. You don't build these from scratch, you can use them where needed.

The Framework: The set of tools Medusa gives you for adding custom behavior: API Routes (to expose new features), Workflows (to define business logic step by step), and Data Models (to store custom data). This is where your specific business logic lives.

The Admin Dashboard: A built-in UI where you manage your store: products, orders, customers, settings.

For hosting and deployment, Medusa Cloud is the recommended path. It is the most performant way to run Medusa, handling all infrastructure components out of the box, including the backend, storefront, admin, database S3, and caching layer, so there is nothing to configure or maintain yourself. On top of that, you get built-in features like Medusa Emails, guaranteed support for any issues, and infrastructure that auto-scales with your traffic, making it cost-efficient whether you're just launching or handling significant volume. It's what this tutorial uses in the final step.

When you ask Claude Code to add a feature, it's working within well-defined, patterns. It does not need to guess but can follow Medusa's well documented framework and tutorials.

Why does Medusa work well with Claude Code?

Claude Code is an AI coding assistant from Anthropic that you run from your terminal. Unlike a chatbot you type questions into, Claude Code has access to your actual project files. It can read your code, make changes, run commands, and explain what it's doing.

Medusa is actively built for coding agents like Claude Code. Medusa maintains a dedicated Agent Skills library: a growing set of skills that give Claude Code the specific knowledge needed to build with Medusa reliably, covering backend features, customizing the Admin Dashboard, building and optimizing storefronts, and even agents that operate your store.

Medusa continuously improves its framework with coding agents in mind, meaning the experience gets better over time as new skills and capabilities are added.

Claude Code works particularly well because of how Medusa is built:

• Open-source and fully transparent: the entire codebase is public, so Claude Code can reason about how Medusa works at every level, not just the documented surface.
• Built on TypeScript and Node.js: the most widely used programming languages in the world, giving Claude Code an extensive base of patterns and training data to draw from.
• Purpose-built for extensibility: API Routes, Workflows, Data Models, and Module Links all follow predictable patterns, so Claude Code's suggestions fit naturally into the existing structure.
• Extensive documentation: the Medusa plugin connects Claude Code directly to up-to-date reference material, guides, and tutorials.
• 700+ community plugins: a wide range of real-world Medusa implementations for Claude Code to draw from, beyond official examples.
• Active Discord with Q&A: thousands of real implementation questions and answers, queryable on the web.
• Recipes for common use cases: official blueprints for marketplaces, subscriptions, B2B portals, digital products, and more give Claude Code concrete patterns to follow for complex builds.
• Actively maintained: frequent releases mean Claude Code is working with a current, well-supported framework.

The practical effect: instead of needing to write TypeScript fluently, you need to be able to describe what you want clearly. "Add a custom field to products for supplier information" is a complete instruction. Claude Code handles the implementation inside Medusa's framework.

Before you get started: prerequisites

Before you start, make sure you have the following:

• A Medusa Cloud account: Medusa Cloud handles hosting, the database, and deployment so you don't have to. Sign up at cloud.medusajs.com. You'll connect it to your project in a later step.
• Node.js (v20 or later): this is the runtime Medusa runs on locally. Download from nodejs.org.
• A package manager: Medusa recommends Copy to clipboardpnpm. If you don't have it, run Copy to clipboardnpm install -g pnpm in your terminal.
• Claude Code: install it by running Copy to clipboardnpm install -g @anthropic-ai/claude-code in your terminal. You'll need a Claude account, of course.
• A terminal: on Mac, this is Terminal. On Windows, use Windows Terminal or WSL.

You'll work locally to build and customize your store, then deploy to Medusa Cloud when you're ready to go live. Cloud handles everything on the infrastructure side, database, scaling, environments, so the local setup is deliberately lightweight.

Step 1: How to Install Medusa

Open your terminal and run:

Copy to clipboardnpx create-medusa-app@latest my-store

This command creates a new Medusa project in a folder called Copy to clipboardmy-store. The installer will ask you a few questions; accept the defaults unless you have a reason not to.

What it sets up:

• The Medusa backend (your commerce engine)
• The Admin Dashboard
• A sample storefront (optional, but recommended for this tutorial)
• Seed data: a set of example products, so you have something to work with immediately

Once it finishes (it takes a few minutes), navigate into the folder:

Copy to clipboardcd my-store

Then start Medusa:

Copy to clipboardnpm run dev

Your Medusa backend will be running at Copy to clipboardhttp://localhost:9000. Open Copy to clipboardhttp://localhost:9000/app in your browser and you'll see the Admin Dashboard. Log in with the credentials the installer gave you.

Take a minute to explore it. You'll see the Products, Orders, Customers, and Settings sections. This is what your store's backend looks like, all of this is already functional, with no code written by you.

Step 2: How to Connect Claude Code to Your Project

Open a new terminal window (keep Medusa running in the first one) and navigate to your project folder:

Copy to clipboardcd my-store claude

This launches Claude Code inside your Medusa project. Now install the Medusa plugin, which gives Claude Code specific knowledge of Medusa's framework and documentation — so your instructions can focus on what you want to build, not on explaining how Medusa works:

Copy to clipboard/plugin marketplace add medusajs/medusa-claude-plugins /plugin install medusa-dev@medusa

That's it. Claude Code now has Medusa-specific skills built in and is connected to the Medusa MCP server, which lets it pull from Medusa's documentation when it needs to.

If you're completely new to Medusa and want to get familiar with its structure before building anything, there's also a Copy to clipboardlearn-medusa plugin that walks you through the framework interactively:

Copy to clipboard/plugin install learn-medusa@medusa

Then just send: Copy to clipboardI want to learn Medusa., and Claude Code will guide you through it step by step.

Otherwise, try your first instruction to confirm everything is connected:

Copy to clipboardDescribe the structure of this Medusa project to me. What are the main folders and what does each one do?

Claude Code will read your project and give you a plain-language explanation of what's where.

Step 3: How to Make Your First Customization

Let's do something concrete: add a custom attribute to products. Say you're building a store for a fashion brand and you want to add a "care instructions" field to every product, something that doesn't exist in Medusa's default Product module but that you need to display on your product pages.

In Claude Code, describe what you want:

Copy to clipboardI want to add a custom text field called "care_instructions" to Medusa's product data model. This field should be editable in the Admin Dashboard and accessible via the store API. Walk me through how to do this in Medusa's framework.

Claude Code will explain the approach, in Medusa, you extend the Product module by adding a custom field via the data model, and then implement it. It will create or modify the relevant files, following Medusa's framework conventions.

Step 4: How to Add Custom Business Logic with Workflows

Medusa's Workflows are sequences of steps that define how business operations happen. The built-in workflows cover the standard ecommerce flow, placing an order, processing a payment, fulfilling a shipment. You can extend them or create new ones.

A practical example: you want to automatically send a custom notification to a supplier when an order is placed containing their products. This isn't something Medusa does out of the box, it's custom business logic. But Medusa's Workflow framework gives Claude Code a clear place to put it.

In Claude Code:

Copy to clipboardWhen a new order is placed in Medusa, I want to automatically send an email notification to a supplier. The supplier email address is stored in a custom "supplier_email" field on the product. Walk me through how to set this up using Medusa's workflow and event system.

Claude Code will:

• Explain how Medusa's event system works (Medusa emits events like Copy to clipboardorder.placed)
• Write a subscriber that listens for that event
• Build a workflow step that reads the product's supplier email and sends the notification
• Tell you what email integration to use (Resend is commonly used with Medusa)

This is where Medusa's structure pays off: because there's a defined pattern for "do X when Y happens," Claude Code can implement it reliably, and you can verify the logic without reading every line.

Step 5: How to Customize the Admin Dashboard

The Admin Dashboard in Medusa is extensible. You can add custom widgets, components that appear inside existing pages, and custom routes, entirely new pages. This lets you build internal tools directly into your admin without a separate application.

Example: you want to see the care instructions field you added in Step 3 displayed on the product detail page in the Admin.

In Claude Code:

Copy to clipboardI want to add a widget to the Medusa Admin product detail page that displays and allows editing of the "care_instructions" field I added earlier. How do I create an Admin Widget in Medusa?

Claude Code will generate the widget file; a React component that drops into Medusa's Admin via a defined injection zone and tell you exactly where to put it. When you save the file, the Admin Dashboard hot-reloads and your widget appears.

You can extend this same approach to build supplier management pages, custom reporting views, internal approval flows, anything your operations team needs.

Step 6: How to Connect a Storefront

Medusa's backend is API-first: every piece of data and every action is available via REST API. Your storefront, the website customers actually visit, connects to those APIs to display products, handle carts, and process checkouts.

Medusa provides a Next.js Starter storefront you can use as a base. When setting up your project on Medusa Cloud, you can choose between a B2C and a B2B starter depending on your use case. To set it up, follow the guide at docs.medusajs.com/resources/nextjs-starter.

Once your storefront is running, you can use Claude Code to customize it the same way you customized the backend:

Copy to clipboardThe Medusa Next.js storefront currently shows products in a grid. I want to add a tab on each product page that displays the care_instructions field from the Medusa API. How do I do this?

Claude Code knows the Medusa Store API structure and can write the component that fetches and displays the data.

Step 7: How to Deploy to Medusa Cloud

When you're ready to take your store live, Medusa Cloud handles the rest. Connect your project to your Medusa Cloud account by running:

Copy to clipboardmedusa cloud login

Then push your project:

Copy to clipboardmedusa cloud deploy

Medusa Cloud will provision your database, set up your environment, and deploy your store. Once it's done, you'll get a live URL for your backend and Admin Dashboard.

From this point on, any changes you make locally can be deployed with the same command. If you want to test changes before pushing them live, Medusa Cloud supports preview environments, separate deployments connected to your repository that let you verify everything works before it reaches production.

A few things Cloud handles that you don't have to think about: database backups, scaling, environment variables, and email delivery via Medusa Emails.

What Can You Build With This Stack?

Medusa's framework supports a wide range of commerce use cases out of the box:

• Standard DTC stores: products, checkout, orders, returns
• B2B portals: company accounts, custom pricing per customer group, bulk ordering
• Marketplaces: multiple vendors, split payments, per-vendor fulfillment
• Subscription commerce: recurring billing, dunning management
• Digital products: file delivery, license keys, download management
• Bundled products: configurable bundles with custom pricing
• Personalized products: custom design, made-to-order, and configurable items
• Multi-region stores: localized pricing, currencies, tax rules, and shipping per market
• Omnichannel: unified commerce across web, mobile and in-store
• POS: point-of-sale with shared inventory and order management
• OMS: order management system with custom fulfillment flows
• Custom ERP integrations: sync orders, inventory, and pricing with external systems

All of these are buildable in Medusa using the same pattern: describe what you want to Claude Code, have it implement inside Medusa's framework, verify the output, iterate.

For more on what you can build with Medusa, the documentation and Discord community are the best places to go next.

Common Questions

We’ve gathered some of the most common questions from first time Medusa users that are using Claude. Find answers below:

Do I need to know how to code to use Medusa? Not to get started. You need to be comfortable in a terminal (running commands, navigating folders) and able to read code well enough to verify what Claude Code writes. The more clearly you can describe what you want your store to do, the more effectively Claude Code can implement it inside Medusa's framework.

What is headless commerce and when should I use it? Headless commerce means the backend (your products, orders, pricing, etc.) is decoupled from the frontend that customers see and interact with. They communicate via API, which means you can build any storefront experience you want without being constrained by a platform's templates or checkout flow. Headless is the right approach when you need custom functionality that standard platforms can't support, when you're selling across multiple channels or markets, or when you expect your commerce requirements to evolve significantly over time. Medusa is a headless commerce framework, meaning all the core commerce logic is pre-built, but every layer is open for customization.

How can I build ecommerce using AI? The most effective approach today is to use a structured, well-documented commerce framework as the foundation and use an AI coding agent like Claude Code to build on top of it. Medusa is particularly well-suited to this because its framework follows predictable patterns that Claude Code can implement reliably. Rather than generating commerce logic from scratch, Claude Code works within Medusa's existing structure: extending data models, building workflows, customizing the admin, and connecting storefronts, all from plain-language instructions.

What's the difference between Medusa and Shopify? Shopify is a SaaS platform, you rent access to it, customize within its limits, and can't modify the core behavior. Medusa is an open-source framework: you own the code, you can change anything, and you're not paying per-transaction fees. The tradeoff: Medusa requires more setup than Shopify. That's exactly the gap this tutorial (and Claude Code) is designed to close.

Can I build a B2B store with Medusa? Yes. Medusa has first-class support for B2B commerce, including company accounts, customer groups, custom pricing per account, quote workflows, and bulk ordering. There's an official B2B recipe in the Medusa documentation with a full reference implementation, and a dedicated B2B Next.js storefront starter available when setting up your project on Medusa Cloud. Brands like Redington, India's largest IT distributor, have built their B2B operations on Medusa.

Can I deploy my Medusa store to production? Yes. Medusa Cloud is the hosted offering: it handles infrastructure, scaling, and deployment. You connect it to your GitHub repository and deploy directly. For self-hosted options, Medusa can be deployed to any Node.js-compatible host.