Medusa B2B Starter

Documentation | Website

Building blocks for digital commerce

Medusa B2B Starter

An official Medusa starter for B2B ecommerce, built with Medusa and Next.js 15. It covers common business-to-business requirements out of the box and is designed to be customized and extended.

Features

• Company management — Create and manage companies, invite employees, and assign roles
• Spending limits — Set per-employee spending limits with configurable reset frequencies
• Approval workflows — Require admin or sales manager approval before orders are placed
• Quote management — Allow customers and merchants to negotiate quotes with messaging
• Order editing — Adjust order items, pricing, and totals after placement
• Bulk add-to-cart — Add multiple products to the cart at once
• Promotions — Manual and automatic promotion support with free shipping progress
• Full ecommerce — Products, collections, cart, checkout, and order history

Getting Started

Deploy with Medusa Cloud

The fastest way to get started is deploying with Medusa Cloud:

1. Create a Medusa Cloud account
2. Deploy this starter directly from your dashboard

Local Installation

Prerequisites:

• Node.js v22.22+
• PostgreSQL v15+
• pnpm v9 (pinned to pnpm@9.15.0 via packageManager)

1. Clone the repository and install dependencies:

git clone https://github.com/medusajs/b2b-starter.git
cd b2b-starter
pnpm install

2. Set up environment variables for the backend:

cp apps/backend/.env.template apps/backend/.env

3. Set the database URL in apps/backend/.env:

# Replace with actual database URL, make sure the database exists.
DATABASE_URL=postgres://postgres:@localhost:5432/medusa-b2b-starter

4. Run migrations:

cd apps/backend
pnpm medusa db:migrate

5. Add admin user:

cd apps/backend
pnpm medusa user -e admin@test.com -p supersecret

6. Start Medusa backend:

cd apps/backend
pnpm dev

7. Open the admin dashboard at localhost:9000/app and log in. Retrieve your publishable API key at Settings > Publishable API key.

8. Set up environment variables for the storefront:

cp apps/storefront/.env.template apps/storefront/.env.local

9. Update apps/storefront/.env.local with your Medusa publishable API key:

NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_6c3...

10. Start storefront:

cd apps/storefront
pnpm dev

The storefront runs on http://localhost:8000.

You can also run the following command from the root to start both backend and storefront:

pnpm dev

Project Structure

apps/
├── backend/      # Medusa v2 app: custom modules (company, quote, approval), API routes, workflows, admin extensions
└── storefront/   # Next.js 15 App Router storefront

The repo is a pnpm workspace orchestrated by Turborepo. Root scripts (dev, build, lint, test:integration:http) run in each app.

Configuration

Backend (apps/backend/.env)

Variable	Description
DATABASE_URL	PostgreSQL connection string
REDIS_URL	Redis connection string (optional)
JWT_SECRET	Secret used to sign JWT tokens
COOKIE_SECRET	Secret used to sign session cookies
STORE_CORS / ADMIN_CORS / AUTH_CORS	Allowed origins for the store, admin, and auth APIs

Storefront (apps/storefront/.env.local)

Variable	Description
NEXT_PUBLIC_MEDUSA_BACKEND_URL	URL of the Medusa backend
NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY	Publishable API key (required)
NEXT_PUBLIC_BASE_URL	Public URL of the storefront
NEXT_PUBLIC_DEFAULT_REGION	Default region code (e.g. us)
NEXT_PUBLIC_MEDUSA_PAYMENTS_PUBLISHABLE_KEY	Medusa Payments publishable key (optional)
NEXT_PUBLIC_MEDUSA_PAYMENTS_ACCOUNT_ID	Medusa Payments account ID (optional)
REVALIDATE_SECRET	Secret for on-demand cache revalidation

Building with AI Agents

• AGENTS.md: commands, structure, where to find things, and conventions for coding agents.
• Package docs: installed @medusajs/* packages ship an AGENTS.md in node_modules/@medusajs/<pkg>/ (Medusa releases after v2.21.2).
• Medusa agent skills for backend, admin, and storefront work.
• Docs MCP server: claude mcp add --transport http medusa https://docs.medusajs.com/mcp
• Medusa Cloud MCP server (Cloud users): claude mcp add --transport http medusa-cloud https://cloud.medusajs.com/mcp

Resources

• Medusa Documentation
• Medusa B2B Commerce Recipe
• Build with LLMs and AI
• Medusa docs for LLMs (llms.txt)
• Next.js Documentation
• Discord Community

License

Licensed under the MIT License.