Ecommerce Plugin

Basic Usage

In the plugins array of your Payload Config, call the plugin with:

1import { buildConfig } from 'payload'
2import { ecommercePlugin } from '@payloadcms/plugin-ecommerce'
3
4const config = buildConfig({
collections: [
  {
    slug: 'pages',
    fields: [],
  },
],
plugins: [
  ecommercePlugin({
    // You must add your access control functions here
    access: {
      adminOnly,
      adminOnlyFieldAccess,
      adminOrCustomerOwner,
      adminOrPublishedStatus,
      customerOnlyFieldAccess,
    },
    customers: { slug: 'users' },
  }),
],
24})
25
26export default config

Options

Option	Type	Description
`access`	`object`	Configuration to override the default access control, use this when checking for roles or multi tenancy. More
`addresses`	`object`	Configuration for addresses collection and supported fields. More
`carts`	`object`	Configuration for carts collection. More
`currencies`	`object`	Supported currencies by the store. More
`customers`	`object`	Used to provide the customers slug. More
`inventory`	`boolean` `object`	Enable inventory tracking within Payload. Defaults to `true`. More
`payments`	`object`	Configuring payments and supported payment methods. More
`products`	`object`	Configuration for products, variants collections and more. More
`orders`	`object`	Configuration for orders collection. More
`transactions`	`boolean` `object`	Configuration for transactions collection. More

Note that the fields in overrides take a function that receives the default fields and returns an array of fields. This allows you to add fields to the collection.

1ecommercePlugin({
access: {
  adminOnly,
  adminOnlyFieldAccess,
  adminOrCustomerOwner,
  adminOrPublishedStatus,
  customerOnlyFieldAccess,
},
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,
},
27})

Access

The plugin requires access control functions in order to restrict permissions to certain collections or fields. You can override these functions by providing your own in the access option.

Option	Type	Description
`authenticatedOnly`	`Access`	Authenticated access only, provided by default.
`publicAccess`	`Access`	Public access, provided by default.
`adminOnly`	`Access`	Limited to only admin users.
`adminOnlyFieldAccess`	`FieldAccess`	Limited to only admin users, specifically for Field level access control.
`adminOrCustomerOwner`	`Access`	Is the owner of the document via the `customer` field or is an admin.
`adminOrPublishedStatus`	`Access`	The document is published or user is admin.
`customerOnlyFieldAccess`	`FieldAccess`	Limited to customers only, specifically for Field level access control.

The default access control functions are:

1access: {
2  authenticatedOnly: ({ req: { user } }) => Boolean(user),
3  publicAccess: () => true,
4}

authenticatedOnly

Access control to check if the user is authenticated. By default the following is provided:

1authenticatedOnly: ({ req: { user } }) => Boolean(user)

publicAccess

Access control to allow public access. By default the following is provided:

1publicAccess: () => true

adminOnly

Access control to check if the user has admin permissions.

Example:

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

adminOnlyFieldAccess

Field level access control to check if the user has admin permissions.

Example:

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

adminOrCustomerOwner

Access control to check if the user has admin permissions or is the owner of the document via the customer field.

Example:

1adminOrCustomerOwner: ({ req: { user } }) => {
if (user && Boolean(user?.roles?.includes('admin'))) {
  return true
}
5
if (user?.id) {
  return {
    customer: {
      equals: user.id,
    },
  }
}
13
return false
15}

adminOrPublishedStatus

Access control to check if the user has admin permissions or if the document is published.

Example:

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

customerOnlyFieldAccess

Field level access control to check if the user has customer permissions.

Example:

1customerOnlyFieldAccess: ({ req: { user } }) =>
2  Boolean(user?.roles?.includes('customer'))

Addresses

The addresses option is used to configure the addresses collection and supported fields. Defaults to true which will create an addresses collection with default fields. It also takes an object:

Option	Type	Description
`addressFields`	`FieldsOverride`	A function that is given the `defaultFields` as an argument and returns an array of fields. Use this to customise the supported fields for stored addresses.
`addressesCollectionOverride`	`CollectionOverride`	Allows you to override the collection for `addresses` with a function where you can access the `defaultCollection` as an argument.
`supportedCountries`	`CountryType[]`	An array of supported countries in ISO 3166-1 alpha-2 format. Defaults to all countries.

You can add your own fields or modify the structure of the existing on in the collection. Example for overriding the default fields:

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

The supportedCountries option is an array of country codes in ISO 3166-1 alpha-2 format. This is used to limit the countries that can be selected when creating or updating an address. If not provided, all countries will be supported. Currently used for storing addresses only.

You can import the default list of countries from the plugin:

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

Carts

The carts option is used to configure the carts collection. Defaults to true which will create a carts collection with default fields. It also takes an object:

Option	Type	Description
`cartsCollectionOverride`	`CollectionOverride`	Allows you to override the collection for `carts` with a function where you can access the `defaultCollection` as an argument.

You can add your own fields or modify the structure of the existing on in the collection. Example for overriding the default fields:

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

