# Ecommerce Events Implementation Guide

## Complete Ecommerce Journey Tracking

This guide covers implementing the full customer journey from product discovery through purchase and refund handling.

---

## Ecommerce Event Flow

```
1. view_item_list       (User sees product listing)
2. select_item / view_item (User views product details)
3. add_to_cart          (User adds product to cart)
4. view_cart           (User reviews cart)
5. begin_checkout      (User starts checkout - CRITICAL METRIC)
6. add_shipping_info   (User selects shipping)
7. add_payment_info    (User enters payment)
8. purchase            (Transaction complete - MAIN GOAL)
9. refund              (Optional: Product refunded)
```

---

## Step-by-Step Implementation

### Step 1: Product Listing Page

**Event:** `view_item_list`

**Purpose:** Track when user views product search results, category pages, or product collections

**Implementation:**
```javascript
gtag('event', 'view_item_list', {
  'items': [
    {
      'item_id': 'SKU_001',
      'item_name': 'Blue T-Shirt',
      'item_category': 'Apparel',
      'price': 29.99
    },
    {
      'item_id': 'SKU_002',
      'item_name': 'Red T-Shirt',
      'item_category': 'Apparel',
      'price': 29.99
    }
  ],
  'item_list_id': 'search_results',
  'item_list_name': 'Search Results for T-Shirts'
});
```

**Trigger Points:**
- User lands on category page
- Search results load
- Related products section appears
- Collection/sale page loads

**Reporting Use:**
- "Items" report - view count by product
- Funnel analysis - how many users view products
- Product performance metrics

---

### Step 2: Product Detail Page

**Event:** `view_item`

**Purpose:** Track individual product views

**Implementation:**
```javascript
// Extract product data from page
var productData = {
  id: document.getElementById('product-id').textContent,
  name: document.getElementById('product-name').textContent,
  price: parseFloat(document.getElementById('product-price').textContent),
  category: document.getElementById('product-category').textContent
};

gtag('event', 'view_item', {
  'items': [{
    'item_id': productData.id,
    'item_name': productData.name,
    'item_category': productData.category,
    'item_brand': 'Your Brand',
    'item_variant': 'Blue/Large',
    'price': productData.price,
    'quantity': 1
  }],
  'value': productData.price,
  'currency': 'USD'
});
```

**Advanced Implementation (Multiple Variants):**
```javascript
gtag('event', 'view_item', {
  'items': [{
    'item_id': 'SKU_123',
    'item_name': 'Premium T-Shirt',
    'item_category': 'Apparel',
    'item_category2': 'Shirts',
    'item_category3': 'Premium',
    'item_brand': 'Brand Name',
    'item_variant': 'Blue',
    'item_list_name': 'Search Results',
    'price': 49.99,
    'quantity': 1
  }],
  'value': 49.99,
  'currency': 'USD'
});
```

**Trigger Points:**
- Product detail page loads
- User arrives via search or category link
- Product page ready (after lazy-loading images)

---

### Step 3: Add to Cart

**Event:** `add_to_cart`

**Purpose:** Track when items are added to shopping cart

**Implementation:**
```javascript
document.getElementById('add-to-cart-btn').addEventListener('click', function() {
  var quantity = parseInt(document.getElementById('quantity-input').value) || 1;
  var price = parseFloat(document.getElementById('product-price').textContent);
  var itemId = document.getElementById('product-id').textContent;

  gtag('event', 'add_to_cart', {
    'items': [{
      'item_id': itemId,
      'item_name': 'Product Name',
      'item_category': 'Apparel',
      'price': price,
      'quantity': quantity
    }],
    'value': price * quantity,
    'currency': 'USD'
  });

  // Proceed with cart addition
  addToCart(itemId, quantity);
});
```

**Important Notes:**
- Value should be `price * quantity`
- Send immediately when user clicks add button
- Don't wait for backend confirmation
- Always include items array

**Reporting Use:**
- Add-to-cart rate metrics
- Funnel drop-off analysis
- Cart value trending

---

### Step 4: View Cart

**Event:** `view_cart`

**Purpose:** Track when user reviews shopping cart

**Implementation:**
```javascript
// On cart page load
var cartItems = getCartItemsFromStorage(); // Your cart data
var totalValue = 0;

var itemsArray = cartItems.map(function(item) {
  totalValue += item.price * item.quantity;
  return {
    'item_id': item.id,
    'item_name': item.name,
    'item_category': item.category,
    'price': item.price,
    'quantity': item.quantity
  };
});

gtag('event', 'view_cart', {
  'items': itemsArray,
  'value': totalValue,
  'currency': 'USD'
});
```

**Trigger Points:**
- User navigates to cart page
- User views mini-cart
- Cart updates after removing item

