# Events Guide

The SDK publishes browser events for user interactions and state changes. Use them to react to product selections, cart updates, and checkout progress.

## Event Format

All SDK events are dispatched as native `CustomEvent` objects. The payload lives in `event.detail`:

```javascript
window.addEventListener('lce:actions.client_ready', (event) => {
  const { data, metadata } = event.detail;

  const {
    event: eventName,
    namespace,
    originalEvent,
    actionNamespace,
    eventId,
    timestamp
  } = metadata;
});
```

`data` is event-specific. `metadata` describes the event (name, namespace, timestamp, etc).

## Event Namespaces

- `lce:actions.*` - User actions and state changes
- `lce:forms.*` - Form field interactions (checkout)
- `lce:actions` - All action events (namespace-level listener)
- `lce:forms` - All form events (namespace-level listener)

Example: listen to every action event:

```javascript
window.addEventListener('lce:actions', (event) => {
  const { metadata } = event.detail;
  console.log('Action event:', metadata.event);
});
```

## Core Events

### `lce:actions.client_ready`

Fires once when the SDK finishes initializing and is ready for actions.

**Data includes:** `isReady`, `message`, `timestamp`, `version`.

**Example**

```javascript
window.addEventListener('lce:actions.client_ready', (event) => {
  const { data } = event.detail;
  if (data.isReady) {
    console.log('Elements SDK ready', data.version);
  }
});
```

## Product Events

### `lce:actions.product_loaded`

Fires when a product component finishes loading and product data is available.

**Data includes:** `identifier`, `name`, `price`, `selectedSizeId`, `selectedFulfillmentType`.

**Example**

```javascript
window.addEventListener('lce:actions.product_loaded', (event) => {
  const { data } = event.detail;
  console.log(`Loaded ${data.name} (${data.identifier})`);
});
```

### `lce:actions.product_add_to_cart`

Fires when the user triggers add-to-cart from a product component. Use cart events to confirm success or failure.

**Data includes:** `identifier`, `quantity`, `fulfillmentId`, `partNumber`, `engravingLines`.

**Example**

```javascript
window.addEventListener('lce:actions.product_add_to_cart', (event) => {
  const { data } = event.detail;
  gtag('event', 'add_to_cart_click', { item_id: data.identifier, quantity: data.quantity });
});
```

### `lce:actions.product_size_changed`

Fires when the user changes the selected size.

**Data includes:** `identifier`, `selectedSizeId`, `selectedSize`, `previousSizeId`, `previousSize`.

**Example**

```javascript
window.addEventListener('lce:actions.product_size_changed', (event) => {
  const { data } = event.detail;
  console.log(`Size changed to ${data.selectedSize}`);
});
```

### `lce:actions.product_fulfillment_type_changed`

Fires when the user switches between fulfillment types (for example shipping vs onDemand).

**Data includes:** `identifier`, `selectedFulfillmentType`, `previousFulfillmentType`, `selectedFulfillmentId`, `previousFulfillmentId`.

**Example**

```javascript
window.addEventListener('lce:actions.product_fulfillment_type_changed', (event) => {
  const { data } = event.detail;
  console.log('Fulfillment type:', data.selectedFulfillmentType);
});
```

### `lce:actions.product_fulfillment_changed`

Fires when the user selects a different fulfillment option or retailer.

**Data includes:** `identifier`, `selectedFulfillmentId`, `previousFulfillmentId`, `selectedFulfillmentType`, `previousFulfillmentType`.

**Example**

```javascript
window.addEventListener('lce:actions.product_fulfillment_changed', (event) => {
  const { data } = event.detail;
  console.log('Fulfillment changed:', data.selectedFulfillmentId);
});
```

### `lce:actions.product_quantity_increase`

Fires when the product quantity is increased.

**Data includes:** `identifier`, `quantity`, `previousQuantity`.

**Example**