Carts are created when a customer adds their first item to the cart. The cart is then updated as they add or remove items. The cart is linked to a Customer via the customer field. If the user is authenticated, this will be set to their user ID. If the user is not authenticated, this will be null. If the user is not authenticated, the cart ID is stored in local storage and used to fetch the cart on subsequent requests. Access control by default works so that if the user is not authenticated then they can only access carts that have no customer linked to them.

Customers

The customers option is required and is used to provide the customers collection slug. This collection is used to link orders, carts, and addresses to a customer.

Option	Type	Description
`slug`	`string`	The slug of the customers collection.

While it's recommended to use just one collection for customers and your editors, you can use any collection you want for your customers. Just make sure that your access control is checking for the correct collections as well.

Currencies

The currencies option is used to configure the supported currencies by the store. Defaults to true which will support USD. It also takes an object:

Option	Type	Description
`supportedCurrencies`	`Currency[]`	An array of supported currencies by the store. Defaults to `USD`. See Currencies for available currencies.
`defaultCurrency`	`string`	The default currency code to use for the store. Defaults to the first currency. Must be one of the `supportedCurrencies` codes.

The Currency type is as follows:

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

For example, to support JYP in addition to USD:

1import { ecommercePlugin } from '@payloadcms/plugin-ecommerce'
2import { USD } from '@payloadcms/plugin-ecommerce'
3
4ecommercePlugin({
currencies: {
  supportedCurrencies: [
    USD,
    {
      code: 'JPY',
      decimals: 0,
      label: 'Japanese Yen',
      symbol: '¥',
    },
  ],
  defaultCurrency: 'USD',
},
17})

Note that adding a new currency could generate a new schema migration as it adds new prices fields in your products.

We currently support the following currencies out of the box:

USD
EUR
GBP

You can import these from the plugin:

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

Inventory

The inventory option is used to enable or disable inventory tracking within Payload. It defaults to true. It also takes an object:

Option	Type	Description
`fieldName`	`string`	Override the field name used to track inventory. Defaults to `inventory`.

For now it's quite rudimentary tracking with no integrations to 3rd party services. It will simply add an inventory field to the variants collection and decrement the inventory when an order is placed.

Payments

The payments option is used to configure payments and supported payment methods.

Option	Type	Description
`paymentMethods`	`array`	An array of payment method adapters. Currently, only Stripe is supported. More

Payment adapters

The plugin supports payment adapters to integrate with different payment gateways. Currently, only the Stripe adapter is available. Adapters will provide a client side version as well with slightly different arguments.

Every adapter supports the following arguments in addition to their own:

Argument	Type	Description
`label`	`string`	Human readabale label for this payment adapter.
`groupOverrides`	`GroupField` with `FieldsOverride`	Use this to override the available fields for the payment adapter type.

Client side base arguments are the following:

Argument	Type	Description
`label`	`string`	Human readabale label for this payment adapter.

See the Stripe adapter for an example of client side arguments and the React section for usage.

`groupOverrides`

The groupOverrides option allows you to customize the fields that are available for a specific payment adapter. It takes a GroupField object with a fields function that receives the default fields and returns an array of fields. These fields are stored in transactions and can be used to collect additional information for the payment method. Stripe, for example, will track the paymentIntentID.

Example for overriding the default fields:

1payments: {
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',
          },
        ]
      }
    }
  }),
],
21},

Stripe Adapter

The Stripe adapter is used to integrate with the Stripe payment gateway. It requires a secret key, publishable key, and optionally webhook secret.

Argument	Type	Description
`secretKey`	`string`	Required for communicating with the Stripe API in the backend.
`publishableKey`	`string`	Required for communicating with the Stripe API in the client side.
`webhookSecret`	`string`	The webhook secret used to verify incoming webhook requests from Stripe.
`webhooks`	`WebhookHandler[]`	An array of webhook handlers to register within Payload's REST API for Stripe to callback.
`apiVersion`	`string`	The Stripe API version to use. See docs. This will be deprecated soon by Stripe's SDK, configure the API version in your Stripe Dashboard.
`appInfo`	`object`	The application info to pass to Stripe. See docs.

1import { stripeAdapter } from '@payloadcms/plugin-ecommerce/payments/stripe'
2
3stripeAdapter({
4  secretKey: process.env.STRIPE_SECRET_KEY!,
5  publishableKey: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!,
6  webhookSecret: process.env.STRIPE_WEBHOOKS_SIGNING_SECRET!,
7})

Stripe `webhooks`

The webhooks option allows you to register custom webhook handlers for Stripe events. This is useful if you want to handle specific events that are not covered by the default handlers provided by the plugin.

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

Stripe client side

On the client side, you can use the publishableKey to initialize Stripe and handle payments. The client side version of the adapter only requires the label and publishableKey arguments. Never expose the secretKey or webhookSecret keys on the client side.