---

### Step 5: Begin Checkout (CRITICAL)

**Event:** `begin_checkout`

**Purpose:** Track when user initiates checkout (most important funnel metric)

**Implementation:**
```javascript
document.getElementById('checkout-btn').addEventListener('click', function() {
  var cartItems = getCartItems();
  var totalValue = calculateCartTotal();

  gtag('event', 'begin_checkout', {
    'items': cartItems.map(function(item) {
      return {
        'item_id': item.id,
        'item_name': item.name,
        'item_category': item.category,
        'price': item.price,
        'quantity': item.quantity
      };
    }),
    'value': totalValue,
    'currency': 'USD'
  });

  // Navigate to checkout
  redirectToCheckout();
});
```

**Why It's Critical:**
- Baseline funnel metric
- Identifies cart abandonment
- Used for conversion modeling
- Compare begin_checkout to purchase ratio

**Trigger Points:**
- User clicks "Checkout" button
- User navigates to checkout page
- One-page checkout form loads

---

### Step 6: Add Shipping Info

**Event:** `add_shipping_info`

**Purpose:** Track when user selects shipping method

**Implementation:**
```javascript
document.querySelectorAll('input[name="shipping"]').forEach(function(option) {
  option.addEventListener('change', function() {
    var selectedShipping = this.value;
    var cartItems = getCartItems();
    var subtotal = calculateSubtotal();
    var shippingCost = getShippingCost(selectedShipping);
    var total = subtotal + shippingCost;

    gtag('event', 'add_shipping_info', {
      'items': cartItems,
      'value': total,
      'currency': 'USD',
      'shipping_tier': selectedShipping  // 'standard', 'express', 'overnight'
    });
  });
});
```

**Shipping Tier Values:**
- `standard` - Standard delivery
- `express` - Express delivery
- `overnight` - Overnight delivery
- `pickup` - Store pickup
- `free_shipping` - Free shipping option

**Reporting Use:**
- Shipping method selection analysis
- Funnel drop-off by shipping option

---

### Step 7: Add Payment Info

**Event:** `add_payment_info`

**Purpose:** Track when user enters payment information

**Implementation:**
```javascript
document.getElementById('payment-form').addEventListener('submit', function(e) {
  e.preventDefault();

  var paymentMethod = document.querySelector('input[name="payment"]:checked').value;
  var cartItems = getCartItems();
  var totalValue = calculateTotal();

  gtag('event', 'add_payment_info', {
    'payment_type': paymentMethod,
    'items': cartItems,
    'value': totalValue,
    'currency': 'USD'
  });

  // Process payment
  processPayment(paymentMethod);
});
```

**Payment Type Values:**
- `credit_card`
- `debit_card`
- `paypal`
- `apple_pay`
- `google_pay`
- `bank_transfer`
- `crypto`

**Reporting Use:**
- Payment method distribution
- Payment method-to-purchase completion rate

---

### Step 8: Purchase (MOST IMPORTANT)

**Event:** `purchase`

**Purpose:** Track completed transactions (highest priority event)

**Implementation:**
```javascript
// After payment confirmation
function trackPurchase(transactionData) {
  gtag('event', 'purchase', {
    'transaction_id': 'TXN_' + Date.now() + '_' + Math.random().toString(36).substr(2, 9),
    'affiliation': 'Online Store',
    'value': transactionData.total,
    'currency': 'USD',
    'tax': transactionData.tax,
    'shipping': transactionData.shipping,
    'coupon': transactionData.coupon || undefined,
    'items': transactionData.items.map(function(item) {
      return {
        'item_id': item.id,
        'item_name': item.name,
        'item_category': item.category,
        'item_brand': item.brand,
        'item_variant': item.variant,
        'price': item.price,
        'quantity': item.quantity,
        'affiliation': 'Online Store'
      };
    })
  });
}
```

**Transaction ID Requirements:**
```
✅ GOOD:
TXN_1731234567890_abc123def456   // Unique, timestamp-based
TXN_20241110_001_ABC123           // Order ID based
user_123_purchase_1234567890      // User + timestamp based

❌ BAD:
purchase                           // Not unique
order_123                          // Can be reused
TXN_12345                          // Too short, likely duplicated
```

**Critical Points:**
1. **Uniqueness:** Each transaction gets ONE unique ID
2. **Non-reusable:** Never use same ID twice
3. **Consistency:** Use same ID in all systems (website, backend, reports)
4. **Timing:** Send immediately upon payment confirmation
5. **Items Array:** Must include all products purchased