```javascript
window.addEventListener('lce:actions.product_quantity_increase', (event) => {
  const { data } = event.detail;
  console.log('Quantity increased to', data.quantity);
});
```

### `lce:actions.product_quantity_decrease`

Fires when the product quantity is decreased.

**Data includes:** `identifier`, `quantity`, `previousQuantity`.

**Example**

```javascript
window.addEventListener('lce:actions.product_quantity_decrease', (event) => {
  const { data } = event.detail;
  console.log('Quantity decreased to', data.quantity);
});
```

## Address Events

### `lce:actions.address_updated`

Fires when an address is successfully set.

**Data includes:** `googlePlacesId`, `formattedAddress`, `address`, `coordinates`.

**Example**

```javascript
window.addEventListener('lce:actions.address_updated', (event) => {
  const { data } = event.detail;
  console.log('Address set:', data.formattedAddress);
});
```

### `lce:actions.address_cleared`

Fires when the current address is cleared.

**Data includes:** `true`.

**Example**

```javascript
window.addEventListener('lce:actions.address_cleared', () => {
  console.log('Address cleared');
});
```

### `lce:actions.address_failed`

Fires when setting the address fails.

**Data includes:** `googlePlacesId`, `formattedAddress`, `address`, `coordinates`, `error`.

**Example**

```javascript
window.addEventListener('lce:actions.address_failed', (event) => {
  const { data } = event.detail;
  console.error('Address error:', data.error);
});
```

## Cart Events

### `lce:actions.cart_loaded`

Fires when the cart is fully loaded or synced.

**Data includes:** `cartId`, `itemCount`, `subtotal`, `items`, `promoCodeDiscount`.

**Example**

```javascript
window.addEventListener('lce:actions.cart_loaded', (event) => {
  const { data } = event.detail;
  console.log(`Cart ${data.cartId} has ${data.itemCount} items`);
});
```

### `lce:actions.cart_opened`

Fires when the cart drawer opens.

**Data includes:** `true`.

**Example**

```javascript
window.addEventListener('lce:actions.cart_opened', () => {
  document.body.classList.add('cart-open');
});
```

### `lce:actions.cart_closed`

Fires when the cart drawer closes.

**Data includes:** `true`.

**Example**

```javascript
window.addEventListener('lce:actions.cart_closed', () => {
  document.body.classList.remove('cart-open');
});
```

### `lce:actions.cart_updated`

Fires when cart contents or totals change.

**Data includes:** `previous`, `current`.

**Example**

```javascript
window.addEventListener('lce:actions.cart_updated', (event) => {
  const { data } = event.detail;
  const delta = data.current.itemCount - data.previous.itemCount;
  if (delta !== 0) {
    console.log('Item count changed by', delta);
  }
});
```

### `lce:actions.cart_reset`

Fires when the cart is cleared.

**Data includes:** `true`.

**Example**

```javascript
window.addEventListener('lce:actions.cart_reset', () => {
  console.log('Cart reset');
});
```

### `lce:actions.cart_failed`

Fires when a cart operation fails.

**Data includes:** `cartId`, `message`.

**Example**

```javascript
window.addEventListener('lce:actions.cart_failed', (event) => {
  const { data } = event.detail;
  console.error('Cart error:', data.message);
});
```

### `lce:actions.cart_item_added`

Fires when an item is added to the cart.

**Data includes:** `cartId`, `itemId`, `quantity`, `fulfillmentId`, `partNumber`.

**Example**

```javascript
window.addEventListener('lce:actions.cart_item_added', (event) => {
  const { data } = event.detail;
  console.log(`Added item ${data.itemId} (qty ${data.quantity})`);
});
```

### `lce:actions.cart_item_removed`

Fires when an item is removed from the cart.

**Data includes:** `cartId`, `itemId`.

**Example**

```javascript
window.addEventListener('lce:actions.cart_item_removed', (event) => {
  const { data } = event.detail;
  console.log('Removed item', data.itemId);
});
```

