@liquidcommerce/elements-sdk 2.6.0-beta.119 → 2.6.0-beta.120

package/docs/v1/guides/accessibility.md

@@ -105,6 +105,7 @@ 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. …" |
 | 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" |
@@ -163,6 +164,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

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

@@ -402,6 +402,16 @@ window.addEventListener('lce:actions.checkout_submit_failed', (event) => {
 });
 ```
 
+### 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
 
 ```javascript
@@ -496,13 +506,63 @@ 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.
 
+### 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 +683,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
@@ -691,7 +752,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

@@ -858,6 +858,25 @@ 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_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',

package/docs/v1/reference/analytics.md

@@ -52,7 +52,17 @@ The SDK detects an already-present partner/host GTM container rather than replac
 
 ### Google tag gateway
 
-If your site loads its own GTM container first-party through [Google tag gateway for advertisers](https://developers.google.com/tag-platform/tag-manager/gateway/get-started) (e.g. `https://www.yoursite.com/metrics/` instead of `https://www.googletagmanager.com/gtm.js?id=GTM-XXXX`), tell the SDK where that path is so it recognizes your container:
+[Google tag gateway for advertisers](https://developers.google.com/tag-platform/tag-manager/gateway/get-started) serves your Google tags from your own domain instead of Google's. Your GTM container loads from a first-party path such as `https://www.yoursite.com/metrics/` instead of `https://www.googletagmanager.com/gtm.js?id=GTM-XXXX`, and its measurement requests (e.g. GA4 `/g/collect` hits) go out through that same path. Your CDN or load balancer forwards them to Google, so they are less likely to be blocked than requests to Google's domains.
+
+#### How the SDK works with it
+
+- The SDK pushes every event to the page's `window.dataLayer`. Your container reads that same `dataLayer`, so it receives SDK events whether it loads from Google or from your gateway. Keep the default `dataLayer` name: a container renamed with `&l=` never sees them.
+- The SDK never loads your container and proxies nothing. The LiquidCommerce container still loads from `googletagmanager.com`.
+- To send SDK events to your own GA4 property, add a Custom Event trigger in your container on the [event names](#events) below and a GA4 Event tag that fires on it. The SDK puts `items`, `value` and `currency` at the top level of each event, not inside an `ecommerce` object, so map them with Data Layer Variables rather than the GA4 tag's "Send Ecommerce data" option.
+
+#### `gatewayUrl`
+
+Tell the SDK your gateway path so it can recognize your container:
 
 ```javascript
 const client = await Elements('YOUR_API_KEY', {
@@ -62,7 +72,9 @@ const client = await Elements('YOUR_API_KEY', {
 
 Or declaratively, on the script tag: `data-gtm-gateway-url="/metrics/"`.
 
-A gateway script URL usually carries no container ID, so without this setting the SDK cannot match the script tag to your partner container. A script with the same origin whose path starts with that value is matched to your partner container by container ID: an `id=` query parameter must equal your partner container ID, and a script without one counts only once GTM's `window.google_tag_manager` registry lists your container ID (or while no container has booted yet). A gateway serving a different container or a GA4/Ads tag is therefore never taken for yours. Relative values resolve against the current page. The setting affects detection only — the SDK never loads your container, and the LiquidCommerce container still loads from `googletagmanager.com`.
+A gateway script URL usually carries no container ID, so until GTM has booted your container this setting is the only way the SDK can match the script tag to it. Once matched, your container ID is added to each event's `send_to` targets. The setting is optional: events reach your container through `dataLayer` without it.
+
+A script with the same origin whose path starts with that value is matched to your partner container by container ID: an `id=` query parameter must equal your partner container ID, and a script without one counts only once GTM's `window.google_tag_manager` registry lists your container ID (or while no container has booted yet). A gateway serving a different container or a GA4/Ads tag is therefore never taken for yours. Relative values resolve against the current page.
 
 When both the LiquidCommerce container and a partner container are initialized, events are sent to both using GA4's `send_to` targeting (a dual-container send). Only containers that are actually initialized are added to `send_to`, so events are never routed to a container that failed to load.
 

package/package.json

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