Ecommerce Plugin

import { buildConfig } from 'payload'
import { ecommercePlugin } from '@payloadcms/plugin-ecommerce'

const config = buildConfig({
  collections: [
    {
      slug: 'pages',
      fields: [],
    },
  ],
  plugins: [
    ecommercePlugin({
      // You must add your access control functions here
      access: {
        adminOnlyFieldAccess,
        adminOrPublishedStatus,
        isAdmin,
        isAuthenticated,
        isCustomer,
        isDocumentOwner,
      },
      customers: { slug: 'users' },
    }),
  ],
})

export default config

ecommercePlugin({
  access: {
    adminOnlyFieldAccess,
    adminOrPublishedStatus,
    isAdmin,
    isAuthenticated,
    isCustomer,
    isDocumentOwner,
  },
  customers: {
    slug: 'users',
  },
  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: {
    variants: {
      variantsCollection: VariantsCollection,
    },
    productsCollection: ProductsCollection,
  },
})

access: {
  publicAccess: () => true,
}

adminOnlyFieldAccess: ({ req: { user } }) =>
  Boolean(user?.roles?.includes('admin'))

adminOrPublishedStatus: ({ req: { user } }) => {
  if (user && Boolean(user?.roles?.includes('admin'))) {
    return true
  }
  return {
    _status: {
      equals: 'published',
    },
  }
}

isCustomer: ({ req: { user } }) =>
  Boolean(user && !user?.roles?.includes('admin'))

isAdmin: ({ req: { user } }) => Boolean(user?.roles?.includes('admin'))

isAuthenticated: ({ req: { user } }) => Boolean(user)

isDocumentOwner: ({ req: { user } }) => {
  if (user && Boolean(user?.roles?.includes('admin'))) {
    return true
  }

  if (user?.id) {
    return {
      customer: {
        equals: user.id,
      },
    }
  }

  return false
}

publicAccess: () => true

addresses: {
  addressesCollectionOverride: ({ defaultCollection }) => ({
    ...defaultCollection,
    fields: [
      ...defaultCollection.fields,
      {
        name: 'googleMapLocation',
        label: 'Google Map Location',
        type: 'text',
      },
    ],
  })
}

import { defaultCountries } from '@payloadcms/plugin-ecommerce/client/react'

carts: {
  cartsCollectionOverride: ({ defaultCollection }) => ({
    ...defaultCollection,
    fields: [
      ...defaultCollection.fields,
      {
        name: 'notes',
        label: 'Notes',
        type: 'textarea',
      },
    ],
  })
}

carts: {
  allowGuestCarts: false,
}

POST /api/carts/:cartID/add-item

POST /api/carts/:cartID/update-item

// Set quantity to 5
fetch('/api/carts/123/update-item', {
  method: 'POST',
  body: JSON.stringify({ itemID: 'item-456', quantity: 5 }),
})

// Increment by 1
fetch('/api/carts/123/update-item', {
  method: 'POST',
  body: JSON.stringify({ itemID: 'item-456', quantity: { $inc: 1 } }),
})

// Decrement by 1
fetch('/api/carts/123/update-item', {
  method: 'POST',
  body: JSON.stringify({ itemID: 'item-456', quantity: { $inc: -1 } }),
})

POST /api/carts/:cartID/remove-item

POST /api/carts/:cartID/clear

import type { CollectionConfig } from 'payload'
import type { CartItemMatcher } from '@payloadcms/plugin-ecommerce'
import { ecommercePlugin } from '@payloadcms/plugin-ecommerce'

/**
 * Custom cart item matcher that includes fulfillment option.
 * This ensures the same product with different fulfillment options
 * are listed as separate items in the cart.
 */
