refreshShoppingCart__c

Use the refreshShoppingCart message channel when a Lightning component changes cart contents and other cart-aware components need to refresh immediately. This channel is especially useful for keeping Shopping Cart Widget aligned with the shopper's current cart count after add, update, remove, or import actions.

Overview

refreshShoppingCart is an exposed Lightning Message Service channel in the cart domain. It acts as a refresh signal for storefront components that show cart data.

This channel does not carry business data such as cart item details or totals. Instead, it tells subscribing components to reload their own data from the server.

In the source project, the channel is referenced as:

import refreshShoppingCart from '@salesforce/messageChannel/refreshShoppingCart__c';

In an installed managed package context, the fully qualified channel name is:

import refreshShoppingCart from '@salesforce/messageChannel/welisacommerce__refreshShoppingCart__c';

When to use this channel

Publish this channel after a component successfully changes the cart, for example when it:

• adds a product to the cart
• updates quantity or cart item fields
• removes a cart item
• imports cart items from a file
• applies custom cart logic that changes the number of items shown in the header

Subscribe to this channel when a component displays cart-related data that should stay current without a full page reload.

Event payload contract

This channel is used as a signal-only event.

How Shopping Cart Widget uses this channel

Shopping Cart Widget subscribes to refreshShoppingCart during initialization. When the channel fires, the widget calls the cart count Apex method again and updates the displayed number of items.

That means any custom LWC can refresh the number shown in Shopping Cart Widget simply by publishing this message after a successful cart change.

The refresh flow is:

1. A storefront component changes the cart.
2. That component publishes refreshShoppingCart.
3. Shopping Cart Widget receives the message.
4. Shopping Cart Widget calls getNumberOfShoppingCartItems().
5. The displayed badge or label count updates.

Existing publishers in the cart experience

This channel is already used by cart components in the storefront, including flows that:

• refresh the full shopping cart LWC after updates
• refresh cart data providers
• refresh the header count after CSV import
• refresh list or table views after cart actions

Use the same pattern in custom components so the storefront stays consistent.

Publish the channel from a custom LWC

Use this pattern when your custom component performs a cart mutation and should refresh Shopping Cart Widget.

Example: publish after a successful cart update

import { LightningElement, wire } from 'lwc';
import { MessageContext, publish } from 'lightning/messageService';
import refreshShoppingCart from '@salesforce/messageChannel/refreshShoppingCart__c';
import addToCart from '@salesforce/apex/CustomCartController.addToCart';

export default class CustomAddToCartButton extends LightningElement {
    @wire(MessageContext)
    messageContext;

    isLoading = false;

    async handleAddToCart() {
        this.isLoading = true;

        try {
            await addToCart({ webProductId: this.recordId, quantity: 1 });
            publish(this.messageContext, refreshShoppingCart, {});
        } finally {
            this.isLoading = false;
        }
    }
}

Why this refreshes Shopping Cart Widget

If Shopping Cart Widget is present on the same storefront page experience, it receives the published message and reloads the cart item count automatically. No direct reference to the widget is required.

This keeps custom components loosely coupled to the header widget and avoids duplicating cart count logic.

Subscribe to the channel from another custom LWC

Use this pattern when your custom component also needs to refresh itself after any cart action in the storefront.

import { LightningElement, wire } from 'lwc';
import { MessageContext, subscribe, unsubscribe } from 'lightning/messageService';
import refreshShoppingCart from '@salesforce/messageChannel/refreshShoppingCart__c';

export default class CartSummaryBadge extends LightningElement {
    subscription;

    @wire(MessageContext)
    messageContext;

    connectedCallback() {
        if (!this.subscription) {
            this.subscription = subscribe(this.messageContext, refreshShoppingCart, () => {
                this.refreshCartSummary();
            });
        }
    }

    disconnectedCallback() {
        if (this.subscription) {
            unsubscribe(this.subscription);
            this.subscription = null;
        }
    }

    refreshCartSummary() {
        // Reload Apex or wire-backed cart summary data here.
    }
}

Implementation guidance

• Publish the channel only after the cart change succeeds.
• Do not place cart totals, record Ids, or other business data in the payload unless you have a documented extension contract for your own custom subscribers.
• Keep subscribers responsible for fetching their own data. This channel is intended to trigger refresh behavior, not transport cart state.
• Use this channel to decouple custom storefront components from Shopping Cart Widget and other cart displays.
• If your component updates cart records and LDS-backed UI at the same time, combine channel publication with any needed record refresh logic in your own component.

Troubleshooting

Shopping Cart Widget count does not update

Verify that your custom component publishes refreshShoppingCart after the cart update succeeds.

The channel publishes but the count is still wrong

Verify that the underlying cart update completed successfully and that the shopper's active cart reflects the new item count.

A subscriber does not react to the event

Verify that the component wires MessageContext, subscribes during initialization, and has not been removed from the page.

The widget updates only after a page refresh

Verify that the custom component publishes the message in the same Experience Cloud page context where Shopping Cart Widget is loaded.