@liquidcommerce/elements-sdk 2.6.0-beta.13 → 2.6.0-beta.131

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

@@ -0,0 +1,920 @@
+# Checkout Component
+
+The Checkout component provides a complete purchase flow including customer information collection, payment processing, and order confirmation.
+
+## Overview
+
+The Checkout component handles:
+- Customer information (email, phone, address)
+- Gift recipient details (optional)
+- Payment processing (Stripe integration)
+- Billing address
+- Promo codes and gift cards
+- Order summary and totals
+- Marketing preferences
+- Tip options
+- Order confirmation
+
+## Basic Usage
+
+### Checkout Drawer (Default)
+
+The checkout drawer opens automatically when users click "Checkout" from the cart. No additional setup required.
+
+### Hosted Checkout Page
+
+For a full-page checkout experience, inject checkout into a dedicated container:
+
+```javascript
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+
+await client.injectCheckoutElement({
+  containerId: 'checkout-container',
+  checkoutId: 'optional_checkout_id',  // Optional: load specific checkout
+  hideHeader: false  // Optional: hide checkout header
+});
+```
+
+#### With URL Parameter
+
+Configure checkout to load from URL parameter:
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-checkout-param="lce_checkout"
+  type="text/javascript"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+></script>
+
+<div data-lce-checkout></div>
+```
+
+Visit `https://yoursite.com/checkout?lce_checkout=checkout_abc123` to load that checkout.
+
+### Redirect to Custom Checkout Page
+
+Configure the cart to redirect to your checkout page instead of opening the drawer:
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  checkout: {
+    pageUrl: 'https://yoursite.com/checkout?lce_checkout={token}'
+  }
+});
+```
+
+Or with data attributes:
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-checkout-url="https://yoursite.com/checkout?lce_checkout={token}"
+  type="text/javascript"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+></script>
+```
+
+The `{token}` placeholder is replaced with the checkout token.
+
+## Checkout Actions
+
+### Open Checkout
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.openCheckout();
+```
+
+### Close Checkout
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.closeCheckout();
+```
+
+### Toggle Checkout
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.toggleCheckout();
+```
+
+### Exit Checkout
+
+Navigate away from checkout (requires `exitUrl` configuration):
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.exitCheckout();
+```
+
+Configure exit URL:
+
+```javascript
+customTheme: {
+  checkout: {
+    layout: {
+      exitUrl: 'https://yoursite.com/shop'
+    }
+  }
+}
+```
+
+### Add Product to Checkout
+
+Skip the cart and go directly to checkout:
+
+```javascript
+await window.LiquidCommerce.elements.actions.checkout.addProduct([
+  {
+    identifier: '00619947000020',
+    fulfillmentType: 'shipping',
+    quantity: 1
+  }
+], true);  // true = open checkout after adding
+```
+
+### Apply Promo Code
+
+```javascript
+await window.LiquidCommerce.elements.actions.checkout.applyPromoCode('WELCOME10');
+```
+
+### Remove Promo Code
+
+```javascript
+await window.LiquidCommerce.elements.actions.checkout.removePromoCode();
+```
+
+### Apply Gift Card
+
+```javascript
+await window.LiquidCommerce.elements.actions.checkout.applyGiftCard('GIFT-1234-5678');
+```
+
+### Remove Gift Card
+
+```javascript
+await window.LiquidCommerce.elements.actions.checkout.removeGiftCard('GIFT-1234-5678');
+```
+
+### Toggle Gift Mode
+
+Enable/disable "Send as Gift" mode:
+
+```javascript
+// Enable gift mode
+await window.LiquidCommerce.elements.actions.checkout.toggleIsGift(true);
+
+// Disable gift mode
+await window.LiquidCommerce.elements.actions.checkout.toggleIsGift(false);
+
+// Toggle current state
+await window.LiquidCommerce.elements.actions.checkout.toggleIsGift();
+```
+
+### Toggle Billing Same As Shipping
+
+```javascript
+// Use shipping address for billing
+await window.LiquidCommerce.elements.actions.checkout.toggleBillingSameAsShipping(true);
+
+// Use different billing address
+await window.LiquidCommerce.elements.actions.checkout.toggleBillingSameAsShipping(false);
+```
+
+### Toggle Marketing Preferences
+
+```javascript
+// Opt into email marketing
+await window.LiquidCommerce.elements.actions.checkout.toggleMarketingPreferences('canEmail', true);
+
+// Opt into SMS marketing
+await window.LiquidCommerce.elements.actions.checkout.toggleMarketingPreferences('canSms', true);
+```
+
+### Update Customer Information
+
+Pre-fill customer information:
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.updateCustomerInfo({
+  firstName: 'John',
+  lastName: 'Doe',
+  email: 'john@example.com',
+  phone: '+15551234567',
+  birthDate: '1990-01-15',
+  addressTwo: 'Apt 4',
+  company: 'Acme Corp'
+});
+```
+
+**Available fields:**
+- `firstName`, `lastName`
+- `email`, `phone`
+- `birthDate`, `addressTwo`
+- `company`
+
+### Update Gift Information
+
+Pre-fill gift recipient information:
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.updateGiftInfo({
+  firstName: 'Jane',
+  lastName: 'Smith',
+  email: 'jane@example.com',
+  phone: '+15559876543',
+  message: 'Happy Birthday!',
+  addressTwo: 'Suite 5B'
+});
+```
+
+**Available fields:**
+- `firstName`, `lastName`
+- `email`, `phone`
+- `message`
+- `addressTwo`
+
+### Update Billing Information
+
+Pre-fill billing address:
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.updateBillingInfo({
+  firstName: 'John',
+  lastName: 'Doe',
+  email: 'john@example.com',
+  phone: '+15551234567',
+  addressOne: '789 Elm St',
+  addressTwo: 'Floor 2',
+  city: 'Chicago',
+  state: 'IL',
+  zipCode: '60601'
+});
+```
+
+**Available fields:**
+- `firstName`, `lastName`
+- `email`, `phone`, `company`
+- `addressOne`, `addressTwo`
+- `city`, `state`, `zipCode`
+
+### Get Checkout Details
+
+```javascript
+const checkoutData = window.LiquidCommerce.elements.actions.checkout.getDetails();
+
+console.log(checkoutData);
+// {
+//   token: 'abc123xyz',
+//   cartId: 'cart_abc123',
+//   items: { 'cart_item_id': { ... } },
+//   amounts: {
+//     subtotal: 9998,
+//     tax: 800,
+//     shipping: 500,
+//     tip: 200,
+//     total: 11498
+//   },
+//   isGift: false,
+//   ...
+// }
+```
+
+### 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
+
+```javascript
+window.addEventListener('lce:actions.checkout_loaded', (event) => {
+  console.log('Checkout loaded');
+});
+
+window.addEventListener('lce:actions.checkout_opened', (event) => {
+  console.log('Checkout opened');
+});
+
+window.addEventListener('lce:actions.checkout_closed', (event) => {
+  console.log('Checkout closed');
+});
+
+window.addEventListener('lce:actions.checkout_failed', (event) => {
+  console.error('Checkout failed:', event.detail.data.message);
+});
+```
+
+### Customer Information
+
+```javascript
+window.addEventListener('lce:actions.checkout_customer_information_updated', (event) => {
+  const { cartId } = event.detail.data;
+  console.log('Customer info updated for cart:', cartId);
+});
+```
+
+### Gift Information
+
+```javascript
+window.addEventListener('lce:actions.checkout_is_gift_toggled', (event) => {
+  const { isActive } = event.detail.data;
+  console.log('Gift mode:', isActive ? 'enabled' : 'disabled');
+});
+
+window.addEventListener('lce:actions.checkout_gift_information_updated', (event) => {
+  console.log('Gift recipient updated');
+});
+```
+
+### Billing Information
+
+```javascript
+window.addEventListener('lce:actions.checkout_billing_same_as_shipping_toggled', (event) => {
+  const { isActive } = event.detail.data;
+  console.log('Billing same as shipping:', isActive);
+});
+
+window.addEventListener('lce:actions.checkout_billing_information_updated', (event) => {
+  console.log('Billing address updated');
+});
+```
+
+### Marketing Preferences
+
+```javascript
+window.addEventListener('lce:actions.checkout_marketing_preferences_toggled', (event) => {
+  const { fieldName, isActive } = event.detail.data;
+  console.log(`Marketing ${fieldName}:`, isActive);
+});
+```
+
+### Items Management
+
+```javascript
+window.addEventListener('lce:actions.checkout_item_removed', (event) => {
+  const { cartItemId } = event.detail.data;
+  console.log('Item removed:', cartItemId);
+});
+
+window.addEventListener('lce:actions.checkout_item_quantity_increase', (event) => {
+  const { cartItemId, quantity } = event.detail.data;
+  console.log(`Item ${cartItemId} quantity: ${quantity}`);
+});
+
+window.addEventListener('lce:actions.checkout_item_quantity_decrease', (event) => {
+  const { cartItemId, quantity } = event.detail.data;
+  console.log(`Item ${cartItemId} quantity: ${quantity}`);
+});
+```
+
+### Delivery Method
+
+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) => {
+  const { fulfillmentType, previousFulfillmentType } = event.detail.data;
+  console.log(`Delivery method: ${previousFulfillmentType} to ${fulfillmentType}`);
+});
+```
+
+### 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
+window.addEventListener('lce:actions.checkout_tip_updated', (event) => {
+  const { deliveryTips } = event.detail.data;
+  const total = deliveryTips.reduce((sum, t) => sum + t.tip, 0);
+  console.log('Tip amount:', total / 100);
+});
+```
+
+### Payment & Submission
+
+```javascript
+window.addEventListener('lce:actions.checkout_submit_started', (event) => {
+  console.log('Processing payment...');
+  // Show loading state
+});
+
+window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
+  const { orderNumber } = event.detail.data;
+  console.log('Order completed:', orderNumber);
+  // Redirect to confirmation page
+});
+
+window.addEventListener('lce:actions.checkout_submit_failed', (event) => {
+  const { message } = event.detail.data;
+  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');
+});
+
+// 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
+
+```javascript
+window.addEventListener('lce:actions.checkout_promo_code_applied', (event) => {
+  const { discount, newTotal } = event.detail.data;
+  console.log(`Promo applied: $${discount / 100} off`);
+});
+
+window.addEventListener('lce:actions.checkout_promo_code_removed', (event) => {
+  console.log('Promo code removed');
+});
+
+window.addEventListener('lce:actions.checkout_promo_code_failed', (event) => {
+  const { error } = event.detail.data;
+  console.error('Promo code failed:', error);
+});
+```
+
+### Gift Cards
+
+```javascript
+window.addEventListener('lce:actions.checkout_gift_card_applied', (event) => {
+  const { newTotal } = event.detail.data;
+  console.log('Gift card applied, new total:', newTotal / 100);
+});
+
+window.addEventListener('lce:actions.checkout_gift_card_removed', (event) => {
+  console.log('Gift card removed');
+});
+
+window.addEventListener('lce:actions.checkout_gift_card_failed', (event) => {
+  const { error } = event.detail.data;
+  console.error('Gift card failed:', error);
+});
+```
+
+### Product Add to Checkout
+
+```javascript
+window.addEventListener('lce:actions.checkout_product_add_success', (event) => {
+  const { itemsAdded, identifiers } = event.detail.data;
+  console.log(`Added ${itemsAdded} items to checkout`);
+});
+
+window.addEventListener('lce:actions.checkout_product_add_failed', (event) => {
+  const { error } = event.detail.data;
+  console.error('Failed to add to checkout:', error);
+});
+```
+
+## California Proposition 65 Warning
+
+When the shipping address is in California, the order summary shows a panel directly above the
+place-order button reading **Adult signature (21+) required at delivery.** followed by
+**CA WARNING · California Proposition 65 information for these products**, so the warning is
+presented before the purchase completes. The text links to the OEHHA alcohol page,
+[www.P65Warnings.ca.gov/alcohol](https://www.p65warnings.ca.gov/alcohol), in a new tab. The full
+27 CCR § 25607.4 text is on the product element.
+
+The panel appears in the drawer checkout, the hosted checkout and the checkout-only build. The
+whole panel, adult-signature notice included, is shown only for a California shipping address; it
+appears or disappears when the address changes, and nothing renders in its place otherwise. Neither can be turned off or reworded by configuration. Its colours follow `global.layout.poweredByMode` — the same
+light/dark switch the Stripe payment form uses — as a fixed pair so the copy is always legible:
+`light` is `#18181B` on `#F5F3EE`, `dark` is `#F5F3EE` on `#2A2824`. The font and corner radius come
+from your theme. If your checkout is dark, set `poweredByMode: 'dark'`.
+
+## Customization
+
+### Theme Configuration
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  customTheme: {
+    checkout: {
+      theme: {
+        backgroundColor: '#ffffff'
+      },
+      layout: {
+        allowGiftCards: true,
+        exitUrl: 'https://yoursite.com/shop',
+        continueShoppingUrl: 'https://yoursite.com/shop',
+        drawerHeaderText: 'Checkout',
+        placeOrderButtonText: 'Complete Purchase'
+      }
+    }
+  }
+});
+```
+
+## Payment Integration
+
+The SDK uses Stripe for payment processing. Payment form is embedded and handles:
+- Credit/debit cards
+- 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 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
+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
+
+1. Customer opens checkout (from cart or direct)
+2. Reviews order summary
+3. Enters shipping information
+4. Enters payment information
+5. Optionally enters billing address
+6. Reviews total (with promo codes, gift cards, tips)
+7. Places order
+8. Sees order confirmation
+
+### Gift Flow
+
+1. Customer enables "Send as Gift"
+2. Enters their billing/payment information
+3. Enters recipient's shipping information
+4. Adds gift message (optional)
+5. Places order
+6. Confirmation shows gift delivery details
+
+## Presale Products
+
+Checkouts with presale items show:
+- Countdown timer for presale expiration
+- Expected delivery date
+- Special handling for presale orders
+
+When presale expires:
+- Shows expiration notice
+- Disables checkout submission
+
+## Best Practices
+
+### Pre-fill Known Information
+
+If you have customer data, pre-fill it:
+
+```javascript
+// After user logs in
+if (userIsLoggedIn) {
+  window.addEventListener('lce:actions.checkout_opened', () => {
+    window.LiquidCommerce.elements.actions.checkout.updateCustomerInfo({
+      firstName: currentUser.firstName,
+      lastName: currentUser.lastName,
+      email: currentUser.email,
+      phone: currentUser.phone
+    });
+  });
+}
+```
+
+### Track Conversion Funnel
+
+```javascript
+const checkoutFunnel = {
+  loaded: false,
+  infoEntered: false,
+  paymentEntered: false,
+  submitted: false
+};
+
+window.addEventListener('lce:actions.checkout_loaded', () => {
+  checkoutFunnel.loaded = true;
+  gtag('event', 'begin_checkout');
+});
+
+window.addEventListener('lce:actions.checkout_customer_information_updated', () => {
+  if (!checkoutFunnel.infoEntered) {
+    checkoutFunnel.infoEntered = true;
+    gtag('event', 'checkout_progress', { step: 'customer_info' });
+  }
+});
+
+window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
+  gtag('event', 'purchase', {
+    transaction_id: event.detail.data.orderNumber,
+    value: event.detail.data.orderTotal / 100,
+    currency: 'USD'
+  });
+});
+```
+
+### Handle Submission States
+
+```javascript
+window.addEventListener('lce:actions.checkout_submit_started', () => {
+  // Disable navigation
+  window.onbeforeunload = () => 'Payment in progress...';
+  
+  // Show loading overlay
+  showGlobalLoadingOverlay('Processing your order...');
+});
+
+window.addEventListener('lce:actions.checkout_submit_completed', () => {
+  // Re-enable navigation
+  window.onbeforeunload = null;
+  
+  // Redirect to confirmation
+  window.location.href = '/order-confirmation';
+});
+
+window.addEventListener('lce:actions.checkout_submit_failed', () => {
+  // Re-enable navigation
+  window.onbeforeunload = null;
+  
+  // Hide loading
+  hideGlobalLoadingOverlay();
+});
+```
+
+## Configuration Options
+
+### Enable/Disable Features
+
+```javascript
+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
+      text: 'Subscribe to our newsletter'
+    },
+    smsOptIn: {
+      show: false,             // Hide SMS opt-in checkbox
+      checked: false,          // Default unchecked
+      text: 'Receive SMS updates'
+    }
+  }
+}
+```
+
+### Button Text
+
+```javascript
+checkout: {
+  layout: {
+    placeOrderButtonText: 'Complete Purchase'
+  }
+}
+```
+
+## Troubleshooting
+
+### Checkout Not Opening
+
+1. Verify cart has items: `window.LiquidCommerce.elements.actions.cart.getDetails()`
+2. Check for JavaScript errors in console
+3. Ensure SDK is initialized: `window.LiquidCommerce.elements`
+4. Try manually: `window.LiquidCommerce.elements.actions.checkout.openCheckout()`
+
+### 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 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
+
+1. Verify you're calling `updateCustomerInfo()` after checkout loads
+2. Check field names match exactly (case-sensitive)
+3. Ensure values are strings, not other types
+4. Listen for checkout_opened event before updating
+
+### Order Submission Failing
+
+1. Check all required fields are filled
+2. Verify payment information is valid
+3. Look for validation errors in UI
+4. Check console for detailed error messages
+5. Ensure products are still available
+
+## See Also
+
+- [Cart Component](./cart-component.md) - Shopping cart functionality
+- [Actions API](../api/actions/checkout-actions.md) - Checkout actions reference
+- [Events](./events.md) - All available events
+- [Theming](./theming.md) - Customize appearance
+
+### 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). 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.
+
+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.
+
+## 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 "As soon as possible" 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 in the retailer's time zone, named once above the list ("Times in Eastern Time"). The window list scrolls inside the dialog and keeps the chosen window in view. The first window shows "Order by" with its cutoff, and **As soon as possible** sits next to it when the store can deliver now. 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, Oct 8, 1 PM – 2 PM ET"), and on the thank-you page as "Delivery time" with "Thu, Oct 8, 1 PM – 2 PM ET". 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; when it names none and the SDK cannot place it, every saved window is cleared. 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, Oct 8, 1 PM – 2 PM ET"), 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 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.