Ecommerce Frontend

The package provides a set of React utilities to help you manage your ecommerce frontend. These include context providers, hooks, and components to handle carts, products, and payments.

The following hooks and components are available:

Hook / Component	Description
`EcommerceProvider`	A context provider to wrap your application and provide the ecommerce context.
`useCart`	A hook to manage the cart state and actions.
`useAddresses`	A hook to fetch and manage addresses.
`usePayments`	A hook to manage the checkout process.
`useCurrency`	A hook to format prices based on the selected currency.
`useEcommerceConfig`	A hook to access the ecommerce configuration (collection slugs, API settings).
`useEcommerce`	A hook that encompasses all of the above in one.

EcommerceProvider

The EcommerceProvider component is used to wrap your application and provide the ecommerce context. It takes the following props:

Prop	Type	Description
`addressesSlug`	`string`	The slug of the addresses collection. Defaults to `addresses`.
`api`	`object`	API configuration for the internal fetches of the provider. More
`cartsSlug`	`string`	The slug of the carts collection. Defaults to `carts`.
`children`	`ReactNode`	The child components that will have access to the ecommerce context.
`currenciesConfig`	`CurrenciesConfig`	Configuration for supported currencies. See Currencies.
`customersSlug`	`string`	The slug of the customers collection. Defaults to `users`.
`debug`	`boolean`	Enable or disable debug mode. This will send more information to the console.
`enableVariants`	`boolean`	Enable or disable product variants support. Defaults to `true`.
`paymentMethods`	`PaymentMethod[]`	An array of payment method adapters for the client side. See Payment adapters.
`syncLocalStorage`	`boolean` `object`	Whether to sync the cart ID to local storage. Defaults to `true`. Takes an object for configuration

Example usage:

1import { EcommerceProvider } from '@payloadcms/plugin-ecommerce/client/react'
2// Import any payment adapters you want to use on the client side
3import { stripeAdapterClient } from '@payloadcms/plugin-ecommerce/payments/stripe'
4import { USD, EUR } from '@payloadcms/plugin-ecommerce'
5
6export const Providers = () => (
7  <EcommerceProvider
8    enableVariants={true}
9    currenciesConfig={{
10      supportedCurrencies: [USD, EUR],
11      defaultCurrency: 'USD',
12    }}
13  >
14    {children}
15  </EcommerceProvider>
16)

api

The api prop is used to configure the API settings for the internal fetches of the provider. It takes an object with the following properties:

Property	Type	Description
`apiRoute`	`string`	The base route for accessing the Payload API. Defaults to `/api`.
`serverURL`	`string`	The full URL of your Payload server.
`cartsFetchQuery`	`object`	Additional query parameters to include when fetching the cart.

The cartsFetchQuery property allows you to specify additional query parameters to include when fetching the cart. This can be useful for including related data or customizing the response. This accepts:

Property	Type	Description
`depth`	`string`	Defaults to 0. See Depth
`select`	`SelectType`	Select parameters. See Select
`populate`	`PopulateType`	Populate parameters. See Populate

Example usage:

1<EcommerceProvider
2  api={{
3    cartsFetchQuery: {
4      depth: 2, // Include related data up to 2 levels deep
5    },
6  }}
7>
8  {children}
9</EcommerceProvider>

syncLocalStorage

The syncLocalStorage prop is used to enable or disable syncing the cart ID to local storage. This allows the cart to persist across page reloads and sessions. It defaults to true.

You can also provide an object with the following properties for more configuration:

Property	Type	Description
`key`	`string`	The key to use for storing the cart ID in local storage. Defaults to `cart`.

useCart

The useCart hook is used to manage the cart state and actions. It provides methods to add, remove, and update items in the cart, as well as to fetch the current cart state. It has the following properties:

Property	Type	Description
`addItem`	`(item: CartItemInput, quantity?: number) => void`	Method to add an item to the cart, optionally accepts a quantity to add multiple at once.
`cart`	`Cart` `null`	The current cart state. Null or undefined if it doesn't exist.
`clearCart`	`() => void`	Method to clear the cart.
`decrementItem`	`(item: IDType) => void`	Method to decrement the quantity of an item. Will remove it entirely if it reaches 0.
`incrementItem`	`(item: IDType) => void`	Method to increment the quantity of an item.
`isLoading`	`boolean`	Boolean indicating if any async operation is in progress (e.g., adding/removing items).
`removeItem`	`(item: IDType) => void`	Method to remove an item from the cart.

