Ecommerce Plugin

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

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.

The plugin requires access control functions in order to restrict permissions to certain collections or fields. You must provide these functions in the access option.

The plugin provides default implementations for publicAccess only:

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

Example:

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

Example:

Checks if the user is a customer (authenticated but not an admin). This is used internally to auto-assign the customer ID when creating addresses - customers can only create addresses for themselves, while admins can create addresses for any customer.

Example:

Access control to check if the user has admin permissions.

Example:

Access control to check if the user is authenticated (any role).

Example:

Access control to check if the user owns the document being accessed via the customer field. Returns a Where query to filter documents by the customer field.

Example:

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

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:

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

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:

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

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

By default, guest carts are enabled (allowGuestCarts: true), allowing unauthenticated users to create and manage carts. This is useful for anonymous checkout flows where users can shop without logging in.

To disable guest carts and require authentication:

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.

When guest carts are enabled and 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.

The plugin automatically adds custom endpoints to the carts collection for managing cart items. These endpoints use a reducer-like pattern with MongoDB-style operators for flexible updates.

Adds an item to the cart. If an item matching the same criteria already exists (determined by the cartItemMatcher), its quantity is incremented instead of creating a duplicate entry.

Updates an item in the cart. Supports both setting a specific quantity and incrementing/decrementing using MongoDB-style operators.

Examples:

Removes an item from the cart by its row ID.

Removes all items from the cart.

The cartItemMatcher option allows you to customize how the plugin determines if two cart items should be considered the same. When items match, their quantities are combined instead of creating separate entries. When items don't match, they appear as separate line items in the cart.

By default, items are matched by product and variant IDs only. This means if a customer adds the same product twice, the quantity is incremented rather than creating a duplicate entry.

However, many ecommerce scenarios require distinguishing the same product based on additional criteria:

• Fulfillment options: Same product for shipping vs. in-store pickup
• Gift wrapping: Same item with or without gift wrapping
• Personalization: Same product with different engraving text
• Subscription intervals: Same product with weekly vs. monthly delivery

The cartItemMatcher function receives both the existing cart item and the new item being added, and returns true if they should be combined or false if they should remain separate.

This example shows how to allow the same product to appear as separate cart items when different fulfillment options (shipping vs. pickup) are selected.

First, add a fulfillment field to cart items using cartsCollectionOverride:

Then, when adding items to the cart from the frontend, include the fulfillment field:

You can import and extend the default matcher for simpler customizations:

The plugin exports isolated cart operation functions that can be used directly in your own endpoints, hooks, or local API operations:

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.

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.

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:

The Currency type is as follows:

For example, to support JYP in addition to USD:

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:

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

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.

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

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:

Client side base arguments are the following:

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

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:

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

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.

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.

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:

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

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

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

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.

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:

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.

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:

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

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:

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

The plugin includes translations for admin UI labels and messages under the plugin-ecommerce namespace. To add the plugin's translations to your Payload config, use the i18n.translations key.

Import the plugin translations and add them to your Payload config:

You can override specific translation strings by providing your own values under the plugin-ecommerce namespace: