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

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

@@ -0,0 +1,629 @@
+# 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. Reports `begin_checkout` for the cart's items
+to GTM, as the cart's own Checkout button does, unless the drawer already shows the checkout.
+
+```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. Opening it reports `begin_checkout`, as `openCheckout()` does.
+
+```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`.
+
+Reports `add_to_cart` for the added products and then `begin_checkout` for the cart to GTM, so don't report either again with [`actions.analytics`](./analytics-actions.md).
+
+`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 {
+  deliveryScheduling: Record<string, CheckoutDeliveryScheduling>; // keyed by fulfillment ID; empty without scheduled delivery
+  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'`) |
+
+## Delivery scheduling actions
+
+Available on both `Elements()` and `ElementsCheckout()` when a checkout fulfillment carries `deliveryScheduling` (an AccelPay retailer with scheduled delivery turned on). Checkouts without it keep their usual behaviour, and `getDetails().deliveryScheduling` is an empty map.
+
+### `actions.checkout.loadDeliverySlots(fulfillmentId)`
+
+```typescript
+loadDeliverySlots(fulfillmentId: string): Promise<DeliverySlot[]>
+```
+
+Loads the full list of delivery windows for one fulfillment. Checkout prepare returns the list only on request, so outside this call `deliveryScheduling.slots` is empty and `availability.nextSlot` names the first window. The call sends the whole current checkout to prepare, plus `deliverySlotsFulfillmentId`, and resolves with the windows that can still be ordered. Each window's `cutoff` is the latest time to place the order for it ("Order by"). Show times in `availability.timezone`.
+
+### `actions.checkout.chooseDeliverySlot(fulfillmentId, slotId)`
+
+```typescript
+chooseDeliverySlot(fulfillmentId: string, slotId: string | null): Promise<void>
+```
+
+Saves a window from the last loaded list for one fulfillment, or `null` for as soon as possible (only when `availability.canDeliverNow` is true). The promise resolves after prepare accepts and echoes that exact selection. It rejects malformed arguments, unknown fulfillments, windows that were not offered, concurrent checkout updates and server errors; a rejected save keeps the previously accepted choice, except after `delivery_selection_not_accepted` (below). Slot IDs come from the server; do not build them.
+
+`getDetails().deliveryScheduling[fulfillmentId]` returns the availability, the accepted `selectedSlotId` and `selectedSlot` (the accepted window's `start`, `end` and `cutoff`).
+
+```javascript
+const actions = client.actions.checkout;
+const [fulfillmentId] = Object.keys(actions.getDetails().deliveryScheduling);
+if (fulfillmentId) {
+  const slots = await actions.loadDeliverySlots(fulfillmentId);
+  if (slots.length) await actions.chooseDeliverySlot(fulfillmentId, slots[0].id);
+}
+```
+
+### Expired windows
+
+If a saved window's cutoff passes, or the store's hours or zone rules no longer allow it, before the order is placed, the server answers Place Order, or any other checkout update, with error code `delivery_window_expired` or `delivery_window_unavailable`. Place Order on a store that cannot deliver now with no saved window answers `delivery_window_required`. All three are recovered the same way; only the message differs ("Your delivery window has passed. Choose a new delivery time.", "Your delivery window is no longer available. Choose a new delivery time." or "The store cannot deliver now. Choose a delivery time."). The SDK then clears the window, marks the fulfillment as needing a new choice, shows the message, opens the picker and blocks payment and Place Order until the shopper saves a new choice. An update that hit the error is sent once more without the window, so the shopper's change still applies. Customer, address, payment, tip and notes stay as they were. A custom UI recovers the same way: load the windows again and call `chooseDeliverySlot`.
+
+If prepare did not keep the window that was sent (error code `delivery_selection_not_accepted`, HTTP 409), the SDK drops the window it holds for that fulfillment so no later update sends it again. `chooseDeliverySlot` rejects with "We couldn't save that delivery time. Choose a delivery time again."; on any other update the window is recovered as an unavailable one.
+
+When scheduled delivery stops applying to the order (`delivery_scheduling_not_enabled`, `delivery_windows_unsupported` or `delivery_scheduling_unsupported`, and `multiple_fulfillment_groups` from an older server that schedules one group only), the SDK drops the saved window with a re-prepare, keeps the rest of checkout and shows "Scheduled delivery isn't available for this order right now. We'll deliver as soon as possible." The picker does not open; the response no longer carries `deliveryScheduling`, so the delivery time row goes away. Switching the delivery method never carries a window over to the new fulfillment.
+
+## 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.