Example usage:

1import { useCart } from '@payloadcms/plugin-ecommerce/client/react'
2
3const CartComponent = () => {
4  const {
5    addItem,
6    cart,
7    clearCart,
8    decrementItem,
9    incrementItem,
10    isLoading,
11    removeItem,
12  } = useCart()
13
14  // Your component logic here
15  // Use isLoading to show loading states in your UI
16}

useAddresses

The useAddresses hook is used to fetch and manage addresses. It provides methods to create, update, and delete addresses, as well as to fetch the list of addresses. It has the following properties:

Property	Type	Description
`addresses`	`Address[]`	The list of addresses, if any are available for the current user.
`createAddress`	`(data: Address) => Promise<Address>`	Method to create a new address.
`isLoading`	`boolean`	Boolean indicating if any async operation is in progress (e.g., creating/updating address).
`updateAddress`	`(addressID: IDType, data: Partial<Address>) => Promise<Address>`	Method to update an existing address by ID.

Example usage:

1import { useAddresses } from '@payloadcms/plugin-ecommerce/client/react'
2
3const AddressesComponent = () => {
4  const { addresses, createAddress, isLoading, updateAddress } = useAddresses()
5
6  // Your component logic here
7  // Use isLoading to show loading states while creating or updating addresses
8}

usePayments

The usePayments hook is used to manage the checkout process. It provides methods to initiate payments, confirm orders, and handle payment status. It has the following properties:

Property	Type	Description
`confirmOrder`	`(args) => Promise<Order>`	Method to confirm an order by ID. More
`initiatePayment`	`(args) => Promise<void>`	Method to initiate a payment for an order. More
`isLoading`	`boolean`	Boolean indicating if any async operation is in progress (e.g., initiating/confirming order).
`paymentMethods`	`PaymentMethod[]`	The list of available payment methods.
`selectedPaymentMethod`	`PaymentMethod`	The currently selected payment method, if any.

Example usage:

1import { usePayments } from '@payloadcms/plugin-ecommerce/client/react'
2
3const CheckoutComponent = () => {
4  const {
5    confirmOrder,
6    initiatePayment,
7    isLoading,
8    paymentMethods,
9    selectedPaymentMethod,
10  } = usePayments()
11
12  // Your component logic here
13  // Use isLoading to show loading states during payment initiation or order confirmation
14}

confirmOrder

Use this method to confirm an order by its ID. It requires the payment method ID and will return the order ID.

1try {
const data = await confirmOrder('stripe', {
  additionalData: {
    paymentIntentID: paymentIntent.id,
    customerEmail,
  },
})
// Return type will contain `orderID`
// use data to redirect to your order page
10} catch (error) {
// handle error
12}

If the payment gateway requires additional confirmations offsite then you will need another landing page to handle that. For example with Stripe you may need to use a callback URL, just make sure the relevant information is routed back.

initiatePayment

Use this method to initiate a payment for an order. It requires the cart ID and the payment method ID. Depending on the payment method, additional data may be required. Depending on the payment method used you may need to provide additional data, for example with Stripe:

1try {
const data = await initiatePayment('stripe', {
  additionalData: {
    customerEmail,
    billingAddress,
    shippingAddress,
  },
})
9} catch (error) {
// handle error
11}

This function will hit the Payload API endpoint for /stripe/initiate and return the payment data required to complete the payment on the client side, which by default will include a client_secret to complete the payment with Stripe.js. The next step is to call the confirmOrder once payment is confirmed on the client side by Stripe.

useCurrency

The useCurrency hook is used to format prices based on the selected currency. It provides methods to format prices and to get the current currency. It has the following properties:

Property	Type	Description
`currenciesConfig`	`CurrenciesConfig`	The configuration for supported currencies. Directly matching the config provided to the Context Provider. More
`currency`	`Currency`	The currently selected currency.
`formatPrice`	`(amount: number) => string`	Method to format a price based on the selected currency.
`setCurrency`	`(currencyCode: string) => void`	Method to set the current currency by code. It will update all price formats when used in conjunction with the `formatPrice` utility.

