Skip to content

Home

Jump to bottom
Victor Gerbrands edited this page Feb 21, 2025 · 3 revisions

Overview

Welcome to the official wiki for the Medusa Next.js B2B Starter Kit! This starter kit provides a robust foundation for building B2B commerce platforms with Medusa and Next.js. It includes common B2B commerce requirements and is designed to be easily adapted and extended.

Key Features

  • Company Management: Customers can manage their company and invite employees.
  • Spending Limits: Company admins can assign spending limits to their employees.
  • Bulk Add-to-Cart: Customers can add multiple variants of a product to their cart at once.
  • Quote Management: Customers & Merchants can communicate, accept, or reject quotes.
  • Order Edit: Merchants can edit orders or quotes—add/remove items, update quantity & price management, and more.
  • Company Approvals: Companies can mandate approvals from company admins before employees finalize a cart.
  • Merchant Approvals: Merchants can set up approval processes for orders, ensuring compliance with business rules before fulfillment.
  • Promotions: Customers can apply manual and automatic promotions to their cart.
  • Free Shipping Nudge: Displays a component showing progress toward free shipping.
  • Full eCommerce Support
    • Product Pages
    • Product Collections & Categories
    • Cart & Checkout
    • User Accounts
    • Order Details
  • Full Next.js 15 Support
    • App Router
    • Caching
    • Server Components/Actions
    • Streaming
    • Static Pre-Rendering

Demo

Medusa B2B Starter Demo

Key Features Explained

A detailed overview of the key features included in the Medusa B2B Starter template. These features are designed to address common B2B commerce requirements and can be easily adapted and extended.

Modules

Key B2B modules include:

  • Company: Manages companies and employees.
  • Approval: Handles approval flows for carts and orders.
  • Quote: Manages quotes and quote messages.

Data Model

Company, Employee and Approval

%%{init: {"flowchart": {"htmlLabels": false}} }%%
flowchart LR
    subgraph "Legend"
      C["Core Model"]:::core;
      M["Custom Model"]:::custom;
    end
    subgraph " "
	    Company -->|has many| Employee
	    Employee -->|has one| Customer
	    Company -->|has many| Cart
	    Company -->|has one| ApprovalSettings
	    Company -->|has many| CustomerGroup
	    Cart -->|has many| Approval
	    Cart -->|has one| ApprovalStatus
    end

    %% Core entities with purple background
    classDef core fill:#3B3B3B,stroke:#B3B3B3,stroke-width:1px,color:#F5F5F5;
    class Customer core;
    class Cart core;
    class CustomerGroup core;

    %% Custom entities with gray background
    classDef custom fill:#6D28D9,stroke:#B3B3B3,stroke-width:1px,color:#EDE9FE;
    class Employee custom;
    class ApprovalSettings custom;
    class Approval custom;
    class ApprovalStatus custom;
    class Company custom;
Loading

Quotes

%%{init: {"flowchart": {"htmlLabels": false}} }%%
flowchart LR
    subgraph "Legend"
        C["Core Model"]:::core;
        M["Custom Model"]:::custom;
    end
    subgraph " "
        Quote --> |has one| Order
        Quote --> |has one| Cart
        Quote --> |has one| OrderChange
        Quote --> |has one| User
        Quote --> |has one| Customer
    end

%% Core entities with purple background
classDef core fill:#3B3B3B,stroke:#B3B3B3,stroke-width:1px,color:#F5F5F5;
class Order,OrderChange,Customer,Cart,User,C core;

%% Custom entities with gray background
classDef custom fill:#6D28D9,stroke:#B3B3B3,stroke-width:1px,color:#EDE9FE;
class Quote,M custom;
Loading

Company Management

Functionality: This feature enables customers to manage their company profiles and extend access to other employees.

company-dash.mp4

Details:

  • Create and manage company profiles with details like name, address, and contact information
  • Manage company employees
  • Set company-wide policies and spending limits

Related Files:

  • /backend/src/modules/company/models/company.ts: Defines the Company model with fields for company information
  • /backend/src/modules/company/models/employee.ts: Defines the Employee model with spending limit and admin status
  • /backend/src/api/store/companies: API for company and employee management from the storefront.
  • /backend/src/api/admin/companies: API for company and employee management from the Medusa admin.
  • /backend/src/admin/routes/companies: Admin routes for company management in the Medusa admin interface.
  • /backend/src/workflows/company: Contains company-related workflows including company CRUD and assigning customer groups.
  • /backend/src/workflows/employee: Contains employee CRUD workflows.

Spending Limits

Functionality: Company administrators can assign spending limits to individual employees.

employee-loop.mp4

Details:

  • Control over employee purchasing
  • Configurable reset frequencies for spending limits

Related Files:

  • /backend/src/modules/company/models/employee.ts: Contains spending limit field
  • /backend/src/modules/company/models/company.ts: Contains spending limit reset configuration
  • /backend/src/workflows/hooks/validate-cart-completion.ts: Validates if spending limit isn’t exceeded by completing this cart.

Bulk Add-to-Cart

Functionality: Enables customers to add multiple variants of a product to their cart simultaneously.

bulk-loop.mp4

Details:

  • Streamlines ordering process for B2B bulk purchases

Related Files:

  • /backend/src/api/store/carts/[id]/line-items/bulk/route.ts: Bulk add API endpoint

Quote Management

Functionality: Facilitates communication and negotiation between customers and merchants regarding quotes.

tWyZiznoqbmrMc5l.mp4

Details:

  • Request quotes for carts.
  • Review, modify, and send quotes.
  • Accept or reject quote proposals.

Related Files:

  • /backend/src/modules/quote/: Quote module and models
  • /backend/src/api/admin/quotes/: Admin quote management
  • /backend/src/api/store/quotes/: Storefront quote management
  • /backend/src/admin/routes/quotes/: Admin quote UI route

Order Edit

Functionality: Allows merchants to modify orders or quotes.

Details:

  • Flexible order modification for customer requests

Related Files:

  • Uses existing cart and order modules
  • /backend/src/workflows/order/workflows/update-order.ts: Order update logic

Company Approvals

Functionality: Requires company admin approval for cart finalization.

approvals-full.mp4

Details:

  • Ensures compliance with company policies
  • Cart locking system pending approval

Related Files:

  • /backend/src/modules/approval/: Approval module core
  • /backend/src/api/admin/approvals/: Admin approval endpoints
  • /backend/src/api/store/approvals/: Storefront approval endpoints
  • /backend/src/admin/routes/approvals/: Admin approval routes
  • /backend/src/workflows/hooks: Contains multiple cart validation hooks that handle cart locking.

Merchant Approvals

Functionality: Enables merchant approval processes for orders.

Details:

  • Ensures business rule compliance before fulfillment

Related Files:

  • /backend/src/modules/approval/: Approval module core
  • /backend/src/workflows/approval/workflows/: Approval workflows
  • /backend/src/api/admin/approvals/: Admin approval endpoints
  • /backend/src/api/store/approvals/: Storefront approval endpoints
Clone this wiki locally