@liquidcommerce/elements-sdk 2.7.41 → 2.7.43

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

@@ -20,6 +20,7 @@ export declare class CheckoutStripeHandlerComponent extends BaseComponent<ICheck
     private isCreatingStripeForm;
     private stripeFormContainer;
     private stripeSummaryContainer;
+    private loadFailureNotice;
     private callbacks;
     private stripeFormStatus;
     private isInEditMode;
@@ -38,6 +39,9 @@ export declare class CheckoutStripeHandlerComponent extends BaseComponent<ICheck
     private hideStripeSummary;
     private showStripeForm;
     private hideStripeForm;
+    private showLoadFailure;
+    private clearLoadFailure;
+    private retryStripeForm;
     private handleChangePayment;
     protected template(): HTMLElement[];
     submitStripeForm(): void;

package/dist/types/modules/checkout/components/index.d.ts

@@ -5,6 +5,9 @@ export * from './checkout-buyer-summary.component';
 export * from './checkout-completed.component';
 export * from './checkout-deliver-to.component';
 export * from './checkout-deliver-to-summary.component';
+export * from './checkout-delivery-method.component';
+export * from './checkout-express-checkout.component';
+export * from './checkout-express-completion.component';
 export * from './checkout-gift-cards.component';
 export * from './checkout-header.component';
 export * from './checkout-information.component';

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

@@ -1,4 +1,7 @@
+import { type FulfillmentType } from '@/enums';
 export declare const STRIPE_SLOT_NAME = "lce-checkout-stripe-slot";
