feat(plugin-ecommerce): add new method refreshCart in useCart (#14765) (#14767)

What?

This PR adds a new method refreshCart to the E-commerce plugin.

Why?

Currently, the standard addItem method enforces uniqueness validation
for products in the cart. This conflicts with certain use cases where
the same product should be added as a new line item.

By exposing refreshCart, developers can manually refresh the cart state
after directly modifying cart items, ensuring the UI stays in sync
without being blocked by addItem’s uniqueness validation.

This addresses the feature request described in
[#14765](#14765)
and the related discussion
[#14764](#14764)
.

How?

Added refreshCart method to the E-commerce context.

This allows programmatic updates to the cart state without triggering
the uniqueness validation of addItem.

The method can be called after direct modifications to the cart (e.g.,
via fetch requests or custom logic).

Fixes

Fixes #14765

Author: teastudiopl

packages/plugin-ecommerce/src/react/provider/index.tsx

@@ -50,6 +50,7 @@ const defaultContext: EcommerceContextType = {
   initiatePayment: async () => {},
   isLoading: false,
   paymentMethods: [],
+  refreshCart: async () => {},
   removeItem: async () => {},
   setCurrency: () => {},
   updateAddress: async () => {},
@@ -252,6 +253,14 @@ export const EcommerceProvider: React.FC<ContextProps> = ({
     [baseAPIURL, cartQuery, cartsSlug, cartSecret],
   )
 
+  const refreshCart = useCallback<EcommerceContextType['refreshCart']>(async () => {
+    if (!cartID) {
+      return
+    }
+    const updatedCart = await getCart(cartID)
+    setCart(updatedCart)
+  }, [cartID, getCart])
+
   const deleteCart = useCallback(
     async (cartID: DefaultDocumentIDType) => {
       // Build query params with secret if provided
@@ -898,6 +907,7 @@ export const EcommerceProvider: React.FC<ContextProps> = ({
         initiatePayment,
         isLoading,
         paymentMethods,
+        refreshCart,
         removeItem,
         selectedPaymentMethod,
         setCurrency,
@@ -960,8 +970,16 @@ export const useCurrency = () => {
 }
 
 export function useCart<T extends CartsCollection>() {
-  const { addItem, cart, clearCart, decrementItem, incrementItem, isLoading, removeItem } =
-    useEcommerce()
+  const {
+    addItem,
+    cart,
+    clearCart,
+    decrementItem,
+    incrementItem,
+    isLoading,
+    refreshCart,
+    removeItem,
+  } = useEcommerce()
 
   if (!addItem) {
     throw new Error('useCart must be used within an EcommerceProvider')
@@ -974,6 +992,7 @@ export function useCart<T extends CartsCollection>() {
     decrementItem,
     incrementItem,
     isLoading,
+    refreshCart,
     removeItem,
   }
 }

packages/plugin-ecommerce/src/types/index.ts

@@ -882,6 +882,10 @@ export type EcommerceContextType<T extends EcommerceCollections = EcommerceColle
    */
   isLoading: boolean
   paymentMethods: PaymentAdapterClient[]
+  /**
+   * Refresh the cart.
+   */
+  refreshCart: () => Promise<void>
   /**
    * Remove an item from the cart by its index ID.
    */