@liquidcommerce/elements-sdk 2.7.44 → 2.7.45

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

@@ -155,6 +155,7 @@ interface IFulfillment {
   fee: number;
   timezone: string;
   hourStatus: { isOpen: boolean; openTime: string; isClosed: boolean; closeTime: string };
+  deliveryAvailability?: DeliveryAvailability; // same-day only, where the retailer schedules delivery
 }
 
 interface IProduct {

package/docs/v1/api/client.md

@@ -64,8 +64,10 @@ const client = await ElementsCheckout('YOUR_API_KEY', {
 });
 ```
 
-The checkout-only client exposes `injectCheckout()`, `injectExpressCheckout()`, `actions.checkout`
-and `destroy()`.
+The checkout-only client exposes `injectCheckout()`, `injectExpressCheckout()`, `actions.checkout`,
+`actions.analytics` and `destroy()`. `actions.analytics` reports the steps your own UI renders —
+product views, address, availability, starting checkout — to the same GTM stream the checkout
+reports to; see [Analytics Actions](./actions/analytics-actions.md).
 
 #### injectExpressCheckout()
 
@@ -73,6 +75,9 @@ Injects only the Apple Pay and Google Pay wallet buttons, anywhere on the page,
 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.
 
+Express checkout is off by default: pass `development.enableExpressCheckout: true` in the client config to show it. Without it this
+method renders nothing and resolves to `null`.
+
 ```typescript
 injectExpressCheckout(params: IInjectExpressCheckoutParams): Promise<IInjectedComponent | null>
 ```
@@ -591,6 +596,8 @@ import type {
 } from '@liquidcommerce/elements-sdk';
 ```
 
+Both package entries, including their Node/SSR stubs, export `DeliverySlot`, `DeliveryAvailability`, `CheckoutDeliveryScheduling` and `CheckoutDeliverySelection`. Both clients expose `actions.checkout.loadDeliverySlots(fulfillmentId)` and `actions.checkout.chooseDeliverySlot(fulfillmentId, slotId)`.
+
 See [TypeScript Types](./typescript-types.md) for complete type reference.
 
 ## Best Practices

package/docs/v1/api/configuration.md

@@ -563,6 +563,7 @@ interface ILiquidCommerceElementsDevelopmentConfig {
   customApiUrl?: string;
   openShadowDom?: boolean;
   mockMode?: boolean;
+  enableExpressCheckout?: boolean;
 }
 ```
 
@@ -571,6 +572,9 @@ interface ILiquidCommerceElementsDevelopmentConfig {
 | `customApiUrl` | `string` | Custom API URL for local or custom backend testing |
 | `openShadowDom` | `boolean` | Use an OPEN (inspectable) Shadow DOM instead of the default closed mode, for debugging. Shadow DOM is always attached; forced off in production (default: `false`) |
 | `mockMode` | `boolean` | Enable mock mode to receive mock data from the API; sends an `X-Liquid-Api-Mock-Mode` header with all requests (default: `false`) |
+| `enableExpressCheckout` | `boolean` | Show the Apple Pay / Google Pay express checkout and the checkout's delivery-method switch (same-day vs shipping) — the express block and delivery-method section in the checkout element, and `injectExpressCheckoutElement()` / `injectExpressCheckout()`, which otherwise render nothing and resolve to `null`. Honoured in every environment, production included (default: `false`) |
+
+> **Temporary:** this flag exists only while express checkout and the delivery-method switch are being verified. Once they are confirmed, the flag will be removed and both will always be on.
 
 > To pre-select a payment method and skip the card form (in any environment), use [`actions.checkout.setSavedPaymentMethod`](./actions/checkout-actions.md#actionscheckoutsetsavedpaymentmethod) instead.
 

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

@@ -21,6 +21,8 @@ import { ElementsCheckout } from '@liquidcommerce/elements-sdk/checkout';
 import type {
   IElementsCheckoutClient,
   IElementsCheckoutActions,
+  IAnalyticsActions,
+  IAnalyticsItem,
   ILiquidCommerceElementsCheckoutClientConfig,
   IInjectedComponent
 } from '@liquidcommerce/elements-sdk/checkout';
@@ -81,7 +83,7 @@ Checkout-only client interface returned by `ElementsCheckout()`.
 interface IElementsCheckoutClient {
   injectCheckout(params: IInjectCheckoutParams): Promise<IInjectedComponent | null>;
   injectExpressCheckout(params: IInjectExpressCheckoutParams): Promise<IInjectedComponent | null>;
-  actions: { checkout: IElementsCheckoutActions };
+  actions: { checkout: IElementsCheckoutActions; analytics: IAnalyticsActions };
   destroy(): void;
 }
 
@@ -158,6 +160,7 @@ interface ILiquidCommerceElementsDevelopmentConfig {
   customApiUrl?: string;
   openShadowDom?: boolean;
   mockMode?: boolean;  // when true, sends an 'X-Liquid-Api-Mock-Mode' header to receive mock data
+  enableExpressCheckout?: boolean;  // show express checkout and the delivery-method switch; off by default, honoured in production
 }
 ```
 
@@ -309,6 +312,7 @@ interface ILiquidCommerceElementsActions {
   address: IAddressActions;
   cart: ICartActions;
   checkout: ICheckoutActions;
+  analytics: IAnalyticsActions;
 }
 ```
 
@@ -320,6 +324,74 @@ Checkout actions available in the checkout-only client. This is `ICheckoutAction
 interface IElementsCheckoutActions extends Omit<ICheckoutActions, 'openCheckout' | 'closeCheckout' | 'toggleCheckout'> {}
 ```
 
+### IAnalyticsActions
+
+Reports steps a host renders with its own UI to the SDK's GTM / GA4 stream. On both the full client
+and the checkout-only client. See [Analytics Actions](./actions/analytics-actions.md).
+
+```typescript
+interface IAnalyticsActions {
+  search(searchTerm: string): void;
+  viewItem(item: IAnalyticsItem): void;
+  viewItemList(items: IAnalyticsItem[], list?: IAnalyticsItemList): void;
+  selectItem(item: IAnalyticsItem, list?: IAnalyticsItemList): void;
+  addToCart(item: IAnalyticsItem): void;
+  removeFromCart(item: IAnalyticsItem): void;
+  viewCart(items: IAnalyticsItem[]): void;
+  beginCheckout(items: IAnalyticsItem[], options?: { coupon?: string }): void;
+  addressUpdated(address: IAnalyticsAddress): void;
+  addressFailed(failure: IAnalyticsAddressFailure): void;
+  productNoAvailability(details: IAnalyticsAvailability): void;
+  productSizeNoAvailability(details: IAnalyticsAvailability): void;
+  productFulfillmentNoAvailability(details: IAnalyticsFulfillmentAvailability): void;
+}
+
+interface IAnalyticsItem {
+  id: string;            // the selected size's id
+  name: string;
+  brand?: string;
+  size?: string;
+  categoryPath?: string; // product catPath
+  price?: number;        // cents
+  quantity?: number;
+  type?: string;
+  subType?: string;
+  image?: string;
+  upc?: string;
+  groupingId?: string;
+  index?: number;
+}
+
+interface IAnalyticsItemList {
+  id?: string;
+  name?: string;
+}
+
+interface IAnalyticsAddress {
+  placesId?: string;
+  formattedAddress?: string;
+  address: Partial<IAddressAddress>;
+  coordinates?: IAddressCoordinates;
+}
+
+interface IAnalyticsAddressFailure {
+  placesId?: string;
+  formattedAddress?: string;
+  address?: Partial<IAddressAddress>;
+  error: string;
+}
+
+interface IAnalyticsAvailability {
+  item: IAnalyticsItem;
+  reason: string;
+  address?: Partial<IAddressAddress>;
+}
+
+interface IAnalyticsFulfillmentAvailability extends IAnalyticsAvailability {
+  fulfillmentType: FulfillmentType;
+}
+```
+
 See [Actions API](./actions/) for detailed method signatures.
 
 ---
@@ -353,6 +425,7 @@ type ComponentType =
   | 'drawer' | 'input' | 'engraving-form' | 'engraving-view'
   | 'buttons-cart-open' | 'powered-by' | 'lce-element'
   | 'purchase-min-alert' | 'alert' | 'promo-code-ticker'
+  | 'checkout-delivery-scheduling' // Internal child of checkout
   // ...and additional internal component types
 ```
 
@@ -499,3 +572,39 @@ 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.
+
+## Delivery scheduling types
+
+The main and checkout-only entries, and their Node/SSR stubs, export these types.
+
+```typescript
+export interface DeliverySlot {
+  id: string; // server-issued, `<fulfillmentOptionId>:<window start, Unix seconds>`
+  start: string; // ISO-8601 UTC
+  end: string; // ISO-8601 UTC
+  cutoff: string; // ISO-8601 UTC, latest time to order for this window ("Order by")
+}
+
+export interface DeliveryAvailability {
+  status: 'available' | 'unavailable'; // available when the store can deliver now or offers windows
+  canDeliverNow: boolean;
+  canSchedule: boolean;
+  timezone: string | null; // store IANA time zone; null when the server has none. The SDK shows times in the viewer's browser time zone, not this one
+  nextSlot: DeliverySlot | null; // null on a product fulfillment of a closed store: checkout gives the windows
+  checkedAt: string;
+}
+
+export interface CheckoutDeliveryScheduling {
+  availability: DeliveryAvailability;
+  slots: DeliverySlot[]; // only in answer to deliverySlotsFulfillmentId; empty otherwise
+  selectedSlotId: string | null; // null = as soon as possible / no window
+  selectedSlot?: DeliverySlot | null; // the accepted window with its real end and cutoff; null when none
+}
+
+export interface CheckoutDeliverySelection {
+  fulfillmentId: string;
+  slotId: string | null;
+}
+```
+
+`ICheckoutFulfillment.deliveryScheduling` is optional. `ICheckoutPrepareParams` takes `deliverySelections?: CheckoutDeliverySelection[]` and `deliverySlotsFulfillmentId?: string`. `actions.checkout` adds `loadDeliverySlots(fulfillmentId: string): Promise<DeliverySlot[]>` and `chooseDeliverySlot(fulfillmentId: string, slotId: string | null): Promise<void>` on both clients, and `ICheckoutDetailsEventData` adds `deliveryScheduling: Record<string, CheckoutDeliveryScheduling>`.

package/docs/v1/guides/accessibility.md

@@ -152,7 +152,10 @@ on render, and a live region recreated with its text already in place is not ann
 - An option in a single-select group carries its **whole** visible content in its accessible name.
   `option` and `radio` have presentational children, so the name is the only channel: a delivery
   option names the retailer, the price, the timing, the delivery fee and — for same-day — the
-  store address and whether it is currently closed.
+  store address and whether it is currently closed. A closed store that schedules delivery leads
+  with that instead ("Columbus Avenue Wines, closed now, schedule delivery"), followed by
+  "next arrival Thu, 1 PM – 2 PM" only when the server sends a next window; its card
+  stays enabled.
 - The California Proposition 65 warning on the product is a native `<details>` / `<summary>`
   disclosure: the summary is a button that exposes its expanded state, and `Enter` / `Space` toggle
   it with no scripting involved. Its `+` / `−` indicator is decorative and hidden. In checkout it is
@@ -289,3 +292,7 @@ from the accessibility tree; unknown choices retain their named, keyboard-operab
 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.
+
+### Delivery date and arrival windows
+
+The delivery picker is a named native modal dialog opened from each delivery's Schedule delivery or Edit control. Dates and arrival windows are radio groups with one tab stop each and arrow-key selection; the date strip scrolls inside the dialog and unavailable dates are disabled. While windows load, the dialog is marked busy and shows a loading line; Cancel and Close stay available. Changes are drafts until Save; Cancel, Close and Escape discard them, and closing returns focus to the opening control. The dialog stays the same modal while it is open: a date or window change updates its contents in place, so it is not announced again. Save errors keep the dialog open and move focus to the error. Success is announced politely; errors and an expired or unavailable window are announced assertively, each with its own message. No time zone is shown above the windows; the ASAP window's accessible name is "As soon as possible", and the first window's accessible name also carries its "Order by" time. The window list scrolls inside the dialog, and the chosen or focused window is kept in view as the picker opens, the date changes and arrow keys move.

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

@@ -14,6 +14,8 @@ The Cart component automatically:
 - Persists cart across sessions and tabs
 - Provides checkout navigation
 
+A same-day line from a store that is closed now but takes orders for later (its fulfillment's `deliveryAvailability` says it cannot deliver now and can schedule) shows "Schedule delivery" in place of the delivery estimate. The shopper chooses the delivery window in checkout.
+
 ## Basic Usage
 
 The cart is automatically available when using the SDK - no explicit injection needed for the drawer. However, you need a way for users to open it.

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

@@ -286,6 +286,31 @@ console.log(checkoutData);
 // }
 ```
 
+### Load Delivery Slots
+
+Load the delivery windows for one fulfillment that has scheduled delivery. `getDetails().deliveryScheduling` is keyed by fulfillment ID:
+
+```javascript
+const actions = window.LiquidCommerce.elements.actions.checkout;
+const [fulfillmentId] = Object.keys(actions.getDetails().deliveryScheduling);
+
+const slots = await actions.loadDeliverySlots(fulfillmentId);
+// [{ id: 'option_1:1791475200', start: '2026-10-08T16:00:00.000Z', end: '2026-10-08T17:00:00.000Z', cutoff: '2026-10-08T15:00:00.000Z' }, ...]
+```
+
+### Choose Delivery Slot
+
+Save a window from the last loaded list, or `null` for as soon as possible:
+
+```javascript
+await window.LiquidCommerce.elements.actions.checkout.chooseDeliverySlot(fulfillmentId, slots[0].id);
+
+// As soon as possible (only when availability.canDeliverNow is true)
+await window.LiquidCommerce.elements.actions.checkout.chooseDeliverySlot(fulfillmentId, null);
+```
+
+The promise rejects when the window was not offered, the fulfillment is unknown or another checkout update is in flight. See the [checkout actions reference](../api/actions/checkout-actions.md#delivery-scheduling-actions).
+
 ## Events
 
 ### Checkout Lifecycle
@@ -373,7 +398,9 @@ 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.
+Fires when the shopper switches a single-item checkout between same-day delivery and shipping. The
+switch is shown only with `development.enableExpressCheckout: true`, the same opt-in as express
+checkout.
 
 ```javascript
 window.addEventListener('lce:actions.checkout_delivery_method_updated', (event) => {
@@ -382,6 +409,17 @@ window.addEventListener('lce:actions.checkout_delivery_method_updated', (event)
 });
 ```
 
+### Delivery Time
+
+Fires once after checkout accepts a delivery window or as soon as possible, from the built-in picker or from `chooseDeliverySlot`.
+
+```javascript
+window.addEventListener('lce:actions.checkout_delivery_selection_updated', (event) => {
+  const { deliveryScheduling } = event.detail.data;
+  console.log('Delivery windows by fulfillment:', deliveryScheduling);
+});
+```
+
 ### Tips
 
 ```javascript
@@ -427,6 +465,11 @@ window.addEventListener('lce:actions.checkout_express_checkout_availability', (e
   const { data } = event.detail;
   console.log(data.available ? `Wallets: ${data.wallets.join(', ')}` : 'No wallets available');
 });
+
+// The shopper tapped a wallet button and its sheet opened
+window.addEventListener('lce:actions.checkout_express_checkout_started', (event) => {
+  console.log(`Wallet sheet opened: ${event.detail.data.wallet}`);
+});
 ```
 
 ### Promo Codes
@@ -563,7 +606,12 @@ Apple Pay and Google Pay are offered as express checkout buttons at the top of t
 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
+Express checkout is off by default: pass `development.enableExpressCheckout: true` in the client config to show it. Without it the checkout element renders
+no express block, and the injection methods below render nothing and resolve to `null`.
+
+> **Temporary:** this flag exists only while express checkout and the delivery-method switch are being verified. Once they are confirmed, the flag will be removed and both will always be on.
+
+Once enabled, 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
@@ -856,3 +904,17 @@ 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.
+
+## Scheduled delivery
+
+When an AccelPay retailer has scheduled delivery turned on, checkout shows a **Delivery time** row for that delivery, between the delivery details and payment. It reads "ASAP" while the store can deliver now, or asks for a window when it cannot. The row's button reads **Schedule** while the row is on as soon as possible, **Edit** after a window is saved, and **Schedule delivery** when the shopper must choose a window. It opens a dialog that loads the windows for that delivery: date cards for today and the next 7 days, then arrival windows. Days and times are in the shopper's own time zone (the browser's), so "Today" is the shopper's today; no time zone is shown. The window list scrolls inside the dialog and keeps the chosen window in view. The first window shows "Order by" with its cutoff, and **ASAP** sits next to it when the store can deliver now (screen readers hear "As soon as possible"). Choices are drafts until **Save**; Cancel, Close and Escape discard them.
+
+The accepted window shows in the row and on the items in the order summary ("Scheduled for Thu, 1 PM – 2 PM"), and on the thank-you page as "Delivery time" with "Thu, 1 PM – 2 PM". An ASAP order adds no line there. If the window's cutoff passes before the order is placed, the SDK clears it, shows "Your delivery window has passed. Choose a new delivery time.", reopens the picker and keeps Place Order disabled until a new choice is saved. If the store no longer offers the window, the same happens with "Your delivery window is no longer available. Choose a new delivery time." Everything else the shopper entered stays.
+
+A store that was added to the cart while closed cannot deliver now, so checkout asks for a window and offers no ASAP. If a store closes after the shopper chose ASAP, Place Order answers `delivery_window_required`: the SDK shows "The store cannot deliver now. Choose a delivery time.", opens the picker and keeps Place Order disabled until a window is saved.
+
+In a checkout with more than one fulfillment group (another store, or shipping), each same-day group with scheduled delivery gets its own **Delivery time** row and its own picker, which loads that group's windows. Its button reads **Schedule this store's delivery** (**Edit** after a window is saved), and the picker is named after the store ("Schedule delivery from Columbus Avenue Wines"). Every prepare sends each group's current choice, so saving one group keeps the other's window. A group whose store can deliver now stays on as soon as possible; a group whose store cannot needs its own window before payment and Place Order. When a window lapses, only that group's window is cleared and only its picker reopens: the SDK clears the window whose cutoff passed on the page, and for `delivery_window_required` marks the groups that have no window. When an error names its group (`fulfillmentId` on the error entry), only that group is cleared. A name that is not a scheduling group of this checkout counts as no name; when the error names no group and the SDK cannot place it, every saved window is cleared (a refused window save clears nothing and asks for another time). When the save of one store's window is refused because the window of another store lapsed, the SDK clears that other window and names its store: "Choose a delivery window for Columbus Avenue Wines before continuing." Until each store that cannot deliver now has a window, payment says which: "Choose a delivery window for Amsterdam Liquors before continuing." In an order with more than one fulfillment group, the thank-you page has one line per group, named after its store: the accepted window for a scheduled group ("Columbus Avenue Wines" with "Thu, 1 PM – 2 PM"), and the group's own expectation for the others ("Harbor Spirits" with "Ships in 3-5 days"). A scheduled group never shows the as-soon-as-possible expectation. While a store that cannot deliver now has no accepted window, the express wallet buttons stay off, like the card form. When checkout refuses a store that has scheduled delivery and also another delivery method (`multiple_fulfillment_options_per_store`, code 5516), the SDK shows the refusal as the checkout error and keeps the saved windows: "Scheduled delivery cannot be combined with another delivery method from the same store. Choose ASAP delivery, or use one delivery method for all items from this store." When that store is closed now, the text leaves out ASAP: "This store is closed now. Use one delivery method for all items from this store." When the refusal says whether the store is closed now (`closedNow` on the error entry), the SDK uses that. Otherwise, when Place Order is refused, the SDK reads the cart again and decides "closed now" from its `deliveryAvailability`, because a store can close after the last prepare. Place Order and the express wallet stay off until a prepare succeeds after a change to the cart or to a delivery choice.
+
+In the delivery-method switch, a same-day method whose `deliveryAvailability` says the store cannot deliver now but can schedule shows "Schedule delivery" in place of its delivery estimate. Without `deliveryAvailability` the card shows the estimate as before.
+
+Checkouts without scheduled delivery are unchanged. For a custom UI, see `actions.checkout.loadDeliverySlots` and `actions.checkout.chooseDeliverySlot` in the checkout actions reference, and the `checkout_delivery_selection_updated` event.

package/docs/v1/guides/events.md

@@ -502,7 +502,7 @@ window.addEventListener('lce:actions.cart_product_add_failed', (event) => {
 
 Fires when checkout data loads.
 
-**Data includes:** `cartId`, `amounts`, `itemCount`, `isGift`, `billingSameAsShipping`.
+**Data includes:** `cartId`, `amounts`, `itemCount`, `isGift`, `billingSameAsShipping`, `deliveryScheduling` (keyed by fulfillment ID).
 
 **Example**
 
@@ -709,7 +709,8 @@ 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.
+is re-priced, so the totals change with it. The switch is shown only with
+`development.enableExpressCheckout: true`.
 
 **Data includes:** `cartId`, `fulfillmentType`, `previousFulfillmentType`, `fulfillmentId`.
 
@@ -893,6 +894,26 @@ window.addEventListener('lce:actions.checkout_express_checkout_availability', (e
 });
 ```
 
+### `lce:actions.checkout_express_checkout_started`
+
+Fires when the shopper taps a wallet button and the SDK opens the wallet sheet, inside the checkout
+or on a block placed with `injectExpressCheckout` / `injectExpressCheckoutElement`. It fires for every
+tap, and not for a tap the block refuses (a total that moved, an unmet order minimum, a second tap
+while an order is being placed). The tap happens inside Stripe's frame, so this is the only way a host
+page learns of it — for instance, to report `add_to_cart` for a product-page wallet with
+[`actions.analytics`](../api/actions/analytics-actions.md).
+
+**Data includes:** `cartId`, `wallet` (Stripe's name for it: `'apple_pay'`, `'google_pay'`, …).
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_express_checkout_started', (event) => {
+  const { wallet } = event.detail.data;
+  console.log(`Wallet sheet opened: ${wallet}`);
+});
+```
+
 ### `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
@@ -946,6 +967,19 @@ window.addEventListener('lce:actions.checkout_product_add_failed', (event) => {
 });
 ```
 
+### `lce:actions.checkout_delivery_selection_updated`
+
+Emitted once after checkout prepare accepts a delivery window or ASAP choice, from the built-in picker or from `actions.checkout.chooseDeliverySlot`. Draft choices in the picker and failed saves do not emit it.
+
+**Data:** `ICheckoutDetailsEventData`, including `deliveryScheduling: Record<string, CheckoutDeliveryScheduling>` keyed by fulfillment ID, with each accepted `selectedSlotId` and `selectedSlot`.
+
+```javascript
+window.addEventListener('lce:actions.checkout_delivery_selection_updated', (event) => {
+  const scheduling = event.detail.data.deliveryScheduling;
+  console.log('Delivery windows:', scheduling);
+});
+```
+
 ## Form Events
 
 ### `lce:forms.customer`

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

@@ -480,6 +480,12 @@ await window.LiquidCommerce.elements.actions.address.setAddressManually(
 );
 ```
 
+## Buying when a retailer is closed
+
+A same-day retailer whose store schedules delivery can take orders while it is closed. Its fulfillment then carries `deliveryAvailability`. When that says the store cannot deliver now but can schedule (`status: 'available'`, `canSchedule: true`), the retailer card stays on and shows "Schedule delivery". The product page shows no time: the server sends `nextSlot: null` for a closed store, and checkout asks the shopper to choose a delivery window. Add to Cart stays on. Screen readers hear "Columbus Avenue Wines, closed now, schedule delivery" in place of "Currently closed". When the server does send a `nextSlot`, the card adds it on a second line, in the shopper's own time zone ("Schedule delivery", then "Thu, 1 PM – 2 PM") and screen readers hear "…, next arrival Thu, 1 PM – 2 PM". The SDK selects a retailer that can deliver now first, then one that schedules delivery, and goes to shipping only when neither is available.
+
+A closed store without scheduled delivery is blocked as before. An unknown or unavailable `deliveryAvailability`, or a `nextSlot` whose order cutoff has passed, never turns purchase on.
+
 ## Presale Products
 
 Products in presale mode:

package/docs/v1/reference/analytics.md

@@ -10,6 +10,11 @@ This runs entirely inside the SDK. In most cases you do not need to configure or
 
 It coexists with a host site's own GTM — see [Coexisting With Your Own GTM](#coexisting-with-your-own-gtm) below.
 
+The one case that needs code: if **your own UI** renders a step Elements would otherwise render — a
+product page, an address picker, a cart, or a "Proceed to checkout" in front of the checkout-only
+client — Elements never sees it. Report it with `actions.analytics` — see
+[Reporting Steps Your Own UI Renders](#reporting-steps-your-own-ui-renders).
+
 ## Supported Environments
 
 GTM initialization and every event push are enabled in production and staging. When the SDK is running in Builder mode, no container is loaded and no events are sent.
@@ -93,22 +98,23 @@ Every event automatically carries source-tracking fields identifying the tenant
 
 ## Events
 
-All events are GA4-shaped and follow the standard ecommerce schema (`items[]`, `value`, `currency` — the SDK uses `USD`, `coupon`, etc.).
+All events are GA4-shaped and follow the standard ecommerce schema (`items[]`, `value`, `currency` — the SDK uses `USD`, `coupon`, etc.). `search` is the exception: it carries only `search_term`.
 
 ### Standard GA4 ecommerce events
 
 | Event | Fired when |
 | --- | --- |
-| `view_item` | A shopper views a product |
-| `view_item_list` | A shopper views a list of products |
-| `select_item` | A shopper selects a product from a list |
-| `add_to_cart` | A shopper adds an item to the cart |
-| `view_cart` | A shopper views the cart |
-| `remove_from_cart` | A shopper removes an item from the cart |
-| `begin_checkout` | A shopper begins checkout |
-| `add_shipping_info` | Shipping info is added during checkout |
+| `view_item` | A shopper views a product, and again on each size they switch to |
+| `view_item_list` | A product list loads products: its first load, a filtered or searched list, each "load more" |
+| `select_item` | A shopper opens a product from a product list card |
+| `add_to_cart` | A shopper adds an item: from the product component or a list card, `actions.cart.addProduct()` / `actions.checkout.addProduct()`, a cart or checkout quantity increase, or a presale added straight to checkout |
+| `view_cart` | The cart drawer opens with items in it — the cart button, `openCart()` / `toggleCart()`, the checkout's back button — or an add that opens it lands |
+| `remove_from_cart` | A shopper lowers an item's quantity or removes it, in the cart or in the checkout |
+| `begin_checkout` | A shopper begins checkout: the cart's Checkout button (also before its redirect to `checkout.pageUrl`), `actions.checkout.addProduct()`, `openCheckout()` / `toggleCheckout()` opening the drawer, a presale added straight to checkout, or the first wallet tap on express buttons placed on their own |
+| `add_shipping_info` | Shipping info is added during checkout: the customer or gift recipient form is saved, or a wallet (Apple Pay / Google Pay) order hands over the wallet's contact details |
 | `add_payment_info` | Payment info is added during checkout |
 | `purchase` | A purchase completes |
+| `search` | A search typed into the product list's search box runs |
 
 ### Custom events
 
@@ -126,8 +132,45 @@ All events are GA4-shaped and follow the standard ecommerce schema (`items[]`, `
 | `product_size_no_availability` | A selected size has no availability |
 | `product_fulfillment_no_availability` | A selected fulfillment type has no availability |
 
+## Reporting Steps Your Own UI Renders
+
+Elements reports the steps its components render. A host that renders some steps itself reports
+them through `actions.analytics`, on the full client and on the checkout-only client:
+
+| Action | Event |
+| --- | --- |
+| `search(searchTerm)` | `search` |
+| `viewItem(item)` | `view_item` |
+| `viewItemList(items, list?)` | `view_item_list` |
+| `selectItem(item, list?)` | `select_item` |
+| `addToCart(item)` | `add_to_cart` |
+| `removeFromCart(item)` | `remove_from_cart` |
+| `viewCart(items)` | `view_cart` |
+| `beginCheckout(items, { coupon? })` | `begin_checkout` |
+| `addressUpdated(address)` | `address_updated` |
+| `addressFailed(failure)` | `address_failed` |
+| `productNoAvailability(details)` | `product_no_availability` |
+| `productSizeNoAvailability(details)` | `product_size_no_availability` |
+| `productFulfillmentNoAvailability(details)` | `product_fulfillment_no_availability` |
+
+They go through the same pipeline as the SDK's own events — same shape, `tenant_*` fields,
+`send_to` targets, environment gating and queueing — so a report built on Elements events covers
+both. There are no actions for `add_shipping_info`, `add_payment_info`, `purchase` or the promo code
+and gift card events: the Elements checkout reports those itself, and a host reporting them too
+would count every order twice. For the same reason, don't report a step an Elements component
+renders — including `begin_checkout`, which Elements reports from the cart's Checkout button,
+`actions.checkout.addProduct()`, `openCheckout()` / `toggleCheckout()`, a presale, and the first
+wallet tap on express buttons placed on their own.
+
+Malformed input never throws: the event is skipped and a warning logged, so reporting can't break
+the host's page.
+
+Items take prices in cents, as product responses carry them, and send them in dollars. Full
+signatures and examples: [Analytics Actions](../api/actions/analytics-actions.md).
+
 ## Related Docs
 
 - [Events Guide](../guides/events.md)
+- [Analytics Actions](../api/actions/analytics-actions.md)
 - [Client API](../api/client.md)
 - [Troubleshooting](./troubleshooting.md)

package/package.json

@@ -3,7 +3,7 @@
   "description": "LiquidCommerce Elements SDK",
   "license": "UNLICENSED",
   "author": "LiquidCommerce Team",
-  "version": "2.7.44",
+  "version": "2.7.45",
   "homepage": "https://docs.liquidcommerce.co/elements-sdk",
   "repository": {
     "type": "git",