**Backend Implementation (Node.js):**
```javascript
app.post('/api/purchase', async (req, res) => {
  const { orderData } = req.body;
  const transactionId = `TXN_${Date.now()}_${generateRandomString(12)}`;

  // Save order
  await Order.create({
    transactionId: transactionId,
    items: orderData.items,
    total: orderData.total,
    // ...
  });

  // Return transaction ID for client-side tracking
  res.json({ transactionId: transactionId });
});

// Client receives transaction ID and sends to GA4
gtag('event', 'purchase', {
  'transaction_id': response.transactionId,
  'items': cartItems,
  'value': total,
  'currency': 'USD'
});
```

**Reporting Impact:**
- Revenue tracking
- Transaction count
- Google Ads conversion tracking
- Attribution modeling
- Ecommerce reports
- Key Event (automatic)

---

### Step 9: Refund (Optional)

**Event:** `refund`

**Purpose:** Track refunded purchases

**Implementation:**
```javascript
// When refund is processed
gtag('event', 'refund', {
  'transaction_id': orderData.transactionId,  // Same ID as original purchase
  'value': refundAmount,
  'currency': 'USD',
  'items': [
    {
      'item_id': 'SKU_123',
      'quantity': 1  // Quantity refunded
    }
  ]
});
```

**Important:**
- Use SAME transaction_id as original purchase
- Value is the refund amount
- Only include refunded items

---

## Multiple Product Variants

**Scenario:** Product available in multiple sizes/colors

```javascript
// Product: "T-Shirt" available in Blue/Large, Red/Small, etc.

gtag('event', 'add_to_cart', {
  'items': [{
    'item_id': 'SKU_TSHIRT_BLUE_LARGE',  // Unique per variant
    'item_name': 'Blue T-Shirt - Large',
    'item_category': 'Apparel',
    'item_variant': 'Blue/Large',
    'price': 49.99,
    'quantity': 1
  }],
  'value': 49.99,
  'currency': 'USD'
});
```

---

## Multi-Quantity Purchases

**Scenario:** Customer buys multiple products in one transaction

```javascript
gtag('event', 'purchase', {
  'transaction_id': 'TXN_12345678',
  'value': 329.97,
  'currency': 'USD',
  'items': [
    {
      'item_id': 'SKU_001',
      'item_name': 'Product A',
      'price': 99.99,
      'quantity': 2  // Two units
    },
    {
      'item_id': 'SKU_002',
      'item_name': 'Product B',
      'price': 130.00,
      'quantity': 1  // One unit
    }
  ]
});
```

**Value Calculation:**
- Product A: 99.99 × 2 = 199.98
- Product B: 130.00 × 1 = 130.00
- Total: 329.98 ✓

---

## Coupons and Discounts

**Scenario:** Customer applies coupon code

**Single Coupon (Purchase Level):**
```javascript
gtag('event', 'purchase', {
  'transaction_id': 'TXN_12345678',
  'value': 89.99,    // Already discounted
  'currency': 'USD',
  'coupon': 'SUMMER20',  // Coupon code
  'tax': 5.00,
  'shipping': 10.00,
  'items': [{
    'item_id': 'SKU_001',
    'item_name': 'Product',
    'price': 100.00,  // Pre-discount price
    'quantity': 1
  }]
});
```

**Item-Level Coupon:**
```javascript
gtag('event', 'purchase', {
  'transaction_id': 'TXN_12345678',
  'value': 329.97,
  'currency': 'USD',
  'items': [
    {
      'item_id': 'SKU_001',
      'item_name': 'Product A',
      'price': 99.99,
      'quantity': 2,
      'coupon': 'SUMMER20',  // Item-specific coupon
      'discount': 20.00      // Discount amount
    }
  ]
});
```

---

## Funnel Analysis

**View the complete ecommerce funnel:**

```
view_item_list     → 1000 users (100%)
view_item          → 450 users (45%)
add_to_cart        → 120 users (12%)
begin_checkout     → 95 users (9.5%)  ← CRITICAL METRIC
purchase           → 75 users (7.5%)
```

**Drop-off Points:**
- view_item → add_to_cart: 73% drop (improve product pages)
- add_to_cart → begin_checkout: 21% drop (simplify cart)
- begin_checkout → purchase: 21% drop (optimize checkout)

---

## Testing Ecommerce Events

1. **Product Page:** Verify view_item fires with correct product data
2. **Add to Cart:** Check add_to_cart with accurate quantity/price
3. **Checkout:** Enable DebugView before begin_checkout
4. **Purchase:** Validate transaction_id is unique
5. **Items Array:** Confirm all items include item_id or item_name

**Use DebugView to verify:**
```
✓ Event name correct (purchase, add_to_cart, etc.)
✓ Required parameters present
✓ Items array structured correctly
✓ Values match actual amounts
✓ Transaction ID is unique
```