### `lce:actions.cart_item_quantity_increase`

Fires when a cart item quantity increases.

**Data includes:** `cartId`, `itemId`, `quantity`, `previousQuantity`.

**Example**

```javascript
window.addEventListener('lce:actions.cart_item_quantity_increase', (event) => {
  const { data } = event.detail;
  console.log('Quantity increased to', data.quantity);
});
```

### `lce:actions.cart_item_quantity_decrease`

Fires when a cart item quantity decreases.

**Data includes:** `cartId`, `itemId`, `quantity`, `previousQuantity`.

**Example**

```javascript
window.addEventListener('lce:actions.cart_item_quantity_decrease', (event) => {
  const { data } = event.detail;
  console.log('Quantity decreased to', data.quantity);
});
```

### `lce:actions.cart_item_engraving_updated`

Fires when engraving text is updated for a cart item.

**Data includes:** `cartId`, `itemId`, `engravingLines`, `previousEngravingLines`.

**Example**

```javascript
window.addEventListener('lce:actions.cart_item_engraving_updated', (event) => {
  const { data } = event.detail;
  console.log('Updated engraving for', data.itemId);
});
```

### `lce:actions.cart_promo_code_applied`

Fires when a promo code is applied to the cart.

**Data includes:** `cartId`, `discount`, `newSubtotal`.

**Example**

```javascript
window.addEventListener('lce:actions.cart_promo_code_applied', (event) => {
  const { data } = event.detail;
  console.log('Promo applied, discount:', data.discount);
});
```

### `lce:actions.cart_promo_code_removed`

Fires when a promo code is removed from the cart.

**Data includes:** `cartId`, `discount`, `newSubtotal`.

**Example**

```javascript
window.addEventListener('lce:actions.cart_promo_code_removed', (event) => {
  const { data } = event.detail;
  console.log('Promo removed');
});
```

### `lce:actions.cart_promo_code_failed`

Fires when a promo code fails to apply.

**Data includes:** `cartId`, `error`.

**Example**

```javascript
window.addEventListener('lce:actions.cart_promo_code_failed', (event) => {
  const { data } = event.detail;
  console.error('Promo code failed:', data.error);
});
```

### `lce:actions.cart_product_add_success`

Fires when adding products via the actions API succeeds.

**Data includes:** `cartId`, `itemsAdded`, `identifiers`.

**Example**

```javascript
window.addEventListener('lce:actions.cart_product_add_success', (event) => {
  const { data } = event.detail;
  console.log(`Added ${data.itemsAdded} products`);
});
```

### `lce:actions.cart_product_add_failed`

Fires when adding products via the actions API fails.

**Data includes:** `cartId`, `identifiers`, `error`.

**Example**

```javascript
window.addEventListener('lce:actions.cart_product_add_failed', (event) => {
  const { data } = event.detail;
  console.error('Product add failed:', data.error);
});
```

## Checkout Events

### `lce:actions.checkout_loaded`

Fires when checkout data loads.

**Data includes:** `cartId`, `amounts`, `itemCount`, `isGift`, `billingSameAsShipping`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_loaded', (event) => {
  const { data } = event.detail;
  console.log('Checkout loaded for cart', data.cartId);
});
```

### `lce:actions.checkout_opened`

Fires when the checkout drawer opens.

**Data includes:** `true`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_opened', () => {
  console.log('Checkout opened');
});
```

### `lce:actions.checkout_closed`

Fires when the checkout drawer closes.

**Data includes:** `true`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_closed', () => {
  console.log('Checkout closed');
});
```

### `lce:actions.checkout_failed`

Fires when checkout fails to load or operate.

**Data includes:** `message`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_failed', (event) => {
  const { data } = event.detail;
  console.error('Checkout error:', data.message);
});
```

### `lce:actions.checkout_customer_information_updated`

Fires when customer info (email, phone, name) is updated.

