@liquidcommerce/elements-sdk 2.6.0-beta.12 → 2.6.0-beta.121

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

@@ -0,0 +1,817 @@
+# 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,
+//   ...
+// }
+```
+
+## 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.
+
+```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
+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
+});
+```
+
+### 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
+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.
+
+### 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
+
+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
+
+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
+
+### 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.