const fulfillmentCartItemMatcher: CartItemMatcher = ({
  existingItem,
  newItem,
}) => {
  const existingProductID =
    typeof existingItem.product === 'object'
      ? existingItem.product.id
      : existingItem.product

  const existingVariantID =
    existingItem.variant && typeof existingItem.variant === 'object'
      ? existingItem.variant.id
      : existingItem.variant

  const productMatches = existingProductID === newItem.product

  // Variant matching: both must have same variant or both must have no variant
  const variantMatches = newItem.variant
    ? existingVariantID === newItem.variant
    : !existingVariantID

  // Fulfillment matching: items with different fulfillment options are separate
  const existingFulfillment = existingItem.fulfillment as string | undefined
  const newFulfillment = newItem.fulfillment as string | undefined
  const fulfillmentMatches = existingFulfillment === newFulfillment

  return productMatches && variantMatches && fulfillmentMatches
}

export default buildConfig({
  // ... other config
  plugins: [
    ecommercePlugin({
      carts: {
        cartItemMatcher: fulfillmentCartItemMatcher,
        cartsCollectionOverride: ({ defaultCollection }): CollectionConfig => ({
          ...defaultCollection,
          fields: defaultCollection.fields.map((f) => {
            if ('name' in f && f.name === 'items' && f.type === 'array') {
              return {
                ...f,
                fields: [
                  ...f.fields,
                  {
                    name: 'fulfillment',
                    type: 'select',
                    defaultValue: 'shipping',
                    options: [
                      { label: 'Shipping', value: 'shipping' },
                      { label: 'Pickup', value: 'pickup' },
                    ],
                  },
                ],
              }
            }
            return f
          }),
        }),
      },
      // ... other options
    }),
  ],
})

const { addItem } = useCart()

// These will be separate line items in the cart
await addItem({ product: 'product-123', fulfillment: 'shipping' })
await addItem({ product: 'product-123', fulfillment: 'pickup' })

import {
  defaultCartItemMatcher,
  type CartItemMatcher,
  type CartItemMatcherArgs,
} from '@payloadcms/plugin-ecommerce'

const customMatcher: CartItemMatcher = (args) => {
  // First check the default criteria (product + variant)
  const defaultMatch = defaultCartItemMatcher(args)

  // Then add your custom criteria
  return defaultMatch && args.existingItem.giftWrap === args.newItem.giftWrap
}

import {
  addItem,
  removeItem,
  updateItem,
  clearCart,
} from '@payloadcms/plugin-ecommerce'

// Add item to cart
const result = await addItem({
  payload,
  cartsSlug: 'carts',
  cartID: '123',
  item: { product: 'prod-1', variant: 'var-1' },
  quantity: 2,
})

// Update item quantity with $inc operator
const result = await updateItem({
  payload,
  cartsSlug: 'carts',
  cartID: '123',
  itemID: 'item-row-id',
  quantity: { $inc: 1 }, // or just a number to set directly
})

// Remove item
const result = await removeItem({
  payload,
  cartsSlug: 'carts',
  cartID: '123',
  itemID: 'item-row-id',
})

// Clear cart
const result = await clearCart({
  payload,
  cartsSlug: 'carts',
  cartID: '123',
})

type Currency = {
  code: string // The currency code in ISO 4217 format, e.g. 'USD'
  decimals: number // The number of decimal places for the currency, e.g. 2 for USD
  label: string // A human-readable label for the currency, e.g. 'US Dollar'
  symbol: string // The currency symbol, e.g. '$'
}

import { ecommercePlugin } from '@payloadcms/plugin-ecommerce'
import { USD } from '@payloadcms/plugin-ecommerce'

ecommercePlugin({
  currencies: {
    supportedCurrencies: [
      USD,
      {
        code: 'JPY',
        decimals: 0,
        label: 'Japanese Yen',
        symbol: '¥',
      },
    ],
    defaultCurrency: 'USD',
  },
})

import { EUR } from '@payloadcms/plugin-ecommerce'

payments: {
  paymentMethods: [
    stripeAdapter({
      secretKey: process.env.STRIPE_SECRET_KEY,
      publishableKey: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
      webhookSecret: process.env.STRIPE_WEBHOOKS_SIGNING_SECRET,
      groupOverrides: {
        fields: ({ defaultFields }) => {
          return [
            ...defaultFields,
            {
              name: 'customField',
              label: 'Custom Field',
              type: 'text',
            },
          ]
        }
      }
    }),
  ],
},

pnpm add stripe

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

