Payloadcms Ecommerce 3 84 1

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