+export declare const STRIPE_MINIMUM_CHARGE = 50;
+export declare const EXPRESS_CHECKOUT_SLOT_NAME = "lce-checkout-express-checkout-slot";
 export declare const customerFormFields: {
     readonly firstName: "firstName";
     readonly lastName: "lastName";
@@ -31,3 +34,12 @@ export declare const billingFormFields: {
     readonly zipCode: "zipCode";
 };
 export type BillingFieldName = (typeof billingFormFields)[keyof typeof billingFormFields];
+export declare const DELIVERY_METHOD_LABEL: Record<FulfillmentType, string>;
+export declare const DELIVERY_METHOD_COLLAPSED_LABEL: Record<FulfillmentType, string>;
+export declare const DELIVERY_METHOD_UNAVAILABLE_COPY: Record<FulfillmentType, {
+    unavailable: string;
+    closed: string;
+    unsupported: string;
+}>;
+export declare const DELIVERY_METHOD_FREE_SHIPPING_THRESHOLD = 5000;
+export declare const CHANGE_LOCATION_FOCUS_KEY = "checkout-delivery-method-change-location";

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

@@ -1,2 +1,5 @@
 import type { ICheckoutCustomer } from '@/interfaces/api/checkout.interface';
-export declare function isValidCustomerPrefill(customer: ICheckoutCustomer, today?: Date): boolean;
+import type { ICheckoutLayout } from '@/interfaces/configs/checkout.interface';
+export declare function isBirthDateRequired(layout: Pick<ICheckoutLayout, 'requireBirthDate'> | null | undefined): boolean;
+export declare function isValidCustomerPrefill(customer: ICheckoutCustomer, requireBirthDate?: boolean, today?: Date): boolean;
+export declare function isValidBirthDate(birthDate: string | null | undefined, today?: Date): boolean;

package/dist/types/modules/checkout/express-wallet.d.ts

@@ -0,0 +1,12 @@
+import type { ICheckoutCustomer } from '@/interfaces/api/checkout.interface';
+export interface IExpressWalletBillingDetails {
+    name?: string;
+    email?: string;
+    phone?: string;
+    address?: Record<string, string | null>;
+}
+export declare function walletDisplayName(expressPaymentType: unknown): string;
+export declare function splitWalletName(walletName: string | undefined, existing: Pick<ICheckoutCustomer, 'firstName' | 'lastName'> | null | undefined): {
+    firstName: string;
+    lastName: string;
+};

package/dist/types/modules/checkout/stripe-js.d.ts

@@ -0,0 +1,2 @@
+export type StripeJsLoadFailure = 'blocked' | 'timeout' | 'error';
+export declare function loadStripeJs(): Promise<StripeJsLoadFailure | null>;

package/dist/types/modules/checkout/styles/delivery-method.style.d.ts

@@ -0,0 +1 @@
+export declare const getDeliveryMethodStyles: () => string;

package/dist/types/modules/checkout/styles/express-checkout.style.d.ts

@@ -0,0 +1 @@
+export declare const getExpressCheckoutStyles: () => string;

package/dist/types/modules/checkout/styles/express-completion.style.d.ts

@@ -0,0 +1 @@
+export declare const getExpressCompletionStyles: () => string;

package/dist/types/modules/ui-components/alert/alert.component.d.ts

@@ -1,24 +1,24 @@
 import { BaseComponent, type IOnStoreChanged } from '@/core/base-component.service';
 import type { StorePaths } from '@/core/store/interfaces/core.interface';
+export type AlertLevel = 'success' | 'warning' | 'error';
 export interface IAlertComponentParams {
-    errorStorePath: StorePaths;
-    fromEvents?: boolean;
+    storePaths: StorePaths[];
     showFirstEvent?: boolean;
     autoHideDelay?: number;
 }
 export declare class AlertComponent extends BaseComponent<IAlertComponentParams, null> {
     private hideTimeout;
-    private elements;
-    private lastAnnouncedKey;
+    private lastAnnounced;
     get hostClasses(): string[];
     beforeSetupStoreWatchers(): void;
-    afterRender(): void;
     onStoreWatch(changes: IOnStoreChanged[]): void;
-    private getErrorMessages;
-    private createErrorElement;
-    private scheduleHide;
-    private hideAllErrors;
-    private updateAlert;
+    afterRender(): void;
     protected template(): HTMLElement[];
+    private getAlerts;
+    private discard;
+    private createAlert;
+    private createDismissButton;
+    private scheduleSuccessHide;
+    private announce;
     disconnectedCallback(): void;
 }

package/dist/types/modules/ui-components/input/input.component.d.ts

@@ -22,7 +22,7 @@ export interface IInputComponentParams {
     label?: string;
     ariaLabel?: string;
     name: string;
-    autocomplete?: boolean;
+    autocomplete?: boolean | string;
     disabled?: boolean;
 }
 export declare class InputComponent extends BaseComponent<IInputComponentParams, null> {

package/dist/types/utils/format.d.ts

@@ -13,3 +13,7 @@ export declare function normalizeEngravingLines(lines: readonly (string | null |
 export declare function normalizeText<T extends string | null | undefined>(value: T): T;
 export declare function normalizeEmail<T extends string | null | undefined>(value: T): T;
 export declare function normalizeCode<T extends string | null | undefined>(value: T): T;
+export declare function formatPaymentMethodLabel(card: {
+    brand?: string | null;
+    last4?: string | null;
+} | null | undefined): string;

package/dist/types/utils/places-session-token.d.ts

@@ -0,0 +1 @@
+export declare function createPlacesSessionToken(): string;

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

@@ -9,7 +9,7 @@ Set address using a Google Places ID.
 ### Signature
 
 ```typescript
-setAddressByPlacesId(placesId: string): Promise<void>
+setAddressByPlacesId(placesId: string, sessionToken?: string): Promise<void>
 ```
 
 ### Parameters
@@ -17,6 +17,7 @@ setAddressByPlacesId(placesId: string): Promise<void>
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `placesId` | string | Yes | Google Places ID |
+| `sessionToken` | string | No | Google Places session token of the autocomplete requests that returned `placesId`. The details request ends that session, so Google bills the autocomplete requests as one session instead of per request. Applies only when the autocomplete requests used an API key in the same Google Cloud project as LiquidCommerce's address service. |
 
 ### Example
 
@@ -24,6 +25,9 @@ setAddressByPlacesId(placesId: string): Promise<void>
 await window.LiquidCommerce.elements.actions.address.setAddressByPlacesId(
   'ChIJOwg_06VPwokRYv534QaPC8g'
 );
+
+// With the session token your own Places Autocomplete requests used
+await window.LiquidCommerce.elements.actions.address.setAddressByPlacesId(placesId, sessionToken);
 ```
 
 ### How to Get Places ID

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

@@ -532,7 +532,9 @@ 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.
+(age 21+, year 1930 or later). The `birthDate` may be blank when the partner does not require a
+date of birth (`checkout.layout.requireBirthDate: false`); a supplied one is still validated.
+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.

package/docs/v1/api/client.md

@@ -64,6 +64,55 @@ const client = await ElementsCheckout('YOUR_API_KEY', {
 });
 ```
 
+The checkout-only client exposes `injectCheckout()`, `injectExpressCheckout()`, `actions.checkout`
+and `destroy()`.
+
+#### injectExpressCheckout()
+
+Injects only the Apple Pay and Google Pay wallet buttons, anywhere on the page, without the rest of
+the checkout UI. Confirming the wallet sheet places the order outright — the wallet's contact and
+billing details are sent to the checkout, so the shopper never fills a checkout form.
+
+```typescript
+injectExpressCheckout(params: IInjectExpressCheckoutParams): Promise<IInjectedComponent | null>
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `containerId` | string | Yes | ID of an element that already exists in the DOM |
+| `checkoutId` | string | No | Checkout token to bind the buttons to. Omit to use the checkout already loaded |
+| `variant` | `'buttons' \| 'section'` | No | `'buttons'` (default) is the wallet row alone; `'section'` adds the "Express Checkout" heading and OR divider |
+
+A checkout is prepared at injection time rather than when a button is tapped: Stripe gives the
+wallet's click handler one second to open its sheet, which is not enough time to create a checkout
+and a payment session. Without a `checkoutId` the checkout already in the store is reused, so the
+buttons can be injected beside a checkout the page has already loaded; the checkout-only client has
+no cart to fall back on, so it throws when there is no loaded checkout to attach to. Inject again
+with a new token whenever the address or fulfillment changes — the amounts the sheet shows come from
+the checkout the buttons were prepared against.
+
+The buttons only render where the shopper's platform offers a wallet, and the block hides itself
+entirely otherwise. Subscribe to `lce:actions.checkout_express_checkout_availability` to know which
+state you are in. Both wallets require an HTTPS origin on a domain registered with Stripe, each
+subdomain separately — see the
+[checkout component guide](../guides/checkout-component.md#express-checkout-apple-pay-and-google-pay).
+
+```javascript
+await client.injectExpressCheckout({
+  containerId: 'express-checkout-container'
+});
+```
+
+The full client exposes the same component as `injectExpressCheckoutElement()`, with the same
+parameters. It differs in one way: with no `checkoutId` and no checkout loaded, it prepares one from
+the current cart rather than throwing.
+
+```javascript
+await client.injectExpressCheckoutElement({
+  containerId: 'pdp-express-checkout'
+});
+```
+
 ### ElementsBuilder()
 
 Initialize the builder client, which exposes manual `inject*` / `update*` methods for fully programmatic composition.

package/docs/v1/api/configuration.md

@@ -335,6 +335,7 @@ interface ICheckoutLayout {
   emailOptIn: ICheckoutMarketingOptIn;
   smsOptIn: ICheckoutMarketingOptIn;
   allowGiftCards: boolean;
+  requireBirthDate?: boolean;
   legalMessage: ICheckoutLegalMessage;
   continueShoppingUrl: string;
   exitUrl: string;
@@ -350,6 +351,7 @@ interface ICheckoutLayout {
 | `emailOptIn` | `ICheckoutMarketingOptIn` | Email marketing opt-in configuration |
 | `smsOptIn` | `ICheckoutMarketingOptIn` | SMS marketing opt-in configuration |
 | `allowGiftCards` | `boolean` | Enable gift card payment option |
+| `requireBirthDate` | `boolean` | Whether the shopper must enter a date of birth to place an order. Defaults to `true`. When `false` the form's field is optional and express checkout does not ask for it |
 | `legalMessage` | `ICheckoutLegalMessage` | Legal/terms message configuration |
 | `continueShoppingUrl` | `string` | URL for "Continue Shopping" link |
 | `exitUrl` | `string` | URL for exit/back navigation |
@@ -546,7 +548,7 @@ interface IElementsGTMConfig {
 }
 ```
 
-If your site loads its own GTM container through Google tag gateway for advertisers, set `gatewayUrl` to that first-party path (e.g. `'https://www.yoursite.com/metrics/'` or `'/metrics/'`) so the SDK recognizes the container instead of treating the page as having none. Declarative equivalent: `data-gtm-gateway-url`. An empty or non-string value drops the whole `gtm` config with a console warning.
+If your site loads its own GTM container through Google tag gateway for advertisers, set `gatewayUrl` to that first-party path (e.g. `'https://www.yoursite.com/metrics/'` or `'/metrics/'`) so the SDK recognizes the container before GTM has booted it. It affects detection only: your container receives SDK events through `dataLayer` with or without it. Declarative equivalent: `data-gtm-gateway-url`. An empty or non-string value drops the whole `gtm` config with a console warning.
 
 See [Analytics → Google tag gateway](../reference/analytics.md#google-tag-gateway).
 

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

@@ -80,9 +80,16 @@ Checkout-only client interface returned by `ElementsCheckout()`.
 ```typescript
 interface IElementsCheckoutClient {
   injectCheckout(params: IInjectCheckoutParams): Promise<IInjectedComponent | null>;
+  injectExpressCheckout(params: IInjectExpressCheckoutParams): Promise<IInjectedComponent | null>;
   actions: { checkout: IElementsCheckoutActions };
   destroy(): void;
 }
+
+interface IInjectExpressCheckoutParams {
+  containerId: string;
+  checkoutId?: string;              // omit to use the checkout already loaded
+  variant?: 'section' | 'buttons';  // 'buttons' is the default outside the checkout element
+}
 ```
 
 ---
@@ -440,7 +447,9 @@ 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.
+(age 21+, year 1930 or later). The `birthDate` may be blank when the partner does not require a
+date of birth (`checkout.layout.requireBirthDate: false`); a supplied one is still validated.
+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.

package/docs/v1/guides/accessibility.md

@@ -105,6 +105,8 @@ Content that appears or changes without navigation is announced through a shared
 | Cart or checkout opened / closed | "Shopping cart opened" / "Shopping cart closed" |
 | Panel closed (product) | "Closed. Back to product options." |
 | Item added / removed, promo applied, totals changed | The new state, e.g. "Promo code SPRING applied, $5.00 off" |
+| Express checkout payment failed | "Express checkout failed. …" |
+| Card form could not load Stripe.js | The reason and what to do, e.g. "Your cookie settings are blocking our secure payment form. …" (assertive) |
 | Product list filtered or searched | "12 products found, showing 12" |
 | Validation failed | The field name and the error, interrupting (assertive) |
 | Carousel image changed | "Image 2 of 4" |
@@ -120,6 +122,14 @@ on render, and a live region recreated with its text already in place is not ann
   `aria-selected` / `aria-checked` — not toggle buttons with `aria-pressed`, which would describe
   each choice as an independent on/off switch. Product sizes are a `listbox`; the delivery options
   under each method are a `radiogroup`.
+- Checkout's **Delivery Method** section is an accordion whose header is a real `button` carrying
+  `aria-expanded`, and whose two methods are a `radiogroup` of `radio` cards. Choosing one re-prices
+  the order, so selection does not follow focus here either: arrow keys move between the methods and
+  `Enter` / `Space` commits, rather than committing a switch the shopper was only passing through.
+  A method that cannot fulfil is `aria-disabled` and not activatable, but the **Change Location**
+  button inside it stays reachable — it is the way out of that state, so it must not be sealed in
+  with the option it sits under. Each card names the method, its fee and its timing, or, when it
+  cannot fulfil, the reason why.
 - The delivery-method controls are a `tablist` of `tab`s. Only one method's options are rendered at
   a time, so the selected tab carries `aria-controls` and the region it swaps in is the matching
   `tabpanel`, labelled by that tab; the inactive tab points at nothing, because there is nothing
@@ -163,6 +173,26 @@ 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.
 
+### Express checkout
+
+The Apple Pay and Google Pay buttons are rendered by Stripe inside an iframe, so their own labels
+and keyboard behaviour are Stripe's. What the SDK owns around them:
+
+- The **"Express Checkout" heading** is an `h3`, matching the other checkout section headings. It is
+  rendered only by the `section` variant; injected on their own the buttons carry no heading, and the
+  host page's own outline supplies it.
+- The **`OR` divider** is decorative and carries `aria-hidden="true"`, so "OR" is not announced as
+  content between the buttons and the section below.
+- When the shopper's device offers **no wallet**, the heading and the divider are removed from the
+  accessibility tree along with the buttons, so no orphan rule or empty heading is left behind. The block is also removed on a gift order, which express cannot place, and where a
+  payment method is already bound to the checkout. It is offered to every shopper otherwise.
+- The **wallet sheet is browser UI**, not an SDK overlay: the browser owns focus while it is open and
+  returns it to the button that opened it. Dismissing the sheet changes nothing in the page, so
+  nothing is announced.
+- Failures are announced assertively, because the shopper has just authorised a payment and the sheet
+  that showed the error has already closed. Confirming the sheet places the order outright, so there
+  is nothing to announce on the success path beyond the order confirmation itself.
+
 ### Images and icons
 
 - Product photos use the product name as their alt text; a photo painted as a CSS background is
@@ -239,6 +269,8 @@ 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.
 
+If the card form cannot load Stripe.js — a consent tool holding the script back, a blocker, or a failed request — the reason and a keyboard-operable **Try again** button take the card form's place, and the message is announced assertively. While a retry runs the button stays focusable (`aria-disabled`, not `disabled`), so focus is not lost; if the retry fails, focus moves to the new **Try again** button, and if it succeeds, to the card form's container.
+
 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

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

@@ -56,6 +56,12 @@ The recommended method - provides accurate geocoding:
 await window.LiquidCommerce.elements.actions.address.setAddressByPlacesId('ChIJOwg_06VPwokRYv534QaPC8g');
 ```
 
+If you run Google Places Autocomplete yourself with a [session token](https://developers.google.com/maps/documentation/places/web-service/session-tokens), pass the same token as the second argument. The details request then ends your session, and Google bills the autocomplete requests as one session instead of per request. Google only groups requests whose API keys belong to the same Google Cloud project, so this applies only when your autocomplete requests used the same project as LiquidCommerce's address service; a token from autocomplete requests made with an API key in another project doesn't change billing:
+
+```javascript
+await window.LiquidCommerce.elements.actions.address.setAddressByPlacesId(placesId, sessionToken);
+```
+
 **How to get a Places ID:**
 
 Visit [Google Place IDs](https://developers.google.com/maps/documentation/places/web-service/place-id#find-id) for details on obtaining a Places ID.

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

@@ -371,6 +371,17 @@ window.addEventListener('lce:actions.checkout_item_quantity_decrease', (event) =
 });
 ```
 
+### Delivery Method
+
+Fires when the shopper switches a single-item checkout between same-day delivery and shipping.
+
+```javascript
+window.addEventListener('lce:actions.checkout_delivery_method_updated', (event) => {
+  const { fulfillmentType, previousFulfillmentType } = event.detail.data;
+  console.log(`Delivery method: ${previousFulfillmentType} to ${fulfillmentType}`);
+});
+```
+
 ### Tips
 
 ```javascript
@@ -400,6 +411,22 @@ window.addEventListener('lce:actions.checkout_submit_failed', (event) => {
   console.error('Payment failed:', message);
   // Show error message
 });
+
+// The card form could not load Stripe.js (fires again for each failed Try again)
+window.addEventListener('lce:actions.checkout_payment_form_failed', (event) => {
+  const { reason } = event.detail.data; // 'blocked' | 'timeout' | 'error'
+  console.warn('Card form unavailable:', reason);
+});
+```
+
+### Express Checkout
+
+```javascript
+// Wallet availability settled or changed (always fires at least once per block)
+window.addEventListener('lce:actions.checkout_express_checkout_availability', (event) => {
+  const { data } = event.detail;
+  console.log(data.available ? `Wallets: ${data.wallets.join(', ')}` : 'No wallets available');
+});
 ```
 
 ### Promo Codes
@@ -496,13 +523,92 @@ const client = await Elements('YOUR_API_KEY', {
 
 The SDK uses Stripe for payment processing. Payment form is embedded and handles:
 - Credit/debit cards
-- Apple Pay (when available)
-- Google Pay (when available)
 - PCI compliance
 - 3D Secure authentication
 
 No additional Stripe integration code needed - it's built-in.
 
+### Cookie consent and Content Security Policy
+
+The card form runs on Stripe.js, which the SDK loads from `https://js.stripe.com` when the payment
+step opens. Two things on a host page can stop it loading:
+
+- **Cookie-consent tools with auto-blocking** (OneTrust, Cookiebot and similar) hold back every
+  script in a category the shopper has not accepted. If Stripe is filed under anything other than
+  strictly necessary, a shopper who declines that category cannot pay by card. Classify Stripe — the
+  `js.stripe.com` script and the cookies it sets — as **Strictly Necessary**, or exclude it from
+  auto-blocking. Card payment does not work without it.
+- **A Content Security Policy** has to allow Stripe.js: `https://js.stripe.com` in `script-src` and
+  `frame-src`, and `https://api.stripe.com` in `connect-src`. Stripe's
+  [CSP guidance](https://docs.stripe.com/security/guide#content-security-policy) lists the full set.
+
+When Stripe.js cannot load, or loads but cannot build the card form, the shopper sees a message and a **Try again** button where the card form
+would be, rather than an empty space. A script held back by a consent tool asks them to allow
+cookies; a load that stalled or failed points them at their connection or an ad blocker. The SDK also
+fires [`lce:actions.checkout_payment_form_failed`](./events.md) with a `reason` of `blocked`, `timeout`
+or `error`, so the page can respond:
+
+```javascript
+window.addEventListener('lce:actions.checkout_payment_form_failed', (event) => {
+  const { reason } = event.detail.data;
+  if (reason === 'blocked') {
+    // Stripe is held back by consent settings: reopen your consent tool's preferences here.
+  }
+});
+```
+
+### Express checkout (Apple Pay and Google Pay)
+
+Apple Pay and Google Pay are offered as express checkout buttons at the top of the checkout, above
+the gift toggle. Tapping one collects the shopper's contact and billing details from the wallet and
+places the order without them completing the checkout forms.
+
+Express checkout is offered to every shopper whose platform can show a wallet. Each wallet is
+requested with Stripe's `always` policy, so the button renders wherever the device supports it rather
+than only where Stripe judges it good for conversion. The block hides itself entirely — heading,
+buttons and divider — in four cases: the device or browser offers no wallet, the order is a
+gift, a payment method is already bound to the checkout, or Stripe.js fails to load. Subscribe to
+[`lce:actions.checkout_express_checkout_availability`](./events.md) to know which state you are in.
+
+Two things are required outside the SDK:
+
+- **The page must be served over HTTPS.** Stripe requires this in development as well as production;
+  the wallet buttons do not render on a plain-HTTP page.
+- **Every domain that serves the buttons must be registered with Stripe** for the account issuing the
+  publishable key, in both sandbox and live mode. Stripe requires this for Apple Pay and Google Pay
+  alike, and it covers subdomains: `shop.example.com` is registered separately from `example.com`.
+  Registering in live mode registers the sandbox too. This applies per partner domain.
+
+Approving the wallet sheet hands the order to the **express completion view**, which replaces the
+checkout form the moment the sheet closes. The view saves the shopper's name, email and phone from
+the wallet as the checkout's customer and binds the approved payment method; the wallet's billing
+address goes to Stripe with that payment method, and the order's own billing address stays the one
+the checkout already holds. Then it asks for the one thing no wallet returns — the shopper's **date
+of birth** — with the same 21+ validation as the form, and places the order from its **Complete
+order** button. A date the shopper already typed into the form is used instead, and the view goes
+straight to placing the order. When the partner has turned off **Require date of birth** in the
+builder (`checkout.layout.requireBirthDate: false`), the view skips the step and places the order as
+soon as the payment method is bound. A shopper can step **back to checkout** from the view; the
+payment method stays bound, and the form asks for the date of birth itself when one is required.
+
+If the wallet sheet itself fails — a declined authorisation, or a total that changed while it was
+open — the sheet reports the reason and nothing is handed on. Anything that fails after the sheet
+has closed is reported on the view, with a retry. The order is placed only for the checkout and the
+total the sheet was opened for: the server verifies both against the wallet's intent at completion,
+so a total that moved in between is refused there as well and the shopper approves again.
+
+The wallet tap is also refused, with nothing charged, when a cart is below a retailer's minimum
+purchase amount — the same condition that keeps the Place Order button disabled. Presale checkouts
+are exempt from it, as they are there.
+
+Express checkout is not offered on a gift order: a gift needs the recipient's name, email, phone and
+message, and no wallet returns any of them. Turning on "Send as a gift" hides the block, and turning
+it back off restores it.
+
+The buttons are not confined to the checkout element. Inject them anywhere on the page with
+`injectExpressCheckoutElement()` on the full client, or `injectExpressCheckout()` on the
+checkout-only client.
+
 ## Checkout Flow
 
 ### Standard Flow
@@ -623,6 +729,7 @@ window.addEventListener('lce:actions.checkout_submit_failed', () => {
 checkout: {
   layout: {
     allowGiftCards: true,       // Show gift card input
+    requireBirthDate: true,     // Require a date of birth to place an order
     emailOptIn: {
       show: true,              // Show email opt-in checkbox
       checked: false,            // Default unchecked
@@ -658,10 +765,16 @@ checkout: {
 
 ### Payment Form Not Loading
 
+If the Payment section reads "Your cookie settings are blocking our secure payment form", a consent
+tool on the page is holding Stripe.js back — see
+[Cookie consent and Content Security Policy](#cookie-consent-and-content-security-policy).
+Otherwise:
+
 1. Check internet connection (Stripe requires network)
-2. Verify Stripe is not blocked by ad blockers
-3. Check browser console for Stripe errors
-4. Ensure your API key is valid
+2. Verify Stripe is not blocked by ad blockers or the page's Content Security Policy
+3. Listen for `lce:actions.checkout_payment_form_failed` and check its `reason`
+4. Check browser console for Stripe errors
+5. Ensure your API key is valid
 
 ### Customer Info Not Pre-filling
 
@@ -691,7 +804,9 @@ 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.
+(age 21+, year 1930 or later). The `birthDate` may be blank when the partner does not require a
+date of birth (`checkout.layout.requireBirthDate: false`); a supplied one is still validated.
+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.

package/docs/v1/guides/events.md

@@ -706,6 +706,22 @@ window.addEventListener('lce:actions.checkout_item_engraving_updated', (event) =
 });
 ```
 
+### `lce:actions.checkout_delivery_method_updated`
+
+Fires when the shopper moves a single-item checkout between same-day delivery and shipping. The order
+is re-priced, so the totals change with it.
+
+**Data includes:** `cartId`, `fulfillmentType`, `previousFulfillmentType`, `fulfillmentId`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_delivery_method_updated', (event) => {
+  const { data } = event.detail;
+  console.log('Delivery method now', data.fulfillmentType);
+});
+```
+
 ### `lce:actions.checkout_tip_updated`
 
 Fires when delivery tips are updated.
@@ -858,6 +874,48 @@ window.addEventListener('lce:actions.checkout_gift_card_failed', (event) => {
 });
 ```
 
+### `lce:actions.checkout_express_checkout_availability`
+
+Fires once the express checkout block has settled which wallet buttons the shopper can reach, and
+again whenever that changes. It always fires at least once per block. `available` is `false` on a
+device or browser that offers no wallet, on a gift order, when a payment method is already bound to
+the checkout, and when Stripe.js cannot load; in every case the SDK hides the whole block including
+its divider.
+
+**Data includes:** `cartId`, `available`, `wallets`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_express_checkout_availability', (event) => {
+  const { data } = event.detail;
+  console.log(data.available ? `Wallets: ${data.wallets.join(', ')}` : 'No wallets available');
+});
+```
+
+### `lce:actions.checkout_payment_form_failed`
+
+Fires when the card form cannot load Stripe.js, so the card fields cannot appear. The shopper sees a
+message and a **Try again** button where the card form would be; each attempt that fails fires the
+event again. `reason` is `blocked` when something on the page held the script back before it was
+fetched — typically a cookie-consent tool with auto-blocking, for a shopper who has not accepted the
+category Stripe is filed under — and `timeout` or `error` when the load stalled or failed (`error` also when Stripe.js loads but cannot
+build the card form, as when `api.stripe.com` is blocked). See
+[Cookie consent and Content Security Policy](./checkout-component.md#cookie-consent-and-content-security-policy).
+
+**Data includes:** `cartId`, `reason` (`'blocked' | 'timeout' | 'error'`).
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_payment_form_failed', (event) => {
+  const { data } = event.detail;
+  if (data.reason === 'blocked') {
+    // For example, reopen your consent tool's preferences so the shopper can allow Stripe.
+  }
+});
+```
+
 ### `lce:actions.checkout_product_add_success`
 
 Fires when products are added to checkout via the actions API.

package/docs/v1/guides/theming.md

@@ -168,6 +168,7 @@ customTheme: {
         text: 'Receive SMS updates about your order and exclusive deals.'
       },
       allowGiftCards: true,
+      requireBirthDate: true,
       legalMessage: { show: true, text: 'By placing your order, you agree to our Terms of Service and Privacy Policy.' },
       continueShoppingUrl: 'https://yoursite.com/shop',
       exitUrl: 'https://yoursite.com',