stripeAdapter({
  secretKey: process.env.STRIPE_SECRET_KEY!,
  publishableKey: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!,
  webhookSecret: process.env.STRIPE_WEBHOOKS_SIGNING_SECRET!,
})

stripeAdapter({
  webhooks: {
    'payment_intent.succeeded': ({ event, req }) => {
      // Access to Payload's req object and event data
    },
  },
}),

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

<EcommerceProvider
  paymentMethods={[
    stripeAdapterClient({
      publishableKey: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
    }),
  ]}
>
  {children}
</EcommerceProvider>

products: {
  productsCollectionOverride: ({ defaultCollection }) => ({
    ...defaultCollection,
    fields: [
      ...defaultCollection.fields,
      {
        name: 'notes',
        label: 'Notes',
        type: 'textarea',
      },
    ],
  })
}

variants: {
  variantsCollectionOverride: ({ defaultCollection }) => ({
    ...defaultCollection,
    fields: [
      ...defaultCollection.fields,
      {
        name: 'customField',
        label: 'Custom Field',
        type: 'text',
      },
    ],
  })
}

export const defaultProductsValidation: ProductsValidation = ({
  currenciesConfig,
  currency,
  product,
  quantity = 1,
  variant,
}) => {
  if (!currency) {
    throw new Error('Currency must be provided for product validation.')
  }

  const priceField = `priceIn${currency.toUpperCase()}`

  if (variant) {
    if (!variant[priceField]) {
      throw new Error(
        `Variant with ID ${variant.id} does not have a price in ${currency}.`,
      )
    }

    if (
      variant.inventory === 0 ||
      (variant.inventory && variant.inventory < quantity)
    ) {
      throw new Error(
        `Variant with ID ${variant.id} is out of stock or does not have enough inventory.`,
      )
    }
  } else if (product) {
    // Validate the product's details only if the variant is not provided as it can have its own inventory and price
    if (!product[priceField]) {
      throw new Error(`Product does not have a price in.`, {
        cause: { code: MissingPrice, codes: [product.id, currency] },
      })
    }

    if (
      product.inventory === 0 ||
      (product.inventory && product.inventory < quantity)
    ) {
      throw new Error(
        `Product is out of stock or does not have enough inventory.`,
        {
          cause: { code: OutOfStock, codes: [product.id] },
        },
      )
    }
  }
}

orders: {
  ordersCollectionOverride: ({ defaultCollection }) => ({
    ...defaultCollection,
    fields: [
      ...defaultCollection.fields,
      {
        name: 'notes',
        label: 'Notes',
        type: 'textarea',
      },
    ],
  })
}

transactions: {
  transactionsCollectionOverride: ({ defaultCollection }) => ({
    ...defaultCollection,
    fields: [
      ...defaultCollection.fields,
      {
        name: 'notes',
        label: 'Notes',
        type: 'textarea',
      },
    ],
  })
}

import { buildConfig } from 'payload'
import { ecommercePlugin } from '@payloadcms/plugin-ecommerce'
import { en } from '@payloadcms/translations/languages/en'
import { enTranslations as ecommerceEn } from '@payloadcms/plugin-ecommerce/translations/languages/en'

export default buildConfig({
  // ...
  i18n: {
    supportedLanguages: { en },
    translations: {
      en: ecommerceEn,
    },
  },
  plugins: [
    ecommercePlugin({
      /* ... */
    }),
  ],
})

import { buildConfig } from 'payload'
import { ecommercePlugin } from '@payloadcms/plugin-ecommerce'
import { en } from '@payloadcms/translations/languages/en'
import { enTranslations as ecommerceEn } from '@payloadcms/plugin-ecommerce/translations/languages/en'

export default buildConfig({
  // ...
  i18n: {
    supportedLanguages: { en },
    translations: {
      en: {
        ...ecommerceEn,
        'plugin-ecommerce': {
          ...ecommerceEn['plugin-ecommerce'],
          cart: 'Shopping Cart',
          orders: 'My Orders',
        },
      },
    },
  },
  plugins: [
    ecommercePlugin({
      /* ... */
    }),
  ],
})