formatPrice in particular is very helpful as all prices are stored as integers to avoid any potential issues with decimal calculations, therefore on the frontend you can use this utility to format your price accounting for the currency and decimals. Example usage:

1import { useCurrency } from '@payloadcms/plugin-ecommerce/client/react'
2
3const PriceComponent = ({ amount }) => {
4  const { currenciesConfig, currency, setCurrency } = useCurrency()
5
6  return <div>{formatPrice(amount)}</div>
7}

useEcommerceConfig

The useEcommerceConfig hook provides access to the ecommerce configuration. This is useful when you need to build custom API calls or queries using the correct collection slugs and API settings.

Property	Type	Description
`addressesSlug`	`string`	The slug for the addresses collection.
`cartsSlug`	`string`	The slug for the carts collection.
`customersSlug`	`string`	The slug for the customers collection.
`api.apiRoute`	`string`	The base API route (e.g., `/api`).

Example usage:

1import { useEcommerceConfig } from '@payloadcms/plugin-ecommerce/client/react'
2
3const CustomComponent = () => {
4  const { cartsSlug, customersSlug, api } = useEcommerceConfig()
5
6  // Build custom API URLs
7  const cartsEndpoint = `${api.apiRoute}/${cartsSlug}`
8
9  // Your component logic here
10}

useEcommerce

The useEcommerce hook encompasses all of the above hooks in one. It provides access to the cart, addresses, and payments hooks, along with a unified isLoading state that tracks any async operations across all these features. It also includes the config property for accessing collection slugs and API settings.

Example usage:

1import { useEcommerce } from '@payloadcms/plugin-ecommerce/client/react'
2
3const EcommerceComponent = () => {
4  const {
5    cart,
6    addresses,
7    clearSession,
8    config,
9    isLoading,
10    selectedPaymentMethod,
11  } = useEcommerce()
12
13  // Your component logic here
14  // isLoading tracks loading states for cart, addresses, and payment operations
15  // config provides access to collection slugs and API settings
16}

Hooks

The ecommerce provider exposes several hooks for handling authentication events, session management, and cart operations. These hooks are accessible via useEcommerce().

onLogin

Called after a successful login to properly set up cart state. This hook handles:

