gh-henkisdabro-wookstar-claude-code-plugins-ga-suite/skills/ga4-debugview/references/ecommerce-testing.md

E-commerce Event Testing in DebugView

Complete E-commerce Flow

1. view_item_list

Fires: Product listing page loads

Required Parameters:

• item_list_id: "related_products", "search_results"
• item_list_name: "Related Products", "Search Results"
• items: Array of products shown

Validation:

• Items array populated
• Each item has item_id and item_name
• item_list_id and item_list_name present

2. select_item

Fires: User clicks product from list

Required Parameters:

• item_list_id: Same as view_item_list
• item_list_name: Same as view_item_list
• items: Array with selected item

Validation:

• Only selected item in items array
• item_list matches where user clicked from

3. view_item

Fires: Product detail page loads

Required Parameters:

• currency: "USD"
• value: Product price
• items: Array with single product

Validation:

• currency present
• value is number
• items[0] contains full product details

4. add_to_cart

Fires: User adds item to cart

Required Parameters:

• currency: "USD"
• value: Item total (price × quantity)
• items: Array with added item(s)

Validation:

• value = price × quantity
• currency matches site currency
• items array has correct item
• quantity is integer

5. remove_from_cart (Optional)

Fires: User removes item from cart

Required Parameters:

• currency: "USD"
• value: Removed item value
• items: Array with removed item

6. view_cart (Optional)

Fires: Cart page loads

Required Parameters:

• currency: "USD"
• value: Total cart value
• items: All items in cart

7. begin_checkout

Fires: Checkout process starts

Required Parameters:

• currency: "USD"
• value: Cart total
• items: All items in cart
• coupon (if applicable)

Validation:

• value matches cart total
• All cart items in items array
• coupon code if applied

8. add_payment_info (Optional)

Fires: Payment method added

Required Parameters:

• currency: "USD"
• value: Transaction value
• payment_type: "credit_card", "paypal", etc.

9. add_shipping_info (Optional)

Fires: Shipping info added

Required Parameters:

• currency: "USD"
• value: Transaction value
• shipping_tier: "Ground", "Express", etc.

10. purchase

Fires: Transaction completes

Required Parameters:

• transaction_id: UNIQUE order ID
• currency: "USD"
• value: Total revenue
• items: All purchased items

Optional Parameters:

• tax: Tax amount
• shipping: Shipping cost
• coupon: Coupon code
• affiliation: Store name

Validation:

• transaction_id is unique (never reused)
• value is total (items + tax + shipping - discounts)
• All items have complete details
• tax and shipping are numbers
• No duplicate purchase events

11. refund (Optional)

Fires: Transaction refunded

Required Parameters:

• transaction_id: Original order ID
• currency: "USD"
• value: Refund amount

Items Array Structure

Complete Item Object:

{
  "item_id": "SKU_12345",           // Required
  "item_name": "Blue T-Shirt",      // Required
  "affiliation": "Online Store",
  "coupon": "SUMMER20",
  "currency": "USD",
  "discount": 2.00,
  "index": 0,                        // Position in list
  "item_brand": "MyBrand",
  "item_category": "Apparel",
  "item_category2": "Men",
  "item_category3": "Shirts",
  "item_category4": "T-Shirts",
  "item_category5": "Short Sleeve",
  "item_list_id": "related_products",
  "item_list_name": "Related Products",
  "item_variant": "Blue",
  "location_id": "Warehouse_A",
  "price": 29.99,                    // Required for most events
  "quantity": 2                      // Required for cart/purchase events
}

Testing Purchase Event

Complete Test:

1. Add items to cart → Verify add_to_cart for each
2. Go to checkout → Verify begin_checkout
3. Complete purchase → Verify purchase

Purchase Event Checklist:

• Event name: purchase
• transaction_id present and unique
• value is number (not string)
• currency is 3-letter code
• items array not empty
• Each item has item_id
• Each item has item_name
• Each item has price (number)
• Each item has quantity (integer)
• Optional: tax is number
• Optional: shipping is number
• Optional: coupon is string
• No duplicate transaction_id in DebugView session

Common Issues:

Issue: Items array empty

• Cause: Items not passed to event
• Fix: Ensure dataLayer.push includes ecommerce.items

Issue: Value is string "99.99"

• Cause: Quotes around number
• Fix: Remove quotes: value: 99.99

Issue: transaction_id repeats

• Cause: Page reload after purchase, or testing with same ID
• Fix: Generate unique IDs, prevent double-submit

Issue: Item missing price

• Cause: Incomplete item object
• Fix: Include price in every item object

Calculating Value

Formula:

value = (sum of item prices × quantities) + tax + shipping - discount

Example:

Item 1: $29.99 × 2 = $59.98
Item 2: $19.99 × 1 = $19.99
Subtotal: $79.97
Tax: $6.40
Shipping: $5.00
Discount: -$10.00
Total value: $81.37

In DebugView:

purchase event:
  value: 81.37
  currency: "USD"
  tax: 6.40
  shipping: 5.00
  items: [item1, item2]

Multi-Step Checkout Validation

Step 1: Cart Page

• view_cart event
• Items match current cart
• Value correct

Step 2: Shipping Info

• add_shipping_info event
• shipping_tier parameter
• Value includes shipping

Step 3: Payment Info

• add_payment_info event
• payment_type parameter
• Value matches total

Step 4: Review Order

• No specific event (or custom event)
• Final verification before purchase

Step 5: Purchase Complete

• purchase event
• Unique transaction_id
• All parameters correct
• Confirmation page loads

Testing with Test Transactions

Using GTM Preview + DebugView:

1. Enable GTM Preview mode
2. Enable DebugView
3. Add test product to cart
4. Complete checkout with test payment
5. Verify each event in real-time:
   • GTM Tag Assistant: Tags fire
   • DebugView: Events appear
6. Cross-check parameters match
7. Verify transaction_id is unique
8. Test refund event (if implemented)

Best Practice:

• Use test payment gateway in development
• Generate unique transaction_ids for each test
• Document test transaction IDs
• Clean up test data if it reaches production