@liquidcommerce/elements-sdk 2.7.35 → 2.7.37

package/dist/ssr-stub.esm.js

@@ -97,6 +97,7 @@ const ELEMENTS_ACTIONS_EVENT = {
     PRODUCT_FULFILLMENT_TYPE_CHANGED: 'product_fulfillment_type_changed',
     PRODUCT_FULFILLMENT_CHANGED: 'product_fulfillment_changed',
     CART_LOADED: 'cart_loaded',
+    CART_SHOP_RETAILER: 'cart_shop_retailer',
     CART_CLOSED: 'cart_closed',
     CART_OPENED: 'cart_opened',
     CART_UPDATED: 'cart_updated',

package/dist/types/clients/helpers.d.ts

@@ -1,5 +1,7 @@
 import { type ComponentType } from '@/enums';
+import type { ICartComponent } from '@/interfaces/configs';
 export declare function normalizeProductListLists<T extends Record<string, any>>(data: T): T;
+export declare function withCartLayoutDefaults(cart: ICartComponent): ICartComponent;
 export declare function deepMergeConfigs<T extends Record<string, any>>(target: T, source: Partial<T>, currentPath?: string): T;
 export declare const layoutFieldToComponentTypes: Map<string, ComponentType[]>;
 export declare function getComponentTypesForLayoutFields(parentPath: string, layoutFields: Record<string, any>): ComponentType[];

package/dist/types/core/client/actions/client-checkout-action.service.d.ts

@@ -1,5 +1,5 @@
 import type { ICheckoutDetailsEventData } from '@/core/pubsub/interfaces/checkout.interface';
-import type { IAnonymousCheckoutAddProductParams, IAnonymousCheckoutAddProductResponse } from '@/interfaces/api/checkout.interface';
+import type { IAnonymousCheckoutAddProductParams, IAnonymousCheckoutAddProductResponse, ICheckoutMarketingPreferences } from '@/interfaces/api/checkout.interface';
 import type { IProductAvailabilityResponse } from '@/interfaces/api/product.interface';
 import type { BillingFieldName, CustomerFieldName, GiftFieldName } from '@/modules/checkout/constant';
 import { BaseActionService } from './base-action.service';
@@ -20,6 +20,8 @@ export interface ICheckoutActions {
     exitCheckout: () => void;
     setSavedPaymentMethod: (params: ISavedPaymentMethodInput) => void;
     clearSavedPaymentMethod: () => void;
+    setSavedMarketingPreferences: (preferences: Partial<ICheckoutMarketingPreferences>) => Promise<void>;
+    clearSavedMarketingPreferences: () => void;
     addProduct: (params: IAddProductParams[], openCheckout?: boolean) => Promise<void>;
     applyPromoCode: (promoCode: string) => Promise<void>;
     removePromoCode: () => Promise<void>;
@@ -28,7 +30,9 @@ export interface ICheckoutActions {
     toggleIsGift: (active?: boolean) => Promise<void>;
     toggleBillingSameAsShipping: (active?: boolean) => Promise<void>;
     toggleMarketingPreferences: (field: 'canEmail' | 'canSms', active: boolean) => Promise<void>;
-    updateCustomerInfo: (params: Record<CustomerFieldName, string>) => void;
+    updateCustomerInfo: (params: Record<CustomerFieldName, string>, options?: {
+        saveIfValid?: boolean;
+    }) => Promise<void>;
     updateBillingInfo: (params: Record<BillingFieldName, string>) => void;
     updateGiftInfo: (params: Record<GiftFieldName, string>) => void;
     getDetails: () => ICheckoutDetailsEventData;
@@ -59,6 +63,8 @@ export declare class ClientCheckoutActionService extends BaseActionService {
     private removeGiftCard;
     private toggleIsGift;
     private toggleBillingSameAsShipping;
+    private setSavedMarketingPreferences;
+    private clearSavedMarketingPreferences;
     private toggleMarketingPreferences;
     private updateCustomerInfo;
     private updateBillingInfo;

package/dist/types/core/pubsub/interfaces/cart.interface.d.ts

@@ -67,3 +67,8 @@ export interface ICartProductAddFailedEventData {
     identifiers: string[];
     error: string;
 }
+export interface ICartShopRetailerEventData {
+    retailerId: string;
+    fulfillmentId: string;
+    fulfillmentType: 'onDemand' | 'shipping';
+}

package/dist/types/core/pubsub/interfaces/core.interface.d.ts

@@ -1,5 +1,5 @@
 import type { IAddressActionEventData, IAddressFailedEventData } from '@/core/pubsub/interfaces/address.interface';
-import type { ICartFailedEventData, ICartItemAddedEventData, ICartItemEngravingUpdatedEventData, ICartItemQuantityChangedEventData, ICartItemRemovedEventData, ICartLoadedEventData, ICartProductAddEventData, ICartProductAddFailedEventData, ICartPromoCodeEventData, ICartPromoCodeFailedEventData, ICartUpdatedEventData } from '@/core/pubsub/interfaces/cart.interface';
+import type { ICartFailedEventData, ICartItemAddedEventData, ICartItemEngravingUpdatedEventData, ICartItemQuantityChangedEventData, ICartItemRemovedEventData, ICartLoadedEventData, ICartProductAddEventData, ICartProductAddFailedEventData, ICartPromoCodeEventData, ICartPromoCodeFailedEventData, ICartShopRetailerEventData, ICartUpdatedEventData } from '@/core/pubsub/interfaces/cart.interface';
 import type { ICheckoutBillingInformationUpdatedEventData, ICheckoutCustomerInformationUpdatedEventData, ICheckoutFailedEventData, ICheckoutGiftCardEventData, ICheckoutGiftCardFailedEventData, ICheckoutGiftInformationUpdatedEventData, ICheckoutItemEngravingUpdatedEventData, ICheckoutItemQuantityChangedEventData, ICheckoutItemRemovedEventData, ICheckoutLoadedEventData, ICheckoutMarketingPreferencesToggleEventData, ICheckoutProductAddEventData, ICheckoutProductAddFailedEventData, ICheckoutPromoCodeEventData, ICheckoutPromoCodeFailedEventData, ICheckoutSubmitCompletedEventData, ICheckoutSubmitFailedEventData, ICheckoutSubmitStartedEventData, ICheckoutTipUpdatedEventData, ICheckoutToggleEventData } from '@/core/pubsub/interfaces/checkout.interface';
 import type { IProductAddToCartEventData, IProductFulfillmentChangedEventData, IProductFulfillmentTypeChangedEventData, IProductLoadedEventData, IProductQuantityChangedEventData, IProductSizeChangedEventData } from '@/core/pubsub/interfaces/product.interface';
 import { ELEMENTS_ACTIONS_EVENT } from '@/enums';
@@ -37,6 +37,7 @@ export interface IElementsActionsEventsMap {
     [ELEMENTS_ACTIONS_EVENT.PRODUCT_SIZE_CHANGED]: IProductSizeChangedEventData;
     [ELEMENTS_ACTIONS_EVENT.PRODUCT_FULFILLMENT_TYPE_CHANGED]: IProductFulfillmentTypeChangedEventData;
     [ELEMENTS_ACTIONS_EVENT.PRODUCT_FULFILLMENT_CHANGED]: IProductFulfillmentChangedEventData;
+    [ELEMENTS_ACTIONS_EVENT.CART_SHOP_RETAILER]: ICartShopRetailerEventData;
     [ELEMENTS_ACTIONS_EVENT.CART_CLOSED]: boolean;
     [ELEMENTS_ACTIONS_EVENT.CART_OPENED]: boolean;
     [ELEMENTS_ACTIONS_EVENT.CART_UPDATED]: ICartUpdatedEventData;

package/dist/types/core/store/interfaces/checkout.interface.d.ts

@@ -36,6 +36,7 @@ export interface ICheckoutStore {
     presale: ICheckoutPresale | null;
     isGift: boolean;
     marketingPreferences: ICheckoutMarketingPreferences;
+    appliedSavedMarketingPreferences: Partial<ICheckoutMarketingPreferences>;
     customerForm: ICheckoutCustomerFormStore;
     giftRecipientForm: ICheckoutGiftRecipientFormStore;
     paymentForm: ICheckoutPaymentFormStore;

package/dist/types/enums/core.enum.d.ts

@@ -16,6 +16,7 @@ export declare const ELEMENTS_ACTIONS_EVENT: {
     readonly PRODUCT_FULFILLMENT_TYPE_CHANGED: "product_fulfillment_type_changed";
     readonly PRODUCT_FULFILLMENT_CHANGED: "product_fulfillment_changed";
     readonly CART_LOADED: "cart_loaded";
+    readonly CART_SHOP_RETAILER: "cart_shop_retailer";
     readonly CART_CLOSED: "cart_closed";
     readonly CART_OPENED: "cart_opened";
     readonly CART_UPDATED: "cart_updated";

package/dist/types/interfaces/configs/cart.interface.d.ts

@@ -3,6 +3,7 @@ export interface ICartTheme {
     backgroundColor: string;
 }
 export interface ICartLayout {
+    showShopRetailerButton?: boolean;
     showQuantityCounter: boolean;
     quantityCounterStyle: 'outlined' | 'ghost';
     drawerHeaderText: string;

package/dist/types/modules/cart/cart.commands.d.ts

@@ -1,5 +1,5 @@
 import { BaseCommand } from '@/core/command/base-command.service';
-import type { IBaseCartEventData } from '@/core/pubsub/interfaces/cart.interface';
+import type { IBaseCartEventData, ICartShopRetailerEventData } from '@/core/pubsub/interfaces/cart.interface';
 export interface AddItemParams {
     fulfillmentId: string;
     partNumber: string;
@@ -10,6 +10,10 @@ export interface AddItemParams {
 export declare class CartCommands extends BaseCommand {
     constructor();
     static getInstance(): CartCommands;
+    getShopRetailerTarget(fulfillmentId: string): (ICartShopRetailerEventData & {
+        retailerName: string;
+    }) | null;
+    shopRetailer(fulfillmentId: string): void;
     updateItemQuantity(itemId: string, delta: number): Promise<void>;
     removeItem(itemId: string, isNotStandAlone?: boolean): Promise<void>;
     updateItemEngraving(productItemId: string, engravingLines: string[]): Promise<void>;

package/dist/types/modules/cart/components/cart-fulfillment.component.d.ts

@@ -9,6 +9,7 @@ export declare class CartFulfillmentComponent extends BaseComponent<ICartFulfill
     private handleItemsUpdate;
     private setupItemElements;
     private setupMinimumPurchaseAlert;
+    private removeMinimumControl;
     private createLoadingOverlay;
     private hasLoadingOverlay;
     private showLoadingOverlay;
@@ -16,7 +17,6 @@ export declare class CartFulfillmentComponent extends BaseComponent<ICartFulfill
     private isAnyItemUpdating;
     private checkAndUpdateLoadingState;
     onStoreChanged(changes: IOnStoreChanged[]): boolean | undefined;
-    private hasFulfillmentDataChanged;
     protected afterRender(): void;
     protected disconnected(): void;
     protected template(): HTMLElement[];

package/dist/types/modules/checkout/checkout.commands.d.ts

@@ -1,13 +1,23 @@
 import { BaseCommand } from '@/core/command/base-command.service';
 import type { ICheckoutDetailsEventData } from '@/core/pubsub/interfaces/checkout.interface';
 import type { ICheckoutPaymentMethodStore } from '@/core/store/interfaces/checkout.interface';
-import type { ICheckoutBilling, ICheckoutCustomer, ICheckoutGiftRecipient, ICheckoutPrepare } from '@/interfaces/api/checkout.interface';
+import type { ICheckoutBilling, ICheckoutCustomer, ICheckoutGiftRecipient, ICheckoutMarketingPreferences, ICheckoutPrepare } from '@/interfaces/api/checkout.interface';
 import type { AddItemParams } from '@/modules/cart/cart.commands';
 import type { PresaleExpiredReason } from '@/modules/checkout/components';
 export declare class CheckoutCommands extends BaseCommand {
     private readonly uiCommands;
     private lastLoadParams;
     private paymentGeneration;
+    private savedMarketingPreferences;
+    private savedMarketingRevision;
+    private marketingNeedsPrepare;
+    private completingCheckout;
+    private savedMarketingError;
+    private marketingEdits;
+    private marketingQueue;
+    private readonly marketingFields;
+    private customerEditRevision;
+    private customerEditedGeneration;
     private confirmedPayment;
     assertPaymentReady(): void;
     retryLoadCheckout(): Promise<void>;
@@ -23,6 +33,17 @@ export declare class CheckoutCommands extends BaseCommand {
     loadCheckoutFromResponse(response: ICheckoutPrepare): void;
     toggleIsGift(active?: boolean): Promise<void>;
     toggleBillingSameAsShipping(active?: boolean): Promise<void>;
+    private loadedMarketingState;
+    private defaultMarketingPreferences;
+    private marketingForPrepare;
+    private confirmedSavedMarketing;
+    private queueMarketing;
+    setSavedMarketingPreferences(preferences: Partial<ICheckoutMarketingPreferences>): Promise<void>;
+    clearSavedMarketingPreferences(): void;
+    private recordSavedMarketing;
+    private assertMarketingRestored;
+    private canApplySavedMarketing;
+    private applySavedMarketingPreferences;
     toggleMarketingPreferences(fieldName: 'canEmail' | 'canSms', active?: boolean): Promise<boolean>;
     getPaymentSession(): Promise<void>;
     confirmPaymentSession(confirmationTokenId: string, setupIntentId: string): Promise<ICheckoutPaymentMethodStore>;
@@ -44,6 +65,9 @@ export declare class CheckoutCommands extends BaseCommand {
     updateFulfillmentTip(fulfillmentId: string, tipAmount: number): Promise<void>;
     removeFulfillmentTip(fulfillmentId: string): Promise<void>;
     clearCheckoutError(): Promise<void>;
+    markCustomerFormEdited(): void;
+    canPrefillCustomerForm(): boolean;
+    savePrefilledCustomerInfo(): Promise<void>;
     editCustomerForm(): Promise<void>;
     saveCustomerForm({ shippingAddressTwo, deliveryInstructions, customerData, }: {
         customerData: ICheckoutCustomer;
@@ -65,6 +89,7 @@ export declare class CheckoutCommands extends BaseCommand {
             setupIntentId: string;
         };
     }): Promise<void>;
+    private prepareMarketingForCompletion;
     checkoutComplete(): Promise<void>;
     private updateStoreFromCheckoutResponse;
     private syncFromItemUpdate;

package/dist/types/modules/checkout/components/checkout-order-summary.component.d.ts

@@ -10,6 +10,7 @@ export declare class CheckoutOrderSummaryComponent extends BaseComponent<null, I
     private toggleMarketingPreference;
     private handleEmailToggle;
     private handleSmsToggle;
+    private updateSavedMarketingPrompts;
     private marketingOptInsContainer;
     private hasOnDemandOrder;
     protected template(): HTMLElement[];

package/dist/types/modules/checkout/components/checkout-payment.component.d.ts

@@ -7,6 +7,7 @@ export declare class CheckoutPaymentComponent extends BaseComponent<ICheckoutSen
     private stripeHandlerElement;
     private saveButton;
     private errorMessageElement;
+    private walletInstructionsElement?;
     private billingFormData;
     private isValidBillingForm;
     private isBillingSameAsShipping;
@@ -21,6 +22,9 @@ export declare class CheckoutPaymentComponent extends BaseComponent<ICheckoutSen
     private handleBillingSameAsShippingChange;
     afterRender(): Promise<void>;
     private updateSaveButtonState;
+    private getSelectedWallet;
+    private getPaymentButtonText;
+    private updateWalletInstructions;
     private lastAnnouncedPaymentError;
     private updateErrorMessage;
     private showError;

package/dist/types/modules/checkout/components/checkout-stripe-form.component.d.ts

@@ -18,6 +18,8 @@ export interface IStripeConfig {
     elementOptions?: Record<string, any>;
 }
 export interface IStripeFormStatus {
+    selectedPaymentType?: string;
+    hasPendingConfirmation?: boolean;
     isFormComplete: boolean;
     isProcessing: boolean;
     hasCompletedPayment: boolean;
@@ -31,6 +33,7 @@ export declare class CheckoutStripeFormComponent extends SafeHTMLElement {
     private _stripeElements;
     private _paymentElement;
     private _isProcessing;
+    private _selectedPaymentType;
     private _isFormComplete;
     private _hasUsedCurrentSession;
     private _pendingConfirmation;

package/dist/types/modules/checkout/customer-prefill.d.ts

@@ -0,0 +1,2 @@
+import type { ICheckoutCustomer } from '@/interfaces/api/checkout.interface';
+export declare function isValidCustomerPrefill(customer: ICheckoutCustomer, today?: Date): boolean;

package/dist/types/modules/product/components/product-retailers-popup.component.d.ts

@@ -7,5 +7,6 @@ export declare class ProductRetailersPopupComponent extends BaseComponent<IProdu
     get hostClasses(): string[];
     constructor();
     private getProductId;
+    private get fulfillmentLabelId();
     protected template(): HTMLElement[];
 }

package/dist/types/modules/product/product.commands.d.ts

@@ -22,7 +22,7 @@ export declare class ProductCommands extends BaseCommand {
     openProductDrawer(productId: string, contentType: IProductDrawerContentConfig['type'], data?: Record<string, any>, trigger?: HTMLElement | null): Promise<void>;
     closeProductDrawer(productId: string): Promise<void>;
     rerenderAllProducts(): Promise<void>;
-    addToCart(productId: string, params: AddItemParams, trigger?: HTMLElement | null): Promise<void>;
+    addToCart(productId: string, params: AddItemParams, trigger?: HTMLElement | null, triggerFallback?: () => HTMLElement | null): Promise<void>;
     addPresaleToCart(productId: string, params: AddItemParams): Promise<void>;
     productDataForEventFromStore(identifier: string): IBaseProductEventData;
 }

package/dist/types/modules/product-list/product-list.commands.d.ts

@@ -22,7 +22,7 @@ export declare class ProductListCommands extends BaseCommand {
     getItemsPerPage(slug: string): number;
     updatePagination(navigation: INavigationResponse | undefined): IPagination;
     createInitialPagination(): IPagination;
-    addToCart(slug: string, productId: string, params: AddItemParams, trigger?: HTMLElement | null): Promise<void>;
+    addToCart(slug: string, productId: string, params: AddItemParams, trigger?: HTMLElement | null, triggerFallback?: () => HTMLElement | null): Promise<void>;
     selectSize(slug: string, productId: string, sizeId: string): Promise<void>;
     changeFulfillmentType: (slug: string, productId: string, newFulfillmentType: FulfillmentType) => Promise<void>;
     selectFulfillment: (slug: string, productId: string, selectedFulfillmentId: string) => Promise<void>;

package/docs/v1/api/actions/checkout-actions.md

@@ -264,7 +264,7 @@ await window.LiquidCommerce.elements.actions.checkout.toggleMarketingPreferences
 ### actions.checkout.updateCustomerInfo()
 
 ```typescript
-updateCustomerInfo(params: Record<CustomerFieldName, string>): void
+updateCustomerInfo(params: Record<CustomerFieldName, string>, options?: { saveIfValid?: boolean }): Promise<void>
 ```
 
 Pre-fill customer information.
@@ -525,3 +525,60 @@ Key events:
 - [Checkout Component Guide](../../guides/checkout-component.md)
 - [Checkout Events](../../guides/events.md#checkout-events)
 - [Cart Actions](./cart-actions.md)
+
+### Preparing complete account delivery details
+
+After `lce:actions.checkout_loaded`, call
+`await elements.actions.checkout.updateCustomerInfo(fields, { saveIfValid: true })`
+to validate and prepare complete account details, then show their editable summary.
+Supply names, email, a US phone number, and a real `birthDate` in `MM/DD/YYYY` format
+(age 21+, year 1930 or later). A shipping street must already be selected.
+Omitted apartment and delivery instructions retain their existing checkout values.
+Partial or invalid details stay in the form; backend validation failures reject the
+promise, show the checkout error, and keep details editable. The host should handle that rejection.
+
+The option skips gifts, saved forms, in-flight saves, and customer forms the shopper
+has edited during the current checkout. It does not overwrite those forms. Edits or
+address/checkout changes during preparation prevent a stale response from closing
+the form. Without the option, this action only prefills fields, as before.
+
+Apple Pay and Google Pay selection displays **Continue with Apple Pay** or
+**Continue with Google Pay**. This opens the wallet to save a payment method; the
+shopper still reviews and places the order afterward. It is not express checkout.
+
+After wallet cancellation, the same Continue action remains available. If authorization
+succeeded but saving the method failed, **Retry saving Apple Pay/Google Pay** reuses
+the existing authorization rather than opening the wallet again.
+
+### Saved account marketing preferences
+
+```ts
+setSavedMarketingPreferences(preferences: { canEmail?: boolean; canSms?: boolean }): Promise<void>
+clearSavedMarketingPreferences(): void
+```
+
+Call `actions.checkout.setSavedMarketingPreferences()` with known recorded account
+choices, including `false`, before checkout loads. Only boolean values are used;
+missing/null/unrecognized values remain unknown. The first checkout prepare uses
+saved values instead of tenant defaults. Each channel's prompt is hidden only
+after the server confirms that saved choice. Unknown channels retain their normal
+checkout prompts. The actions are available in both full and checkout-only clients.
+
+Calling the setter during an active checkout prepares untouched channels and
+preserves shopper checkbox edits. Backend failure rejects the promise, displays
+an error, and leaves prompts available; the host should catch the rejection.
+The same call can retry. Applying values does not call a subscription service.
+It supplies the account's recorded choices to this checkout.
+
+Saved choices persist across cart resets in the same SDK session. Call
+`clearSavedMarketingPreferences()` on sign-out, account change, and host cleanup.
+Clearing reveals the prompts and restores configured guest defaults. It invalidates
+stale responses while draining outstanding preference requests; checkout completion
+prepares the current choices before submitting the checkout token. A load already
+in progress still finishes and reconciles the current account's values. Bind a new
+account only to its own checkout; the host remains responsible for account/cart
+ownership and for reloading checkout when identity changes.
+
+Order completion waits for queued preference work. It cannot race a late saved
+opt-out or proceed with an unconfirmed saved choice. If applying a known choice
+fails, the shopper can retry or explicitly choose the visible channel preference.

package/docs/v1/api/configuration.md

@@ -271,6 +271,7 @@ interface ICartTheme {
 
 ```typescript
 interface ICartLayout {
+  showShopRetailerButton?: boolean;
   showQuantityCounter: boolean;
   quantityCounterStyle: 'outlined' | 'ghost';
   drawerHeaderText: string;
@@ -280,6 +281,7 @@ interface ICartLayout {
 
 | Property | Type | Description |
 |----------|------|-------------|
+| `showShopRetailerButton` | `boolean` | Default `false`, including older server themes. Shows the retailer shopping button for eligible unmet minimums; requires a `cart_shop_retailer` event handler. |
 | `showQuantityCounter` | `boolean` | Show quantity counter in cart items |
 | `quantityCounterStyle` | `'outlined' \| 'ghost'` | Visual style for quantity counter |
 | `drawerHeaderText` | `string` | Header text for the cart drawer |

package/docs/v1/api/typescript-types.md

@@ -422,3 +422,60 @@ type DeepPartial<T> = {
 - [Client API](./client.md) - Client initialization and usage
 - [Configuration Reference](./configuration.md) - Detailed config options
 - [Injection Methods](./injection-methods.md) - Component injection API
+
+### Preparing complete account delivery details
+
+After `lce:actions.checkout_loaded`, call
+`await elements.actions.checkout.updateCustomerInfo(fields, { saveIfValid: true })`
+to validate and prepare complete account details, then show their editable summary.
+Supply names, email, a US phone number, and a real `birthDate` in `MM/DD/YYYY` format
+(age 21+, year 1930 or later). A shipping street must already be selected.
+Omitted apartment and delivery instructions retain their existing checkout values.
+Partial or invalid details stay in the form; backend validation failures reject the
+promise, show the checkout error, and keep details editable. The host should handle that rejection.
+
+The option skips gifts, saved forms, in-flight saves, and customer forms the shopper
+has edited during the current checkout. It does not overwrite those forms. Edits or
+address/checkout changes during preparation prevent a stale response from closing
+the form. Without the option, this action only prefills fields, as before.
+
+Apple Pay and Google Pay selection displays **Continue with Apple Pay** or
+**Continue with Google Pay**. This opens the wallet to save a payment method; the
+shopper still reviews and places the order afterward. It is not express checkout.
+
+After wallet cancellation, the same Continue action remains available. If authorization
+succeeded but saving the method failed, **Retry saving Apple Pay/Google Pay** reuses
+the existing authorization rather than opening the wallet again.
+
+### Saved account marketing preferences
+
+```ts
+setSavedMarketingPreferences(preferences: { canEmail?: boolean; canSms?: boolean }): Promise<void>
+clearSavedMarketingPreferences(): void
+```
+
+Call `actions.checkout.setSavedMarketingPreferences()` with known recorded account
+choices, including `false`, before checkout loads. Only boolean values are used;
+missing/null/unrecognized values remain unknown. The first checkout prepare uses
+saved values instead of tenant defaults. Each channel's prompt is hidden only
+after the server confirms that saved choice. Unknown channels retain their normal
+checkout prompts. The actions are available in both full and checkout-only clients.
+
+Calling the setter during an active checkout prepares untouched channels and
+preserves shopper checkbox edits. Backend failure rejects the promise, displays
+an error, and leaves prompts available; the host should catch the rejection.
+The same call can retry. Applying values does not call a subscription service.
+It supplies the account's recorded choices to this checkout.
+
+Saved choices persist across cart resets in the same SDK session. Call
+`clearSavedMarketingPreferences()` on sign-out, account change, and host cleanup.
+Clearing reveals the prompts and restores configured guest defaults. It invalidates
+stale responses while draining outstanding preference requests; checkout completion
+prepares the current choices before submitting the checkout token. A load already
+in progress still finishes and reconciles the current account's values. Bind a new
+account only to its own checkout; the host remains responsible for account/cart
+ownership and for reloading checkout when identity changes.
+
+Order completion waits for queued preference work. It cannot race a late saved
+opt-out or proceed with an unconfirmed saved choice. If applying a known choice
+fails, the shopper can retry or explicitly choose the visible channel preference.

package/docs/v1/examples/custom-theming.md

@@ -41,6 +41,7 @@ const client = await Elements('YOUR_API_KEY', {
     },
     cart: {
       layout: {
+        showShopRetailerButton: false, // Enable only with a cart_shop_retailer event handler
         drawerHeaderText: 'Your Cart',
         goToCheckoutButtonText: 'Checkout Now'
       }
@@ -57,6 +58,18 @@ const client = await Elements('YOUR_API_KEY', {
 
 > If you use custom fonts, make sure the font is available on the page.
 
+### Shop the same retailer
+
+Set `customTheme.cart.layout.showShopRetailerButton: true` to show a native **Shop {retailer}**
+button beside each unmet order-minimum warning (below it on mobile). The default is `false`,
+including when the server theme predates this option. It only appears for a current, nonempty
+`onDemand` or `shipping` fulfillment with a positive amount remaining and valid retailer ownership.
+
+Handle `ELEMENTS_ACTIONS_EVENT.CART_SHOP_RETAILER` (`lce:actions.cart_shop_retailer`) to close the
+cart and open your retailer-filtered catalog. The SDK emits identifiers only and performs no
+navigation. Revalidate them against `client.actions.cart.getDetails()` before navigating; see
+[Events](../guides/events.md) for the payload.
+
 ## Related Docs
 
 - [Theming Guide](../guides/theming.md)

package/docs/v1/guides/accessibility.md

@@ -44,7 +44,12 @@ retailer closes the panel — arrow keys move focus and `Enter` commits.
 
 ### Focus management
 
-- **Opening an overlay** moves focus into it and remembers the control that opened it.
+- **Opening an overlay** moves focus onto the first control inside it — the panel's close
+  button, the address field — and remembers the control that opened it. Focus lands on a
+  control rather than on the panel itself so the focus ring shows a sighted keyboard user
+  where they now are; the dialog's role and name are announced either way as focus crosses
+  into it. Views whose point is the text at the top of them (the order confirmation) focus
+  that heading instead.
 - **Closing** returns focus to that control, even when a re-render has replaced it.
 - **While an overlay is open** focus is trapped inside it and the rest of the page is `inert` and
   `aria-hidden`, so a screen reader cannot wander behind the dialog.
@@ -55,6 +60,18 @@ retailer closes the panel — arrow keys move focus and `Enter` commits.
 - **Nothing hidden is focusable.** Collapsed panels are removed from the tab order and the
   accessibility tree, and closed overlays have their content torn down.
 
+### Retailer shopping from the cart
+
+The opt-in `cart.layout.showShopRetailerButton` uses a native **Shop {retailer}** button with
+normal Tab, Enter and Space behavior, a 44px minimum target height and a visible focus ring.
+It appears beside the unmet-minimum warning on desktop and below it on mobile. Warning updates
+retain the button node and its focus; if it disappears because the minimum is met or eligibility
+changes, focus moves to the containing fulfillment before its item controls. The host handles
+focus after closing the drawer and navigating in response to `cart_shop_retailer`.
+
+The button text, border and focus ring use `global.theme.primaryColor`; check that color against
+the cart background as part of your theme contrast review.
+
 ### Focus indicator
 
 A 2px ring in `--focus-ring-color`, offset 2px from the control. Controls that span their
@@ -129,14 +146,14 @@ on render, and a live region recreated with its text already in place is not ann
 
 ### Headings
 
-The product element emits a level-1 title with its sections (`Size`, `About this product:`) at
-level 2, and an overlay supplies its own heading at the top of its content, because the page behind
-it is out of the accessibility tree while it is open.
+The product element emits a level-1 title, and every section caption below it sits at level 2 —
+`Size`, `Delivers to:`, `Shipping From:` and `About this product:` — so the whole element is
+reachable by heading navigation with no level skipped. An overlay supplies its own heading at the
+top of its content, because the page behind it is out of the accessibility tree while it is open.
 
-Captions that label a single value — the `Delivers to:` and `Shipping From:` lines — are **not**
-headings, so they do not turn up in a heading list as headings that head nothing. `Shipping From:`
-names the card it captions with `aria-labelledby`; `Delivers to:` is hidden from assistive
-technology because the control beside it already announces the address.
+A caption can do both jobs at once: `Shipping From:` is a heading *and* names the retailer card
+beneath it through `aria-labelledby`. Heading ids are scoped to the product, so each product
+element on a page labels its own sections.
 
 The checkout element has its own outline and is not covered by the above. Where any element's
 top-level heading sits in **your** page's outline is yours to place.
@@ -212,3 +229,20 @@ for (const region of document.querySelectorAll('[data-lce-live-region]')) {
 Checkout announces loading or initialization failure in a status region. If initialization fails, payment fields are withheld and a keyboard-operable **Retry checkout** button retries the same checkout. The button is disabled while loading.
 
 Save Payment Information remains disabled until checkout initializes. During payment save it stays busy until the server responds. Recoverable billing/prepare errors are announced while the mounted card fields and billing input remain available for correction and retry.
+
+### Wallet payment actions
+
+The payment action's accessible name matches its visible label, including the
+selected Apple Pay or Google Pay wallet and retry/processing states. Adjacent
+instructions explain whether the action opens the wallet or retries saving already
+authorized details. These actions save the payment method; order placement is a
+separate step.
+
+### Recorded marketing choices
+
+Checkout suppresses each email/SMS consent checkbox only after the corresponding
+recorded account choice is confirmed. Suppressed controls are hidden visually and
+from the accessibility tree; unknown choices retain their named, keyboard-operable
+checkboxes. Clearing account preferences reveals the controls and synchronizes
+`aria-checked` with the current guest defaults. A shopper's explicit checkbox edit
+keeps that channel visible when account data arrives later.

package/docs/v1/guides/cart-component.md

@@ -277,6 +277,36 @@ Or using data attributes:
 
 ## Events
 
+### `lce:actions.cart_shop_retailer`
+
+A shopper activated **Shop {retailer}** from an unmet cart fulfillment minimum. Opt in with
+`customTheme.cart.layout.showShopRetailerButton: true` (default `false`). The cart command
+revalidates the fulfillment, its current retailer and items, fulfillment type, and remaining
+minimum before emitting. Unsupported, empty, stale or already-satisfied fulfillments emit nothing.
+
+```typescript
+interface ICartShopRetailerEventData {
+  retailerId: string;
+  fulfillmentId: string;
+  fulfillmentType: 'onDemand' | 'shipping';
+}
+```
+
+Listen with the exported constant; the usual event envelope is `{ data, metadata }`:
+
+```javascript
+window.addEventListener(`lce:actions.${ELEMENTS_ACTIONS_EVENT.CART_SHOP_RETAILER}`, (event) => {
+  const { retailerId, fulfillmentId, fulfillmentType } = event.detail.data;
+  // Revalidate against client.actions.cart.getDetails(), then close the drawer
+  // and route to your catalog scoped to this retailer and fulfillment type.
+});
+```
+
+The SDK leaves the drawer open and does not navigate. The host handles routing and derives
+retailer names, totals and minimums from current cart details. The event is also sent to `lce:actions`.
+
+
+
 ### Cart Loaded
 
 Fired when cart data is loaded:
@@ -410,6 +440,7 @@ const client = await Elements('YOUR_API_KEY', {
         backgroundColor: '#ffffff'
       },
       layout: {
+        showShopRetailerButton: false, // Enable only with a cart_shop_retailer event handler
         showQuantityCounter: true,
         quantityCounterStyle: 'outlined',  // or 'ghost'
         drawerHeaderText: 'My Bag',
@@ -420,6 +451,18 @@ const client = await Elements('YOUR_API_KEY', {
 });
 ```
 
+### Shop the same retailer
+
+Set `customTheme.cart.layout.showShopRetailerButton: true` to show a native **Shop {retailer}**
+button beside each unmet order-minimum warning (below it on mobile). The default is `false`,
+including when the server theme predates this option. It only appears for a current, nonempty
+`onDemand` or `shipping` fulfillment with a positive amount remaining and valid retailer ownership.
+
+Handle `ELEMENTS_ACTIONS_EVENT.CART_SHOP_RETAILER` (`lce:actions.cart_shop_retailer`) to close the
+cart and open your retailer-filtered catalog. The SDK emits identifiers only and performs no
+navigation. Revalidate them against `client.actions.cart.getDetails()` before navigating; see
+[Events](./events.md) for the payload.
+
 ## State Persistence
 
 ### Local Storage