@liquidcommerce/elements-sdk 2.6.0-beta.11 → 2.6.0-beta.111

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

@@ -0,0 +1,527 @@
+# Checkout Actions API
+
+Checkout actions allow you to programmatically control the checkout flow.
+
+## Navigation Actions
+
+> **Note:** `openCheckout()`, `closeCheckout()`, and `toggleCheckout()` are only available on the full `Elements()` client's `actions.checkout`. They are **not** present on the checkout-only client (`ElementsCheckout()`), whose `actions.checkout` is typed `IElementsCheckoutActions = Omit<ICheckoutActions, 'openCheckout' | 'closeCheckout' | 'toggleCheckout'>`. The remaining checkout actions are available on both clients.
+
+### actions.checkout.openCheckout()
+
+```typescript
+openCheckout(): void
+```
+
+Opens the checkout drawer or navigates to checkout page.
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.openCheckout();
+```
+
+### actions.checkout.closeCheckout()
+
+```typescript
+closeCheckout(): void
+```
+
+Closes the checkout drawer.
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.closeCheckout();
+```
+
+### actions.checkout.toggleCheckout()
+
+```typescript
+toggleCheckout(): void
+```
+
+Toggles checkout open/closed.
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.toggleCheckout();
+```
+
+### actions.checkout.exitCheckout()
+
+```typescript
+exitCheckout(): void
+```
+
+Navigates away from checkout (requires `exitUrl` configuration).
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.exitCheckout();
+```
+
+## Product Actions
+
+### actions.checkout.addProduct()
+
+```typescript
+addProduct(params: IAddProductParams[], openCheckout?: boolean): Promise<void>
+```
+
+Add products and open checkout in one call. Products are added to the cart (via the cart action, or directly when none is wired up), then checkout is prepared and opened. For a checkout without a cart session, use `addAnonymousProduct`.
+
+`IAddProductParams.engravingLines?: string[]` — optional engraving. Same rules as [`actions.cart.addProduct()`](./cart-actions.md#actionscartaddproduct): invalid input is ignored, blanks stripped, lines clamped to the product's `maxLines` / `maxCharsPerLine`, and engraving is dropped (without failing) when the product, variant, or fulfillment doesn't support it.
+
+```javascript
+await window.LiquidCommerce.elements.actions.checkout.addProduct([
+  {
+    identifier: '00619947000020',
+    fulfillmentType: 'shipping',
+    quantity: 1
+  }
+], true);  // Open checkout after adding
+
+// With engraving
+await window.LiquidCommerce.elements.actions.checkout.addProduct([
+  {
+    identifier: '00619947000020',
+    fulfillmentType: 'shipping',
+    quantity: 1,
+    engravingLines: ['For Dad']
+  }
+], true);
+```
+
+### actions.checkout.addAnonymousProduct()
+
+```typescript
+addAnonymousProduct(
+  params: IAnonymousCheckoutAddProductParams
+): Promise<IAnonymousCheckoutAddProductResponse>
+```
+
+Add a product to checkout without requiring a cart session. Used for direct-to-checkout flows.
+
+**Parameters** (`IAnonymousCheckoutAddProductParams`):
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `location` | `ILocation` | Yes | `{ address: IAddressAddress; coordinates: IAddressCoordinates }` |
+| `items` | `IAnonymousCheckoutAddProductItem[]` | No | Products to add: `{ identifier, fulfillmentType, quantity }`. Provide `items` **or** `cartItems`. |
+| `cartItems` | `ICartUpdateItem[]` | No | Pre-resolved cart line items: `{ id?, partNumber, quantity, fulfillmentId, engravingLines? }` (alternative to `items`). |
+| `promoCode` | `string` | No | Promo code applied while creating the anonymous checkout. |
+
+```javascript
+const result = await window.LiquidCommerce.elements.actions.checkout
+  .addAnonymousProduct({
+    items: [
+      { identifier: '00619947000020', fulfillmentType: 'shipping', quantity: 1 }
+    ],
+    location: {
+      address: { one: '123 Main St', two: '', city: 'New York', state: 'NY', zip: '10001', country: 'US' },
+      coordinates: { latitude: 40.7128, longitude: -74.006 }
+    },
+    promoCode: 'WELCOME10'  // optional
+  });
+```
+
+**Returns** (`IAnonymousCheckoutAddProductResponse`):
+
+```typescript
+interface IAnonymousCheckoutAddProductResponse {
+  checkout: ICheckoutPrepare | null;        // the prepared checkout (see below), or null on failure
+  unavailableItems: IAnonymousCheckoutUnavailableItem[];
+}
+
+interface IAnonymousCheckoutUnavailableItem {
+  identifier: string;
+  productName: string | null;
+  fulfillmentType: FulfillmentType;         // 'shipping' | 'onDemand'
+  reason: 'product_not_available' | 'fulfillment_not_available';
+}
+
+interface ICheckoutPrepare {
+  token: string;
+  cartId: string;
+  customer: ICheckoutCustomer;
+  isGift: boolean;
+  billingSameAsShipping: boolean;
+  payment?: string;
+  giftOptions: ICheckoutGiftRecipient;
+  marketingPreferences: ICheckoutMarketingPreferences;
+  shippingAddress: ICheckoutShippingAddress;
+  billingAddress: ICheckoutBilling;
+  promoCode: ICheckoutPromoCode | null;
+  amounts: ICheckoutAmounts;
+  giftCards: ICheckoutGiftCard[];
+  presale: ICheckoutPresale | null;
+  itemsQuantity: number;
+  items: Record<string /* cart item ID */, ICheckoutItem>;
+  retailers: Record<string /* retailer ID */, ICheckoutRetailer>;
+  events: ICheckoutEvent[];
+}
+```
+
+## Promo & Gift Card Actions
+
+### actions.checkout.applyPromoCode()
+
+```typescript
+applyPromoCode(promoCode: string): Promise<void>
+```
+
+Apply a promo code during checkout.
+
+```javascript
+await window.LiquidCommerce.elements.actions.checkout.applyPromoCode('WELCOME10');
+```
+
+### actions.checkout.removePromoCode()
+
+```typescript
+removePromoCode(): Promise<void>
+```
+
+Remove the active promo code.
+
+```javascript
+await window.LiquidCommerce.elements.actions.checkout.removePromoCode();
+```
+
+### actions.checkout.applyGiftCard()
+
+```typescript
+applyGiftCard(code: string): Promise<void>
+```
+
+Apply a gift card.
+
+```javascript
+await window.LiquidCommerce.elements.actions.checkout.applyGiftCard('GIFT-1234-5678-9012');
+```
+
+### actions.checkout.removeGiftCard()
+
+```typescript
+removeGiftCard(code: string): Promise<void>
+```
+
+Remove a gift card.
+
+```javascript
+await window.LiquidCommerce.elements.actions.checkout.removeGiftCard('GIFT-1234-5678-9012');
+```
+
+## Toggle Actions
+
+### actions.checkout.toggleIsGift()
+
+```typescript
+toggleIsGift(active?: boolean): Promise<void>
+```
+
+Enable/disable gift mode.
+
+```javascript
+// Enable
+await window.LiquidCommerce.elements.actions.checkout.toggleIsGift(true);
+
+// Disable
+await window.LiquidCommerce.elements.actions.checkout.toggleIsGift(false);
+
+// Toggle
+await window.LiquidCommerce.elements.actions.checkout.toggleIsGift();
+```
+
+### actions.checkout.toggleBillingSameAsShipping()
+
+```typescript
+toggleBillingSameAsShipping(active?: boolean): Promise<void>
+```
+
+Set whether billing address matches 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);
+```
+
+### actions.checkout.toggleMarketingPreferences()
+
+```typescript
+toggleMarketingPreferences(field: 'canEmail' | 'canSms', active: boolean): Promise<void>
+```
+
+Set marketing opt-in 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);
+```
+
+## Form Update Actions
+
+### actions.checkout.updateCustomerInfo()
+
+```typescript
+updateCustomerInfo(params: Record<CustomerFieldName, string>): void
+```
+
+Pre-fill customer information.
+
+**Available fields:**
+- `firstName`, `lastName`
+- `email`, `phone`
+- `birthDate`, `addressTwo`
+- `company`
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.updateCustomerInfo({
+  firstName: 'John',
+  lastName: 'Doe',
+  email: 'john@example.com',
+  phone: '+15551234567',
+  birthDate: '1990-01-01',
+  addressTwo: 'Apt 4B',
+  company: 'Acme Corp'
+});
+```
+
+### actions.checkout.updateBillingInfo()
+
+```typescript
+updateBillingInfo(params: Record<BillingFieldName, string>): void
+```
+
+Pre-fill billing address.
+
+**Available fields:**
+- `firstName`, `lastName`
+- `email`, `phone`, `company`
+- `addressOne`, `addressTwo`
+- `city`, `state`, `zipCode`
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.updateBillingInfo({
+  firstName: 'John',
+  lastName: 'Doe',
+  email: 'john@example.com',
+  phone: '+15551234567',
+  company: 'Acme Corp',
+  addressOne: '123 Main St',
+  addressTwo: 'Apt 4B',
+  city: 'New York',
+  state: 'NY',
+  zipCode: '10001'
+});
+```
+
+### actions.checkout.updateGiftInfo()
+
+```typescript
+updateGiftInfo(params: Record<GiftFieldName, string>): void
+```
+
+Pre-fill gift recipient information.
+
+**Available fields:**
+- `firstName`, `lastName`
+- `email`, `phone`
+- `message`, `addressTwo`
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.updateGiftInfo({
+  firstName: 'Jane',
+  lastName: 'Smith',
+  email: 'jane@example.com',
+  phone: '+15559876543',
+  addressTwo: 'Suite 200',
+  message: 'Happy Birthday!',
+});
+```
+
+## Payment Method
+
+### actions.checkout.setSavedPaymentMethod()
+
+```typescript
+setSavedPaymentMethod(params: {
+  id: string;
+  card: {
+    brand: string;
+    last4: string;
+    expMonth?: string | number;
+    expYear?: string | number;
+  };
+}): void
+```
+
+Pre-select a saved payment method for the checkout. When set, the payment step renders a read-only card summary (e.g. `Visa ending in 4242`) instead of the Stripe card form, and the shopper places the order without re-entering card details. The `id` is bound to the checkout when the payment form is saved.
+
+`id` must be a payment method the backend already holds for the checkout's customer (for example, a card fetched server-side and handed to the page). If the backend does not recognize the `id` for this checkout's customer, saving the payment step fails with an error (`The selected payment method could not be applied to this checkout.`) and the order cannot be placed — pass only a payment method confirmed to belong to the customer. The `card` fields are used only to render the summary. It can be set at any time — before opening checkout, or while it is open — and the payment step updates accordingly. The selection persists across a cart reset within the session.
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.setSavedPaymentMethod({
+  id: 'pm_123',
+  card: { brand: 'Visa', last4: '4242', expMonth: '12', expYear: '30' }
+});
+```
+
+### actions.checkout.clearSavedPaymentMethod()
+
+```typescript
+clearSavedPaymentMethod(): void
+```
+
+Remove a previously set saved payment method, restoring the Stripe card-entry form.
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.clearSavedPaymentMethod();
+```
+
+## Data Retrieval
+
+### actions.checkout.getDetails()
+
+```typescript
+getDetails(): ICheckoutDetailsEventData
+```
+
+Retrieve current checkout information.
+
+```javascript
+const checkout = window.LiquidCommerce.elements.actions.checkout.getDetails();
+
+console.log(`Cart ID: ${checkout.cartId}`);
+console.log(`Total: $${checkout.amounts.total / 100}`);
+console.log(`Items: ${checkout.itemCount}`);
+console.log(`Is Gift: ${checkout.isGift}`);
+```
+
+**Returns:**
+
+```typescript
+interface ICheckoutDetailsEventData {
+  token: string;
+  cartId: string;
+  isGift: boolean;
+  billingSameAsShipping: boolean;
+  marketingPreferences: {
+    canEmail: boolean;
+    canSms: boolean;
+  };
+  hasPromoCode: boolean;
+  hasGiftCards: boolean;
+  amounts: ICheckoutAmounts;
+  itemCount: number;
+  items: Record<string, ICheckoutItem>;
+}
+```
+
+### actions.checkout.getProductAvailabilityByState()
+
+```typescript
+getProductAvailabilityByState(
+  identifiers: string[],
+  state?: string
+): Promise<IProductAvailabilityResponse>
+```
+
+Check product availability across states from the checkout context.
+
+```javascript
+const availability = await window.LiquidCommerce.elements.actions.checkout
+  .getProductAvailabilityByState(['00619947000020'], 'CA');
+```
+
+| Parameter     | Type     | Required | Description                          |
+|---------------|----------|----------|--------------------------------------|
+| `identifiers` | string[] | Yes      | Array of product UPCs, SKUs, or IDs  |
+| `state`       | string   | No       | Two-letter state code (e.g., `'NY'`) |
+
+## Use Cases
+
+### Pre-fill for Logged-In Users
+
+```javascript
+window.addEventListener('lce:actions.checkout_opened', () => {
+  if (userIsLoggedIn) {
+    window.LiquidCommerce.elements.actions.checkout.updateCustomerInfo({
+      firstName: currentUser.firstName,
+      lastName: currentUser.lastName,
+      email: currentUser.email,
+      phone: currentUser.phone
+    });
+  }
+});
+```
+
+### Track Checkout Progress
+
+```javascript
+window.addEventListener('lce:actions.checkout_customer_information_updated', () => {
+  gtag('event', 'checkout_progress', { step: 'customer_info' });
+});
+
+window.addEventListener('lce:actions.checkout_submit_started', () => {
+  gtag('event', 'checkout_progress', { step: 'payment' });
+});
+
+window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
+  const { orderNumber, orderTotal } = event.detail.data;
+  
+  gtag('event', 'purchase', {
+    transaction_id: orderNumber,
+    value: orderTotal / 100,
+    currency: 'USD'
+  });
+});
+```
+
+### Gift Flow
+
+```javascript
+document.getElementById('gift-checkbox').addEventListener('change', async (e) => {
+  await window.LiquidCommerce.elements.actions.checkout.toggleIsGift(e.target.checked);
+  
+  if (e.target.checked) {
+    showGiftForm();
+  } else {
+    hideGiftForm();
+  }
+});
+```
+
+### Auto-Apply Campaign Codes
+
+```javascript
+const params = new URLSearchParams(window.location.search);
+const campaignCode = params.get('promo');
+
+if (campaignCode) {
+  window.addEventListener('lce:actions.checkout_opened', async () => {
+    try {
+      await window.LiquidCommerce.elements.actions.checkout.applyPromoCode(campaignCode);
+    } catch (error) {
+      console.log('Invalid campaign code');
+    }
+  });
+}
+```
+
+## Events
+
+Checkout actions trigger numerous events. See [Checkout Events](../../guides/events.md#checkout-events) for complete list.
+
+Key events:
+- `checkout_opened`, `checkout_closed`
+- `checkout_customer_information_updated`
+- `checkout_submit_started`, `checkout_submit_completed`, `checkout_submit_failed`
+- `checkout_promo_code_applied`, `checkout_promo_code_failed`
+- `checkout_gift_card_applied`, `checkout_gift_card_failed`
+
+## See Also
+
+- [Checkout Component Guide](../../guides/checkout-component.md)
+- [Checkout Events](../../guides/events.md#checkout-events)
+- [Cart Actions](./cart-actions.md)