**Data includes:** `cartId`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_customer_information_updated', (event) => {
  const { data } = event.detail;
  console.log('Customer info updated for cart', data.cartId);
});
```

### `lce:actions.checkout_billing_information_updated`

Fires when billing info is updated.

**Data includes:** `cartId`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_billing_information_updated', (event) => {
  const { data } = event.detail;
  console.log('Billing info updated for cart', data.cartId);
});
```

### `lce:actions.checkout_gift_information_updated`

Fires when gift recipient info is updated.

**Data includes:** `cartId`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_gift_information_updated', (event) => {
  const { data } = event.detail;
  console.log('Gift info updated for cart', data.cartId);
});
```

### `lce:actions.checkout_is_gift_toggled`

Fires when gift mode is toggled.

**Data includes:** `cartId`, `isActive`, `previousIsActive`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_is_gift_toggled', (event) => {
  const { data } = event.detail;
  console.log('Gift mode:', data.isActive);
});
```

### `lce:actions.checkout_billing_same_as_shipping_toggled`

Fires when the billing same-as-shipping option is toggled.

**Data includes:** `cartId`, `isActive`, `previousIsActive`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_billing_same_as_shipping_toggled', (event) => {
  const { data } = event.detail;
  console.log('Billing same as shipping:', data.isActive);
});
```

### `lce:actions.checkout_marketing_preferences_toggled`

Fires when a marketing preference is toggled.

**Data includes:** `cartId`, `fieldName`, `isActive`, `previousIsActive`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_marketing_preferences_toggled', (event) => {
  const { data } = event.detail;
  console.log(`Marketing ${data.fieldName}:`, data.isActive);
});
```

### `lce:actions.checkout_item_removed`

Fires when an item is removed during checkout.

**Data includes:** `cartId`, `cartItemId`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_item_removed', (event) => {
  const { data } = event.detail;
  console.log('Checkout item removed', data.cartItemId);
});
```

### `lce:actions.checkout_item_quantity_increase`

Fires when a checkout item quantity increases.

**Data includes:** `cartId`, `cartItemId`, `quantity`, `previousQuantity`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_item_quantity_increase', (event) => {
  const { data } = event.detail;
  console.log('Checkout quantity increased to', data.quantity);
});
```

### `lce:actions.checkout_item_quantity_decrease`

Fires when a checkout item quantity decreases.

**Data includes:** `cartId`, `cartItemId`, `quantity`, `previousQuantity`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_item_quantity_decrease', (event) => {
  const { data } = event.detail;
  console.log('Checkout quantity decreased to', data.quantity);
});
```

### `lce:actions.checkout_item_engraving_updated`

Fires when engraving text is updated for a checkout item.

**Data includes:** `cartId`, `cartItemId`, `engravingLines`, `previousEngravingLines`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_item_engraving_updated', (event) => {
  const { data } = event.detail;
  console.log('Checkout engraving updated for', data.cartItemId);
});
```

### `lce:actions.checkout_tip_updated`

Fires when delivery tips are updated.

**Data includes:** `cartId`, `deliveryTips`, `previousDeliveryTips`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_tip_updated', (event) => {
  const { data } = event.detail;
  console.log('Tips updated for cart', data.cartId);
});
```

### `lce:actions.checkout_submit_started`

Fires when checkout submission starts.

**Data includes:** `started`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_submit_started', (event) => {
  const { data } = event.detail;
  if (data.started) {
    console.log('Checkout submission started');
  }
});
```

### `lce:actions.checkout_submit_completed`

Fires when checkout submission completes successfully.

**Data includes:** `orderNumber`, `orderTotal`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
  const { data } = event.detail;
  console.log('Order completed:', data.orderNumber);
});
```

### `lce:actions.checkout_submit_failed`

Fires when checkout submission fails.

**Data includes:** `message`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_submit_failed', (event) => {
  const { data } = event.detail;
  console.error('Checkout submit failed:', data.message);
});
```

