User.com REST API Docs

# Product Events

Product events track the e-commerce funnel and power abandoned cart automations and product recommendations. Create separate GTM tags for each event type, triggered by your existing GA4 e-commerce dataLayer events.

# Prerequisites

Ensure you have:

  1. Basic tracking script — User.com SDK loaded and ready
  2. GA4 e-commerce tracking — Standard Google Analytics 4 e-commerce events implemented
  3. Product catalog sync — Products already synced via Product catalog sync
Event Type GA4 Trigger Description
view view_item Contact views a product detail page
add to cart add_to_cart Contact adds item to basket
checkout begin_checkout Contact enters checkout flow

# Required ecommerce variable

The product event tags below use {{DLV - ecommerce.items}} to access product data from your GA4 dataLayer.

Check if you already have this variable: Go to Variables in GTM and look for an existing Data Layer Variable that reads ecommerce.items. If you find one, use its name in the code examples below instead of DLV - ecommerce.items.

If you need to create it:

  1. Go to Variables → New → Data Layer Variable
  2. Set Data Layer Variable Name to ecommerce.items
  3. Name it DLV - ecommerce.items (or follow your naming convention)
  4. Save

This variable reads the items array from your existing GA4 ecommerce dataLayer pushes. If your implementation uses a different structure, adjust the variable path accordingly.

# Product view tag

Create a Custom HTML tag triggered on view_item:

<script>
  if (typeof userengage === 'function') {
    var items = {{DLV - ecommerce.items}};
    if (items && items.length > 0) {
      userengage('product_event', {
        product_id: items[0].item_id,
        event_type: 'view'
      });
    }
  }
</script>

# Add to cart tag

Create a Custom HTML tag triggered on add_to_cart:

<script>
  if (typeof userengage === 'function') {
    var items = {{DLV - ecommerce.items}};
    if (items && items.length > 0) {
      items.forEach(function(item) {
        userengage('product_event', {
          product_id: item.item_id,
          event_type: 'add to cart',
        });
      });
    }
  }
</script>

# Checkout tag

Create a Custom HTML tag triggered on begin_checkout:

<script>
  if (typeof userengage === 'function') {
    var items = {{DLV - ecommerce.items}};
    if (items && items.length > 0) {
      items.forEach(function(item) {
        userengage('product_event', {
          product_id: item.item_id,
          event_type: 'checkout',
        });
      });
    }
  }
</script>

# Understanding custom_data

Product attributes in User.com get overwritten with each event—that's how your catalog stays current. But custom_data is attached to the specific event instance and preserved permanently. Use it for:

  • Price at moment: The exact price when the action occurred
  • Quantity: How many items were added
  • Variant details: Size, color, or configuration selected
  • Session identifiers: Linking related events together

# Additional event types

These events add granularity for advanced segmentation:

Event Type Use Case
detail Deep engagement with product page (scroll depth, time on page, viewing specs)
add to observation Wishlist additions, "save for later", product comparisons
remove Item removed from cart (useful for cart recovery segmentation)

For complete product event documentation, see Tracking Product Events.

# Verification

After implementing product event tags:

  1. GTM Preview mode: Verify tags fire on expected GA4 triggers
  2. Network tab: Filter for requests to /api/product_event/ — each should return 200 OK
  3. Product records: Check Data → Products to confirm events associate with correct catalog items
  4. Contact timeline: Verify product events appear in visitor timelines

# Next steps

With product events implemented:

← Custom events →