payloadcms-ecommerce-3-84-1 - SKILL.md Agent Skill

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