### `lce:actions.checkout_promo_code_applied`

Fires when a promo code is applied during checkout.

**Data includes:** `cartId`, `discount`, `newTotal`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_promo_code_applied', (event) => {
  const { data } = event.detail;
  console.log('Checkout promo applied:', data.discount);
});
```

### `lce:actions.checkout_promo_code_removed`

Fires when a promo code is removed during checkout.

**Data includes:** `cartId`, `discount`, `newTotal`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_promo_code_removed', (event) => {
  const { data } = event.detail;
  console.log('Checkout promo removed');
});
```

### `lce:actions.checkout_promo_code_failed`

Fires when a promo code fails during checkout.

**Data includes:** `cartId`, `error`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_promo_code_failed', (event) => {
  const { data } = event.detail;
  console.error('Checkout promo failed:', data.error);
});
```

### `lce:actions.checkout_gift_card_applied`

Fires when a gift card is applied during checkout.

**Data includes:** `cartId`, `newTotal`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_gift_card_applied', (event) => {
  const { data } = event.detail;
  console.log('Gift card applied, new total:', data.newTotal);
});
```

### `lce:actions.checkout_gift_card_removed`

Fires when a gift card is removed during checkout.

**Data includes:** `cartId`, `newTotal`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_gift_card_removed', (event) => {
  const { data } = event.detail;
  console.log('Gift card removed');
});
```

### `lce:actions.checkout_gift_card_failed`

Fires when a gift card fails during checkout.

**Data includes:** `cartId`, `error`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_gift_card_failed', (event) => {
  const { data } = event.detail;
  console.error('Gift card failed:', data.error);
});
```

### `lce:actions.checkout_product_add_success`

Fires when products are added to checkout via the actions API.

**Data includes:** `cartId`, `itemsAdded`, `identifiers`, `isPresale`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_product_add_success', (event) => {
  const { data } = event.detail;
  console.log(`Checkout added ${data.itemsAdded} products`);
});
```

### `lce:actions.checkout_product_add_failed`

Fires when adding products to checkout via the actions API fails.

**Data includes:** `cartId`, `identifiers`, `error`, `isPresale`.

**Example**

```javascript
window.addEventListener('lce:actions.checkout_product_add_failed', (event) => {
  const { data } = event.detail;
  console.error('Checkout product add failed:', data.error);
});
```

## Form Events

### `lce:forms.customer`

Fires when a customer form field changes in checkout.

**Data includes:** `fieldName`, `fieldValue`.

**Example**

```javascript
window.addEventListener('lce:forms.customer', (event) => {
  const { data } = event.detail;
  console.log('Customer field changed:', data.fieldName);
});
```

### `lce:forms.billing`

Fires when a billing form field changes in checkout.

**Data includes:** `fieldName`, `fieldValue`.

**Example**

```javascript
window.addEventListener('lce:forms.billing', (event) => {
  const { data } = event.detail;
  console.log('Billing field changed:', data.fieldName);
});
```

### `lce:forms.gift`

Fires when a gift form field changes in checkout.

**Data includes:** `fieldName`, `fieldValue`.

**Example**

```javascript
window.addEventListener('lce:forms.gift', (event) => {
  const { data } = event.detail;
  console.log('Gift field changed:', data.fieldName);
});
```

## Use Cases

### Analytics Integration

```javascript
// Track product views
window.addEventListener('lce:actions.product_loaded', (event) => {
  const { data } = event.detail;
  gtag('event', 'view_item', {
    items: [{
      item_id: data.identifier,
      item_name: data.name,
      price: data.price / 100
    }]
  });
});

// Track purchases
window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
  const { data } = event.detail;
  gtag('event', 'purchase', {
    transaction_id: data.orderNumber,
    value: data.orderTotal / 100,
    currency: 'USD'
  });
});
```

## See Also

- [Component Guides](../guides/)
- [Actions API](../api/actions/)