Fetching the authenticated user's data
Merging any guest cart items into the user's existing cart
Transferring a guest cart to the user if they don't have one
Clearing guest cart secrets (authenticated users don't need them)

1import { useEcommerce } from '@payloadcms/plugin-ecommerce/client/react'
2
3const LoginForm = () => {
4  const { onLogin } = useEcommerce()
5
6  const handleLogin = async (credentials) => {
7    // Perform your login logic
8    const response = await fetch('/api/users/login', {
9      method: 'POST',
10      body: JSON.stringify(credentials),
11    })
12
13    if (response.ok) {
14      // Set up ecommerce state after successful login
15      await onLogin()
16    }
17  }
18
19  return <form onSubmit={handleLogin}>{/* form fields */}</form>
20}

onLogout

Called during logout to clear all ecommerce session data. Currently this is just an alias for clearSession() but named for semantic clarity when used in logout flows and it could change in the future.

1import { useEcommerce } from '@payloadcms/plugin-ecommerce/client/react'
2
3const LogoutButton = () => {
4  const { onLogout } = useEcommerce()
5
6  const handleLogout = async () => {
7    // Perform your logout logic
8    await fetch('/api/users/logout', { method: 'POST' })
9
10    // Clear ecommerce session data
11    onLogout()
12  }
13
14  return <button onClick={handleLogout}>Logout</button>
15}

clearSession

Clears all ecommerce session data from state and localStorage. This includes:

Cart data and cart ID
Cart secret (for guest carts)
User addresses
User state

Use this when you need to reset the ecommerce state, such as during logout or when switching users.

1import { useEcommerce } from '@payloadcms/plugin-ecommerce/client/react'
2
3const ResetButton = () => {
4  const { clearSession } = useEcommerce()
5
6  return <button onClick={clearSession}>Reset Session</button>
7}

mergeCart

Merges items from a source cart into a target cart. This is useful when you need to manually merge a guest cart into an authenticated user's cart, or when implementing custom cart merge logic.

Parameter	Type	Description
`targetCartID`	`string`	The ID of the cart to merge items into
`sourceCartID`	`string`	The ID of the cart to merge items from
`sourceSecret`	`string`	The secret for the source cart (required for guest carts)

When items are merged:

Matching items (same product and variant) have their quantities combined
Non-matching items are added to the target cart
The source cart is deleted after successful merge

1import { useEcommerce } from '@payloadcms/plugin-ecommerce/client/react'
2
3const MergeCartsButton = () => {
const { mergeCart, isLoading } = useEcommerce()
5
const handleMerge = async () => {
  try {
    const mergedCart = await mergeCart(
      'user-cart-id',
      'guest-cart-id',
      'guest-cart-secret',
    )
    console.log('Merged cart:', mergedCart)
  } catch (error) {
    console.error('Failed to merge carts:', error)
  }
}
18
return (
  <button onClick={handleMerge} disabled={isLoading}>
    Merge Carts
  </button>
)
24}

refreshCart

Fetches the latest cart data from the server and updates the local state. Use this when you need to ensure the cart is in sync with the server, such as after external cart modifications.

1import { useEcommerce } from '@payloadcms/plugin-ecommerce/client/react'
2
3const RefreshCartButton = () => {
4  const { refreshCart, isLoading } = useEcommerce()
5
6  return (
7    <button onClick={refreshCart} disabled={isLoading}>
8      Refresh Cart
9    </button>
10  )
11}

Session Management

The provider includes built-in session management for handling user authentication flows. This ensures cart data, addresses, and user state are properly managed when users log in or out.

When a user logs in, call onLogin() to set up the ecommerce state. This automatically:

Fetches the authenticated user's data
Merges any guest cart items into the user's existing cart (if both exist)
Transfers the guest cart to the user (if they don't have an existing cart)
Clears guest cart secrets (authenticated users don't need them)

1const handleLogin = async (credentials) => {
const response = await fetch('/api/users/login', {
  method: 'POST',
  body: JSON.stringify(credentials),
})
6
if (response.ok) {
  await onLogin() // Set up ecommerce state
}
10}

Handling Logout

When a user logs out, call onLogout() or clearSession() to clear all ecommerce data:

1const handleLogout = async () => {
2  await fetch('/api/users/logout', { method: 'POST' })
3  onLogout() // or clearSession()
4}

Both methods clear cart data, cart ID, cart secret, addresses, and user state from memory and localStorage.

Payment Adapters

Ecommerce Frontend

The package provides a set of React utilities to help you manage your ecommerce frontend. These include context providers, hooks, and components to handle carts, products, and payments.

The following hooks and components are available:

Hook / Component	Description
`EcommerceProvider`	A context provider to wrap your application and provide the ecommerce context.
`useCart`	A hook to manage the cart state and actions.
`useAddresses`	A hook to fetch and manage addresses.
`usePayments`	A hook to manage the checkout process.
`useCurrency`	A hook to format prices based on the selected currency.
`useEcommerceConfig`	A hook to access the ecommerce configuration (collection slugs, API settings).
`useEcommerce`	A hook that encompasses all of the above in one.

EcommerceProvider

The EcommerceProvider component is used to wrap your application and provide the ecommerce context. It takes the following props:

Prop	Type	Description
`addressesSlug`	`string`	The slug of the addresses collection. Defaults to `addresses`.
`api`	`object`	API configuration for the internal fetches of the provider. More
`cartsSlug`	`string`	The slug of the carts collection. Defaults to `carts`.
`children`	`ReactNode`	The child components that will have access to the ecommerce context.
`currenciesConfig`	`CurrenciesConfig`	Configuration for supported currencies. See Currencies.
`customersSlug`	`string`	The slug of the customers collection. Defaults to `users`.
`debug`	`boolean`	Enable or disable debug mode. This will send more information to the console.
`enableVariants`	`boolean`	Enable or disable product variants support. Defaults to `true`.
`paymentMethods`	`PaymentMethod[]`	An array of payment method adapters for the client side. See Payment adapters.
`syncLocalStorage`	`boolean` `object`	Whether to sync the cart ID to local storage. Defaults to `true`. Takes an object for configuration

Example usage:

1import { EcommerceProvider } from '@payloadcms/plugin-ecommerce/client/react'
2// Import any payment adapters you want to use on the client side
3import { stripeAdapterClient } from '@payloadcms/plugin-ecommerce/payments/stripe'
4import { USD, EUR } from '@payloadcms/plugin-ecommerce'
5
6export const Providers = () => (
7  <EcommerceProvider
8    enableVariants={true}
9    currenciesConfig={{
10      supportedCurrencies: [USD, EUR],
11      defaultCurrency: 'USD',
12    }}
13  >
14    {children}
15  </EcommerceProvider>
16)

api

The api prop is used to configure the API settings for the internal fetches of the provider. It takes an object with the following properties:

Property	Type	Description
`apiRoute`	`string`	The base route for accessing the Payload API. Defaults to `/api`.
`serverURL`	`string`	The full URL of your Payload server.
`cartsFetchQuery`	`object`	Additional query parameters to include when fetching the cart.

cartsFetchQuery

Property	Type	Description
`depth`	`string`	Defaults to 0. See Depth
`select`	`SelectType`	Select parameters. See Select
`populate`	`PopulateType`	Populate parameters. See Populate

Example usage:

1<EcommerceProvider
2  api={{
3    cartsFetchQuery: {
4      depth: 2, // Include related data up to 2 levels deep
5    },
6  }}
7>
8  {children}
9</EcommerceProvider>

syncLocalStorage

The syncLocalStorage prop is used to enable or disable syncing the cart ID to local storage. This allows the cart to persist across page reloads and sessions. It defaults to true.

You can also provide an object with the following properties for more configuration:

Property	Type	Description
`key`	`string`	The key to use for storing the cart ID in local storage. Defaults to `cart`.

useCart

Property	Type	Description
`addItem`	`(item: CartItemInput, quantity?: number) => void`	Method to add an item to the cart, optionally accepts a quantity to add multiple at once.
`cart`	`Cart` `null`	The current cart state. Null or undefined if it doesn't exist.
`clearCart`	`() => void`	Method to clear the cart.
`decrementItem`	`(item: IDType) => void`	Method to decrement the quantity of an item. Will remove it entirely if it reaches 0.
`incrementItem`	`(item: IDType) => void`	Method to increment the quantity of an item.
`isLoading`	`boolean`	Boolean indicating if any async operation is in progress (e.g., adding/removing items).
`removeItem`	`(item: IDType) => void`	Method to remove an item from the cart.

Example usage:

1import { useCart } from '@payloadcms/plugin-ecommerce/client/react'
2
3const CartComponent = () => {
4  const {
5    addItem,
6    cart,
7    clearCart,
8    decrementItem,
9    incrementItem,
10    isLoading,
11    removeItem,
12  } = useCart()
13
14  // Your component logic here
15  // Use isLoading to show loading states in your UI
16}

useAddresses

The useAddresses hook is used to fetch and manage addresses. It provides methods to create, update, and delete addresses, as well as to fetch the list of addresses. It has the following properties:

Property	Type	Description
`addresses`	`Address[]`	The list of addresses, if any are available for the current user.
`createAddress`	`(data: Address) => Promise<Address>`	Method to create a new address.
`isLoading`	`boolean`	Boolean indicating if any async operation is in progress (e.g., creating/updating address).
`updateAddress`	`(addressID: IDType, data: Partial<Address>) => Promise<Address>`	Method to update an existing address by ID.

Example usage:

1import { useAddresses } from '@payloadcms/plugin-ecommerce/client/react'
2
3const AddressesComponent = () => {
4  const { addresses, createAddress, isLoading, updateAddress } = useAddresses()
5
6  // Your component logic here
7  // Use isLoading to show loading states while creating or updating addresses
8}

usePayments

The usePayments hook is used to manage the checkout process. It provides methods to initiate payments, confirm orders, and handle payment status. It has the following properties:

Property	Type	Description
`confirmOrder`	`(args) => Promise<Order>`	Method to confirm an order by ID. More
`initiatePayment`	`(args) => Promise<void>`	Method to initiate a payment for an order. More
`isLoading`	`boolean`	Boolean indicating if any async operation is in progress (e.g., initiating/confirming order).
`paymentMethods`	`PaymentMethod[]`	The list of available payment methods.
`selectedPaymentMethod`	`PaymentMethod`	The currently selected payment method, if any.

Example usage:

1import { usePayments } from '@payloadcms/plugin-ecommerce/client/react'
2
3const CheckoutComponent = () => {
4  const {
5    confirmOrder,
6    initiatePayment,
7    isLoading,
8    paymentMethods,
9    selectedPaymentMethod,
10  } = usePayments()
11
12  // Your component logic here
13  // Use isLoading to show loading states during payment initiation or order confirmation
14}

confirmOrder

Use this method to confirm an order by its ID. It requires the payment method ID and will return the order ID.

1try {
const data = await confirmOrder('stripe', {
  additionalData: {
    paymentIntentID: paymentIntent.id,
    customerEmail,
  },
})
// Return type will contain `orderID`
// use data to redirect to your order page
10} catch (error) {
// handle error
12}

initiatePayment

1try {
const data = await initiatePayment('stripe', {
  additionalData: {
    customerEmail,
    billingAddress,
    shippingAddress,
  },
})
9} catch (error) {
// handle error
11}

useCurrency

The useCurrency hook is used to format prices based on the selected currency. It provides methods to format prices and to get the current currency. It has the following properties:

Property	Type	Description
`currenciesConfig`	`CurrenciesConfig`	The configuration for supported currencies. Directly matching the config provided to the Context Provider. More
`currency`	`Currency`	The currently selected currency.
`formatPrice`	`(amount: number) => string`	Method to format a price based on the selected currency.
`setCurrency`	`(currencyCode: string) => void`	Method to set the current currency by code. It will update all price formats when used in conjunction with the `formatPrice` utility.

1import { useCurrency } from '@payloadcms/plugin-ecommerce/client/react'
2
3const PriceComponent = ({ amount }) => {
4  const { currenciesConfig, currency, setCurrency } = useCurrency()
5
6  return <div>{formatPrice(amount)}</div>
7}

useEcommerceConfig

The useEcommerceConfig hook provides access to the ecommerce configuration. This is useful when you need to build custom API calls or queries using the correct collection slugs and API settings.

Property	Type	Description
`addressesSlug`	`string`	The slug for the addresses collection.
`cartsSlug`	`string`	The slug for the carts collection.
`customersSlug`	`string`	The slug for the customers collection.
`api.apiRoute`	`string`	The base API route (e.g., `/api`).

Example usage:

1import { useEcommerceConfig } from '@payloadcms/plugin-ecommerce/client/react'
2
3const CustomComponent = () => {
4  const { cartsSlug, customersSlug, api } = useEcommerceConfig()
5
6  // Build custom API URLs
7  const cartsEndpoint = `${api.apiRoute}/${cartsSlug}`
8
9  // Your component logic here
10}

useEcommerce

Example usage:

1import { useEcommerce } from '@payloadcms/plugin-ecommerce/client/react'
2
3const EcommerceComponent = () => {
4  const {
5    cart,
6    addresses,
7    clearSession,
8    config,
9    isLoading,
10    selectedPaymentMethod,
11  } = useEcommerce()
12
13  // Your component logic here
14  // isLoading tracks loading states for cart, addresses, and payment operations
15  // config provides access to collection slugs and API settings
16}

Hooks

The ecommerce provider exposes several hooks for handling authentication events, session management, and cart operations. These hooks are accessible via useEcommerce().

onLogin

Called after a successful login to properly set up cart state. This hook handles:

Fetching the authenticated user's data
Merging any guest cart items into the user's existing cart
Transferring a guest cart to the user if they don't have one
Clearing guest cart secrets (authenticated users don't need them)

1import { useEcommerce } from '@payloadcms/plugin-ecommerce/client/react'
2
3const LoginForm = () => {
4  const { onLogin } = useEcommerce()
5
6  const handleLogin = async (credentials) => {
7    // Perform your login logic
8    const response = await fetch('/api/users/login', {
9      method: 'POST',
10      body: JSON.stringify(credentials),
11    })
12
13    if (response.ok) {
14      // Set up ecommerce state after successful login
15      await onLogin()
16    }
17  }
18
19  return <form onSubmit={handleLogin}>{/* form fields */}</form>
20}

onLogout

1import { useEcommerce } from '@payloadcms/plugin-ecommerce/client/react'
2
3const LogoutButton = () => {
4  const { onLogout } = useEcommerce()
5
6  const handleLogout = async () => {
7    // Perform your logout logic
8    await fetch('/api/users/logout', { method: 'POST' })
9
10    // Clear ecommerce session data
11    onLogout()
12  }
13
14  return <button onClick={handleLogout}>Logout</button>
15}

clearSession

Clears all ecommerce session data from state and localStorage. This includes:

Cart data and cart ID
Cart secret (for guest carts)
User addresses
User state

Use this when you need to reset the ecommerce state, such as during logout or when switching users.

1import { useEcommerce } from '@payloadcms/plugin-ecommerce/client/react'
2
3const ResetButton = () => {
4  const { clearSession } = useEcommerce()
5
6  return <button onClick={clearSession}>Reset Session</button>
7}

mergeCart

Merges items from a source cart into a target cart. This is useful when you need to manually merge a guest cart into an authenticated user's cart, or when implementing custom cart merge logic.

Parameter	Type	Description
`targetCartID`	`string`	The ID of the cart to merge items into
`sourceCartID`	`string`	The ID of the cart to merge items from
`sourceSecret`	`string`	The secret for the source cart (required for guest carts)

When items are merged:

Matching items (same product and variant) have their quantities combined
Non-matching items are added to the target cart
The source cart is deleted after successful merge

1import { useEcommerce } from '@payloadcms/plugin-ecommerce/client/react'
2
3const MergeCartsButton = () => {
const { mergeCart, isLoading } = useEcommerce()
5
const handleMerge = async () => {
  try {
    const mergedCart = await mergeCart(
      'user-cart-id',
      'guest-cart-id',
      'guest-cart-secret',
    )
    console.log('Merged cart:', mergedCart)
  } catch (error) {
    console.error('Failed to merge carts:', error)
  }
}
18
return (
  <button onClick={handleMerge} disabled={isLoading}>
    Merge Carts
  </button>
)
24}

refreshCart

Fetches the latest cart data from the server and updates the local state. Use this when you need to ensure the cart is in sync with the server, such as after external cart modifications.

1import { useEcommerce } from '@payloadcms/plugin-ecommerce/client/react'
2
3const RefreshCartButton = () => {
4  const { refreshCart, isLoading } = useEcommerce()
5
6  return (
7    <button onClick={refreshCart} disabled={isLoading}>
8      Refresh Cart
9    </button>
10  )
11}

Session Management

The provider includes built-in session management for handling user authentication flows. This ensures cart data, addresses, and user state are properly managed when users log in or out.

When a user logs in, call onLogin() to set up the ecommerce state. This automatically:

Fetches the authenticated user's data
Merges any guest cart items into the user's existing cart (if both exist)
Transfers the guest cart to the user (if they don't have an existing cart)
Clears guest cart secrets (authenticated users don't need them)

1const handleLogin = async (credentials) => {
const response = await fetch('/api/users/login', {
  method: 'POST',
  body: JSON.stringify(credentials),
})
6
if (response.ok) {
  await onLogin() // Set up ecommerce state
}
10}

Handling Logout

When a user logs out, call onLogout() or clearSession() to clear all ecommerce data:

1const handleLogout = async () => {
2  await fetch('/api/users/logout', { method: 'POST' })
3  onLogout() // or clearSession()
4}

Both methods clear cart data, cart ID, cart secret, addresses, and user state from memory and localStorage.

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 Frontend

EcommerceProvider

api

cartsFetchQuery

syncLocalStorage

useCart

useAddresses

usePayments

confirmOrder

initiatePayment

useCurrency

useEcommerceConfig

useEcommerce

Hooks

onLogin

onLogout

clearSession

mergeCart

refreshCart

Session Management

Handling Login

Handling Logout

Payment Adapters

Ecommerce Frontend

EcommerceProvider

api

cartsFetchQuery

syncLocalStorage

useCart

useAddresses

usePayments

confirmOrder

initiatePayment

useCurrency

useEcommerceConfig

useEcommerce

Hooks

onLogin

onLogout

clearSession

mergeCart

refreshCart

Session Management

Handling Login

Handling Logout