1import { stripeAdapterClient } from '@payloadcms/plugin-ecommerce/payments/stripe'
2
3<EcommerceProvider
4  paymentMethods={[
5    stripeAdapterClient({
6      publishableKey: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
7    }),
8  ]}
9>
10  {children}
11</EcommerceProvider>

Products

The products option is used to configure the products and variants collections. Defaults to true which will create products and variants collections with default fields. It also takes an object:

Option	Type	Description
`productsCollectionOverride`	`CollectionOverride`	Allows you to override the collection for `products` with a function where you can access the `defaultCollection` as an argument.
`variants`	`boolean` `object`	Configuration for the variants collection. Defaults to true. More
`validation`	`ProductsValidation`	Customise the validation used for checking products or variants before a transaction is created or a payment can be confirmed. More

You can add your own fields or modify the structure of the existing on in the collections. Example for overriding the default fields:

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

Variants

The variants option is used to configure the variants collection. It takes an object:

Option	Type	Description
`variantsCollectionOverride`	`CollectionOverride`	Allows you to override the collection for `variants` with a function where you can access the `defaultCollection` as an argument.
`variantTypesCollectionOverride`	`CollectionOverride`	Allows you to override the collection for `variantTypes` with a function where you can access the `defaultCollection` as an argument.
`variantOptionsCollectionOverride`	`CollectionOverride`	Allows you to override the collection for `variantOptions` with a function where you can access the `defaultCollection` as an argument.

You can add your own fields or modify the structure of the existing on in the collection. Example for overriding the default fields:

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

The key differences between these collections:

variantTypes are the types of variants that a product can have, e.g. Size, Color.
variantOptions are the options for each variant type, e.g. Small, Medium, Large for Size.
variants are the actual variants of a product, e.g. a T-Shirt in Size Small and Color Red.

Products validation

We use an addition validation step when creating transactions or confirming payments to ensure that the products and variants being purchased are valid. This is to prevent issues such as purchasing a product that is out of stock or has been deleted.

You can customise this validation by providing your own validation function via the validation option which receives the following arguments:

Option	Type	Description
`currenciesConfig`	`CurrenciesConfig`	The full currencies configuration provided in the plugin options.
`product`	`TypedCollection`	The product being purchased.
`variant`	`TypedCollection`	The variant being purchased, if a variant was selected for the product otherwise it will be `undefined`.
`quantity`	`number`	The quantity being purchased.
`currency`	`string`	The currency code being used for the purchase.

The function should throw an error if the product or variant is not valid. If the function does not throw an error, the product or variant is considered valid.

The default validation function checks for the following:

A currency is provided.
The product or variant has a price in the selected currency.
The product or variant has enough inventory for the requested quantity.

1export const defaultProductsValidation: ProductsValidation = ({
currenciesConfig,
currency,
product,
quantity = 1,
variant,
7}) => {
if (!currency) {
  throw new Error('Currency must be provided for product validation.')
}
11
const priceField = `priceIn${currency.toUpperCase()}`
13
if (variant) {
  if (!variant[priceField]) {
    throw new Error(
      `Variant with ID ${variant.id} does not have a price in ${currency}.`,
    )
  }
20
  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] },
    })
  }
36
  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] },
      },
    )
  }
}
49}

Orders

The orders option is used to configure the orders collection. Defaults to true which will create an orders collection with default fields. It also takes an object:

Option	Type	Description
`ordersCollectionOverride`	`CollectionOverride`	Allows you to override the collection for `orders` with a function where you can access the `defaultCollection` as an argument.

You can add your own fields or modify the structure of the existing on in the collection. Example for overriding the default fields:

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

Transactions

The transactions option is used to configure the transactions collection. Defaults to true which will create a transactions collection with default fields. It also takes an object:

Option	Type	Description
`transactionsCollectionOverride`	`CollectionOverride`	Allows you to override the collection for `transactions` with a function where you can access the `defaultCollection` as an argument.

You can add your own fields or modify the structure of the existing on in the collection. Example for overriding the default fields:

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

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.

Ecommerce Plugin

Basic Usage

Options

Access

authenticatedOnly

publicAccess

adminOnly

adminOnlyFieldAccess

adminOrCustomerOwner

adminOrPublishedStatus

customerOnlyFieldAccess

Addresses

supportedCountries

Carts

Customers

Currencies

Inventory

Payments

Payment adapters

`groupOverrides`

Stripe Adapter

Stripe `webhooks`

Stripe client side

Products

Variants

Products validation

Orders

Transactions

Ecommerce Frontend

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.

Ecommerce Plugin

Basic Usage

Options

Access

authenticatedOnly

publicAccess

adminOnly

adminOnlyFieldAccess

adminOrCustomerOwner

adminOrPublishedStatus

customerOnlyFieldAccess

Addresses

supportedCountries

Carts

Customers

Currencies

Inventory

Payments

Payment adapters

groupOverrides

Stripe Adapter

Stripe webhooks

Stripe client side

Products

Variants

Products validation

Orders

Transactions

Ecommerce Frontend

`groupOverrides`

Stripe `webhooks`