payloadcms-ecommerce-3-84-1

name	payloadcms-ecommerce-3-84-1
description	Payload CMS ecommerce template providing production-ready online store with products, variants, carts, orders, Stripe payments, and user accounts. Use when building e-commerce platforms, online stores, or any digital commerce project requiring product catalogs, shopping carts, order management, payment processing, or inventory management following official Payload best practices.

Payload CMS Ecommerce Template v3.84.1

Overview

The official Payload Ecommerce Template is a production-ready, full-stack ecommerce solution built on Payload CMS v3 with Next.js App Router. It provides a complete online store with a working backend, enterprise-grade admin panel, and a beautifully designed frontend — all in a single deployable application.

The template uses the @payloadcms/plugin-ecommerce package to provide collections for products, variants, carts, orders, transactions, and addresses. Stripe is the default payment adapter. The frontend is built with Next.js 16, Tailwind CSS 4, shadcn/ui components, and React Hook Form.

New in 3.83/3.84:

• Locale-aware currency formatting with symbol positioning in the ecommerce plugin
• PaymentIntent verification — Stripe PaymentIntent success verified before creating orders
• definePlugin helper for type-safe plugin development with execution ordering
• Multipart upload support in form builder for file attachments
• Custom collection views with client components

When to Use

• Building a new ecommerce platform or online store from scratch
• Creating marketplaces with product catalogs and shopping carts
• Implementing payment processing with Stripe in a Payload project
• Setting up guest checkout flows with secure order access
• Building stores that need multi-currency support with locale-aware formatting
• Adding ecommerce functionality to an existing Payload CMS site
• Prototyping commerce features rapidly with a production-ready foundation

Quick Start

Create the project using the Payload CLI:

pnpx create-payload-app my-project -t ecommerce

Then set up locally:

cd my-project
cp .env.example .env
pnpm install && pnpm dev

Open http://localhost:3000 and follow on-screen instructions to create the first admin user.

Required Environment Variables

• PAYLOAD_SECRET — Application secret for signing JWTs
• DATABASE_URL — MongoDB connection string (default adapter)
• STRIPE_SECRET_KEY — Stripe secret API key
• NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY — Stripe publishable key
• STRIPE_WEBHOOKS_SIGNING_SECRET — Stripe webhook signing secret
• PAYLOAD_PUBLIC_SERVER_URL — Server URL for Payload
• NEXT_PUBLIC_SERVER_URL — Server URL for the frontend
• PREVIEW_SECRET — Secret for draft preview authentication

Core Architecture

The template follows a unified monorepo structure where Payload backend and Next.js frontend share a single instance:

src/
├── access/              # Access control functions
├── app/
│   ├── (app)/           # Frontend routes (Next.js App Router)
│   └── (payload)/       # Payload admin & API routes
├── blocks/              # Layout builder blocks
├── collections/         # Collection configurations
├── components/          # Custom React components
├── endpoints/           # Seed data endpoint
├── fields/              # Reusable field definitions
├── fonts/               # Custom fonts
├── globals/             # Global configurations (Header, Footer)
├── hooks/               # Lifecycle hooks
├── lib/                 # Utility libraries
├── plugins/             # Plugin configuration (ecommerce, SEO, forms)
├── providers/           # React context providers
└── utilities/           # Shared utility functions

Collections Overview

The template defines these core collections:

• Users — Auth-enabled with admin and customer roles. Join fields link to orders, carts, and addresses.
• Pages — Layout-builder enabled with draft/publish workflow, live preview, and SEO.
• Media — Upload collection for images, videos, and assets with pre-configured sizes and focal point.
• Categories — Taxonomy for grouping products.

The ecommerce plugin adds:

• Products — Product catalog with pricing per currency, variants, gallery, and layout blocks.
• Variants — Variant definitions (when enabled) with independent pricing and inventory.
• Variant Types — Variant dimension types (e.g., Size, Color).
• Variant Options — Specific variant values (e.g., "Large", "Red").
• Carts — Shopping carts for authenticated and guest users.
• Orders — Completed purchase records with line items, addresses, and totals.
• Transactions — Payment tracking from initiation to completion.
• Addresses — Saved shipping and billing addresses for customers.

Plugin Configuration

The ecommerce plugin is configured in src/plugins/index.ts:

import { ecommercePlugin } from '@payloadcms/plugin-ecommerce'
import { stripeAdapter } from '@payloadcms/plugin-ecommerce/payments/stripe'

export const plugins: Plugin[] = [
  ecommercePlugin({
    access: {
      adminOnlyFieldAccess,
      adminOrPublishedStatus,
      customerOnlyFieldAccess,
      isAdmin,
      isDocumentOwner,
    },
    customers: {
      slug: 'users',
    },
    orders: {
      ordersCollectionOverride: ({ defaultCollection }) => ({
        ...defaultCollection,
        fields: [
          ...defaultCollection.fields,
          { name: 'accessToken', type: 'text', unique: true, index: true, /* ... */ },
        ],
      }),
    },
    payments: {
      paymentMethods: [
        stripeAdapter({
          secretKey: process.env.STRIPE_SECRET_KEY!,
          publishableKey: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!,
          webhookSecret: process.env.STRIPE_WEBHOOKS_SIGNING_SECRET!,
        }),
      ],
    },
    products: {
      productsCollectionOverride: ProductsCollection,
    },
  }),
]

Locale-Aware Currency Formatting (New in 3.84)

The ecommerce plugin now supports locale-aware currency formatting with symbol positioning:

ecommercePlugin({
  // ...
  currencies: [
    { code: 'USD', symbol: '$', position: 'before' },
    { code: 'EUR', symbol: '€', position: 'after' },
    { code: 'GBP', symbol: '£', position: 'before' },
    { code: 'JPY', symbol: '¥', position: 'before' },
  ],
})

Frontend Routes

The Next.js frontend provides these key routes:

• / — Homepage (layout builder page)
• /[slug] — Dynamic page routes
• /shop — Product catalog with search and filters
• /products/[slug] — Individual product pages
• /checkout — Checkout flow with cart review and payment
• /checkout/confirm-order — Post-payment confirmation
• /login, /create-account, /logout — Authentication
• /find-order — Guest order lookup
• /account — Customer account dashboard
• /account/addresses — Address management
• /orders — Order history
• /orders/[id] — Individual order details

Advanced Topics

Plugin Configuration Reference: Full ecommerce plugin config options, collection overrides, access control patterns, locale-aware currency formatting → Plugin Configuration

Products and Variants: Product catalog structure, variant types/options, pricing per currency, inventory management, gallery, related products → Products and Variants

Carts and Checkout: Cart operations, guest carts, item matching, checkout flow, payment initiation, order confirmation → Carts and Checkout

Orders and Transactions: Order lifecycle, transaction tracking, Stripe webhooks with PaymentIntent verification, guest order access with accessToken → Orders and Transactions

Access Control Patterns: Role-based access (admin/customer), document ownership, published status filtering, field-level security → Access Control

Frontend Architecture: Next.js App Router structure, React context for ecommerce state, Stripe Elements integration, layout builder blocks → Frontend Architecture

Deployment and Production: Build process, Vercel deployment, PostgreSQL adapter, migrations, scheduled publishing, caching strategy → Deployment and Production