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

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

@@ -0,0 +1,586 @@
+# 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>, options?: { saveIfValid?: boolean }): Promise<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)
+
+### 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.