@liquidcommerce/elements-sdk 2.6.0-beta.37 → 2.6.0-beta.39

package/docs/checkout.md

@@ -0,0 +1,420 @@
+# Checkout
+
+The checkout component handles the complete purchase flow - collecting customer information, processing payments, and showing order confirmation. It can run as a slide-out drawer from the cart or as a standalone hosted page.
+
+## Overview
+
+The checkout element guides customers through:
+- Contact information collection
+- Delivery address confirmation
+- Payment processing (via Stripe)
+- Promo codes and gift cards
+- Gift options and messaging
+- Marketing opt-ins
+- Age verification
+- Order confirmation
+
+After a successful purchase, customers see a confirmation screen with their order details.
+
+---
+
+## Declarative Setup (HTML Attributes)
+
+### Default Drawer Checkout
+
+By default, checkout opens as a drawer when customers click "Checkout" from the cart. No additional configuration needed.
+
+### Hosted Checkout (External Page)
+
+Redirect to a dedicated checkout page instead of using the drawer:
+
+```html
+<script
+  defer
+  type="text/javascript"
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-checkout-url="https://yoursite.com/checkout"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+When customers click "Checkout", they're redirected to your checkout URL with a checkout token.
+
+### Checkout-Only Page
+
+For dedicated checkout pages, use the checkout-only build:
+
+```html
+<div id="checkout-container"></div>
+
+<script
+  defer
+  type="text/javascript"
+  data-liquid-commerce-checkout
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-container="checkout-container"
+  src="https://assets-elements.liquidcommerce.us/checkout/elements.js"
+></script>
+```
+
+This lighter build only includes checkout components, reducing bundle size for dedicated checkout pages.
+
+---
+
+## Programmatic Setup (JavaScript API)
+
+Inject the checkout element for maximum control.
+
+### Basic Injection
+
+```javascript
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+
+const component = await client.injectCheckoutElement({
+  containerId: 'checkout-container'
+});
+```
+
+### With Options
+
+```javascript
+const component = await client.injectCheckoutElement({
+  containerId: 'checkout-container',
+  checkoutId: 'chk_abc123',  // Load a specific checkout session
+  hideHeader: true            // Hide header for embedded checkout
+});
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `containerId` | string | Yes | ID of the container element |
+| `checkoutId` | string | No | Checkout token to resume a session |
+| `hideHeader` | boolean | No | Hide the checkout header |
+
+### TypeScript Types
+
+For TypeScript users, import types directly from the package:
+
+```typescript
+import type {
+  ILiquidCommerceElementsClient,
+  ILiquidCommerceElementsConfig,
+  IAddProductParams,
+  ICheckoutActions
+} from '@liquidcommerce/elements-sdk';
+```
+
+### Checkout-Only Build (NPM)
+
+For dedicated checkout pages with smaller bundle:
+
+```javascript
+import { ElementsCheckout } from '@liquidcommerce/elements-sdk/checkout';
+
+const client = await ElementsCheckout('YOUR_API_KEY', { env: 'production' });
+await client.injectCheckoutElement({ containerId: 'checkout-container' });
+```
+
+---
+
+## Actions
+
+Control checkout behavior and pre-fill customer data.
+
+### Open / Close / Toggle
+
+```javascript
+// Open checkout drawer
+window.elements.actions.checkout.openCheckout();
+
+// Close checkout drawer
+window.elements.actions.checkout.closeCheckout();
+
+// Toggle checkout drawer
+window.elements.actions.checkout.toggleCheckout();
+
+// Navigate to exit URL (for hosted checkout)
+window.elements.actions.checkout.exitCheckout();
+```
+
+### Add Products Directly to Checkout
+
+Skip the cart and go straight to checkout:
+
+```javascript
+await window.elements.actions.checkout.addProduct(
+  [
+    {
+      identifier: '00619947000020',
+      fulfillmentType: 'shipping',
+      quantity: 1
+    }
+  ],
+  true // Open checkout after adding
+);
+```
+
+### Promo Codes
+
+```javascript
+// Apply promo code
+await window.elements.actions.checkout.applyPromoCode('SAVE10');
+
+// Remove promo code
+await window.elements.actions.checkout.removePromoCode();
+```
+
+### Gift Cards
+
+```javascript
+// Apply gift card
+await window.elements.actions.checkout.applyGiftCard('GIFT-XXXX-XXXX');
+
+// Remove gift card
+await window.elements.actions.checkout.removeGiftCard('GIFT-XXXX-XXXX');
+```
+
+### Form Controls
+
+Pre-fill or toggle checkout form options:
+
+```javascript
+// Toggle gift mode
+await window.elements.actions.checkout.toggleIsGift(true);
+
+// Use shipping address for billing
+await window.elements.actions.checkout.toggleBillingSameAsShipping(true);
+
+// Set marketing preferences
+await window.elements.actions.checkout.toggleMarketingPreferences('canEmail', true);
+await window.elements.actions.checkout.toggleMarketingPreferences('canSms', false);
+```
+
+### Pre-fill Customer Information
+
+Pre-fill forms for logged-in customers:
+
+```javascript
+// Customer contact info
+window.elements.actions.checkout.updateCustomerInfo({
+  firstName: 'John',
+  lastName: 'Doe',
+  email: 'john@example.com',
+  phone: '555-123-4567'
+});
+
+// Billing address (if different from shipping)
+window.elements.actions.checkout.updateBillingInfo({
+  firstName: 'John',
+  lastName: 'Doe',
+  street1: '123 Billing St',
+  city: 'New York',
+  state: 'NY',
+  zipCode: '10001'
+});
+
+// Gift recipient info
+window.elements.actions.checkout.updateGiftInfo({
+  recipientName: 'Jane Smith',
+  senderName: 'John Doe',
+  giftMessage: 'Happy Birthday!'
+});
+```
+
+### Get Checkout Details
+
+Retrieve current checkout state:
+
+```javascript
+const checkout = window.elements.actions.checkout.getDetails();
+
+console.log(checkout.subtotal);
+console.log(checkout.total);
+console.log(checkout.items);
+```
+
+---
+
+## Events
+
+Track checkout progress and handle completion.
+
+### Subscribing to Events
+
+```javascript
+window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
+  const { orderNumber, orderTotal } = event.detail.data;
+  console.log('Order placed:', orderNumber);
+});
+```
+
+### Lifecycle Events
+
+| Event | Description | Key Data |
+|-------|-------------|----------|
+| `checkout_loaded` | Checkout ready | Full checkout state |
+| `checkout_opened` | Drawer opened | boolean |
+| `checkout_closed` | Drawer closed | boolean |
+| `checkout_failed` | Operation failed | message |
+
+### Form Events
+
+| Event | Description | Key Data |
+|-------|-------------|----------|
+| `checkout_customer_information_updated` | Customer form filled | cartId (data is secure) |
+| `checkout_billing_information_updated` | Billing form filled | cartId (data is secure) |
+| `checkout_gift_information_updated` | Gift form filled | cartId (data is secure) |
+| `checkout_is_gift_toggled` | Gift option changed | cartId, isActive |
+| `checkout_billing_same_as_shipping_toggled` | Address option changed | cartId, isActive |
+| `checkout_marketing_preferences_toggled` | Opt-in changed | cartId, fieldName, isActive |
+
+**Note:** Form update events only indicate completion status, not actual customer data (for security).
+
+### Item Events
+
+| Event | Description | Key Data |
+|-------|-------------|----------|
+| `checkout_item_removed` | Item removed | cartId, cartItemId |
+| `checkout_item_quantity_increase` | Quantity increased | cartId, cartItemId, quantity |
+| `checkout_item_quantity_decrease` | Quantity decreased | cartId, cartItemId, quantity |
+| `checkout_item_engraving_updated` | Personalization changed | cartId, cartItemId, engravingLines |
+| `checkout_tip_updated` | Delivery tip changed | cartId, deliveryTips |
+
+### Submit Events
+
+| Event | Description | Key Data |
+|-------|-------------|----------|
+| `checkout_submit_started` | Payment processing | started: boolean |
+| `checkout_submit_completed` | Order placed | orderNumber, orderTotal |
+| `checkout_submit_failed` | Order failed | message |
+
+### Discount Events
+
+| Event | Description | Key Data |
+|-------|-------------|----------|
+| `checkout_promo_code_applied` | Discount applied | cartId, discount, newTotal |
+| `checkout_promo_code_removed` | Discount removed | cartId, newTotal |
+| `checkout_promo_code_failed` | Discount rejected | cartId, error |
+| `checkout_gift_card_applied` | Gift card applied | cartId, newTotal |
+| `checkout_gift_card_removed` | Gift card removed | cartId, newTotal |
+| `checkout_gift_card_failed` | Gift card rejected | cartId, error |
+
+### Product Events
+
+| Event | Description | Key Data |
+|-------|-------------|----------|
+| `checkout_product_add_success` | Programmatic add succeeded | cartId, itemsAdded, identifiers |
+| `checkout_product_add_failed` | Programmatic add failed | cartId, identifiers, error |
+
+### Example: Order Completion Tracking
+
+```javascript
+// Track successful orders
+window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
+  const { orderNumber, orderTotal } = event.detail.data;
+
+  // Send to analytics
+  analytics.track('Order Completed', {
+    orderId: orderNumber,
+    revenue: orderTotal
+  });
+
+  // Redirect to thank you page
+  window.location.href = `/thank-you?order=${orderNumber}`;
+});
+
+// Track failed orders
+window.addEventListener('lce:actions.checkout_submit_failed', (event) => {
+  analytics.track('Checkout Failed', {
+    error: event.detail.data.message
+  });
+});
+```
+
+---
+
+## Use Cases
+
+### Express Checkout for Returning Customers
+
+Pre-fill everything for logged-in users:
+
+```javascript
+// When user reaches checkout and is logged in
+if (currentUser) {
+  window.elements.actions.checkout.updateCustomerInfo({
+    firstName: currentUser.firstName,
+    lastName: currentUser.lastName,
+    email: currentUser.email,
+    phone: currentUser.phone
+  });
+
+  // Enable billing same as shipping by default
+  await window.elements.actions.checkout.toggleBillingSameAsShipping(true);
+}
+```
+
+### Skip Cart Flow
+
+Go directly from product page to checkout:
+
+```javascript
+document.querySelector('#buy-now').addEventListener('click', async () => {
+  await window.elements.actions.checkout.addProduct([
+    {
+      identifier: currentProductId,
+      fulfillmentType: selectedFulfillment,
+      quantity: selectedQuantity
+    }
+  ], true); // Opens checkout immediately
+});
+```
+
+### Auto-Apply Best Discount
+
+```javascript
+// Check for URL promo or user's best available code
+const promoCode = urlParams.get('promo') || currentUser?.bestPromoCode;
+
+if (promoCode) {
+  window.addEventListener('lce:actions.checkout_loaded', async () => {
+    await window.elements.actions.checkout.applyPromoCode(promoCode);
+  });
+}
+```
+
+---
+
+## Customization
+
+Style checkout through theme configuration.
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  customTheme: {
+    checkout: {
+      // Checkout-specific theme options
+    }
+  }
+});
+```
+
+See [theming.md](./theming.md) for available checkout theme options including:
+- Form field styling
+- Button colors
+- Completion screen customization
+- Layout options
+
+---
+
+## See Also
+
+- [Cart](./cart.md) - Shopping cart component
+- [Actions Reference](./actions.md) - All available actions
+- [Events Reference](./events.md) - All available events
+- [Theming Guide](./theming.md) - Customization options