Ecwid Analytics Integrations: Setup Guide

Set up analytics and tracking tools on your Ecwid store to measure traffic, understand buyer behavior, and attribute revenue to the right channels. Ecwid supports native integrations for several platforms, but the embedded store architecture introduces tracking challenges that standard ecommerce platforms do not have. This guide covers everything from basic setup to advanced JavaScript API usage.

Available Integration Guides

Google Analytics 4

Set up GA4 on your Ecwid store to track visitor behavior, product interactions, and ecommerce conversions. Includes enhanced ecommerce event mapping and custom dimension configuration.

GA4 Ecommerce Tracking

Implement full enhanced ecommerce tracking with product impressions, add-to-cart events, checkout funnel steps, and purchase attribution.

Google Tag Manager

Centralize all tracking tags through GTM. Requires Ecwid Business plan or higher. Covers container setup, data layer variables, and tag firing for embedded stores.

Meta Pixel

Track Facebook and Instagram ad conversions with the Meta Pixel. Configure standard ecommerce events like ViewContent, AddToCart, and Purchase.

Built-In Integrations

Ecwid provides native tracking integrations that you can enable directly from the admin panel without writing any code:

• Google Analytics 4 -- Enhanced ecommerce with automatic event firing
• Meta Pixel (Facebook) -- Standard and custom conversion events
• Pinterest Tag -- Product catalog and conversion tracking
• TikTok Pixel -- View content, add to cart, and purchase events
• Google Ads Conversion Tracking -- Conversion value and transaction IDs
• Snapchat Pixel -- Available through the Ecwid App Market

For any integration not listed above, you can add custom tracking code through the JavaScript API (Business plan or higher) or use GTM to deploy tags manually.

GA4 Setup Step by Step

Adding Your Measurement ID

1. Open your Ecwid admin panel at my.ecwid.com
2. Navigate to Settings in the left sidebar
3. Click General then scroll to the Tracking & Analytics section
4. In the Google Analytics field, enter your GA4 Measurement ID (format: G-XXXXXXXXXX)
5. Check the box for Enable Enhanced Ecommerce
6. Click Save

After saving, Ecwid injects the GA4 gtag.js snippet and fires ecommerce events automatically on every storefront page load, including embedded stores.

Automatic Enhanced Ecommerce Events

When you enable enhanced ecommerce, Ecwid fires the following GA4 events without any custom code:

These events populate the Monetization reports in GA4 automatically. You can view them under Reports > Monetization > Ecommerce purchases.

Verifying Events in GA4 DebugView

After enabling tracking, confirm that events are firing correctly:

1. In GA4, go to Admin > DebugView
2. Open your Ecwid store in a new browser tab
3. Browse products, add items to cart, and start a checkout
4. Watch for events appearing in the DebugView timeline
5. Click each event to inspect its parameters and confirm that items[] arrays contain product data

If events are not appearing, check that your Measurement ID is entered correctly and that you do not have an ad blocker active during testing.

GTM Setup (Business Plan Required)

Google Tag Manager gives you full control over which tags fire, when they fire, and what data they receive. Ecwid restricts GTM access to Business plan subscribers and above because it requires custom JavaScript execution.

Adding Your GTM Container

1. Go to Ecwid Admin > Settings > General
2. Scroll to Google Tag Manager
3. Enter your GTM Container ID (format: GTM-XXXXXXX)
4. Click Save

Ecwid injects the GTM container snippet into every storefront page. This works on both Ecwid Instant Sites and embedded storefronts on external domains.

Ecwid Data Layer Variables

When GTM is active, Ecwid pushes data to window.dataLayer for storefront events. You can capture these in GTM by creating Data Layer Variables for:

• ecwid_page_type -- The current page type (CATEGORY, PRODUCT, CART, CHECKOUT_ADDRESS, etc.)
• ecwid_product_id -- The product ID on product detail pages
• ecwid_product_name -- Product name on detail pages
• ecwid_cart_total -- Current cart value
• ecwid_cart_items_count -- Number of items in the cart

Create these as Data Layer Variable type in GTM under Variables > User-Defined Variables. Then reference them in your tag configurations.

Tag Firing Sequence for Embedded Stores

When Ecwid is embedded on an external site, the GTM container loads with the host page but the Ecwid storefront initializes asynchronously. This means tags that depend on Ecwid data must wait for the storefront to be ready. Configure your triggers to fire on custom ecwid_page_load events rather than the standard GTM page view trigger.

Create a Custom Event trigger in GTM:

• Event name: ecwid_page_load
• Fire on: All custom events

Then use Ecwid's JavaScript API to push that event when the storefront is ready:

Ecwid.OnPageLoaded.add(function(page) {
  dataLayer.push({
    'event': 'ecwid_page_load',
    'ecwid_page_type': page.type,
    'ecwid_page_name': page.name || ''
  });
});

Why You Need the Business Plan

Ecwid locks GTM and custom JavaScript behind the Business plan because these features allow arbitrary code execution on the storefront. The Venture plan supports only native integrations (GA4, Meta Pixel) through the admin panel fields. If you need GTM for consent management, A/B testing tools, or multiple ad platform pixels, you must upgrade to Business or Unlimited.

Cross-Domain Tracking

Ecwid presents a unique cross-domain challenge. When you embed an Ecwid store on your own domain, the checkout process can redirect through app.ecwid.com before returning to your order confirmation page. This domain hop breaks session continuity in GA4 unless you configure cross-domain tracking.

The Embedded Store Problem

A typical flow looks like this:

1. Visitor browses products on yoursite.com (your domain with embedded Ecwid)
2. Visitor clicks checkout, which loads app.ecwid.com/... for payment processing
3. After payment, visitor lands on the order confirmation back on yoursite.com

Without cross-domain tracking, GA4 treats steps 1 and 3 as separate sessions. The purchase event in step 3 gets attributed to app.ecwid.com as the referral source instead of the original traffic source.

GA4 Cross-Domain Linker Configuration

1. In GA4, go to Admin > Data Streams > Web > Configure tag settings
2. Click Configure your domains under the Settings section
3. Add these domains:
   • yoursite.com (your main domain)
   • app.ecwid.com
   • store.ecwid.com (if using Ecwid Instant Site)
4. Save the configuration

This tells GA4 to append the _gl linker parameter when navigating between these domains, preserving the client ID and session data across the domain boundary.

Referral Exclusions

You should also exclude Ecwid domains from triggering new sessions:

1. In GA4, go to Admin > Data Streams > Web > Configure tag settings
2. Click List unwanted referrals
3. Add ecwid.com as a domain to exclude
4. Save

This prevents the checkout redirect from appearing as a referral source in your acquisition reports.

Testing Cross-Domain Tracking

After configuration, test the full purchase flow:

1. Enable GA4 DebugView
2. Start on your embedded store page
3. Add a product to cart and proceed to checkout
4. Complete a test purchase
5. In DebugView, confirm that the purchase event shares the same session ID as the initial page_view event on your domain

Plan Requirements

The free plan does not support any tracking integrations. You must be on at least the Venture plan to add a GA4 Measurement ID.

Ecwid JavaScript API for Custom Tracking

The Ecwid Storefront JavaScript API provides event hooks that let you execute custom tracking code at key moments in the shopping experience. This is the foundation for any tracking implementation that goes beyond the native integrations.

All API code goes in Ecwid Admin > Settings > General > Tracking & Analytics > Custom JavaScript Code or is deployed via GTM on the Business plan.

Available Event Hooks

Ecwid.OnAPILoaded

Fires once when the Ecwid JavaScript API is fully initialized. Use this as the entry point for all tracking setup:

Ecwid.OnAPILoaded.add(function() {
  console.log('Ecwid API ready - initializing tracking');
  // Initialize all event listeners here
});

Ecwid.OnPageLoaded

Fires every time the storefront navigates to a new page. The page object contains the page type and relevant IDs:

Ecwid.OnPageLoaded.add(function(page) {
  dataLayer.push({
    'event': 'ecwid_page_load',
    'ecwid_page_type': page.type,
    'ecwid_product_id': page.productId || null,
    'ecwid_category_id': page.categoryId || null
  });
});

The page.type value is one of: CATEGORY, PRODUCT, CART, CHECKOUT_ADDRESS, CHECKOUT_SHIPPING, CHECKOUT_PAYMENT, ORDER_CONFIRMATION, SEARCH, ACCOUNT_ROOT, FAVORITES.

Ecwid.OnCartChanged

Fires whenever the cart contents change, including adds, removes, and quantity updates:

Ecwid.OnCartChanged.add(function(cart) {
  dataLayer.push({
    'event': 'ecwid_cart_change',
    'cart_total': cart.total,
    'cart_items_count': cart.items.length,
    'cart_items': cart.items.map(function(item) {
      return {
        id: item.product.id,
        name: item.product.name,
        price: item.price,
        quantity: item.quantity
      };
    })
  });
});

Ecwid.OnOrderPlaced

Fires when a customer completes a purchase. The order object contains the full transaction details:

Ecwid.OnOrderPlaced.add(function(order) {
  dataLayer.push({
    'event': 'ecwid_order_placed',
    'transaction_id': order.vendorOrderNumber,
    'order_total': order.total,
    'order_tax': order.tax,
    'order_shipping': order.shippingOption ? order.shippingOption.shippingRate : 0,
    'order_currency': order.currency,
    'order_items': order.items.map(function(item) {
      return {
        id: item.product.id,
        name: item.product.name,
        price: item.price,
        quantity: item.quantity,
        sku: item.product.sku || ''
      };
    })
  });
});

Ecwid.OnSetProfile

Fires when customer profile data becomes available (logged-in customers):

Ecwid.OnSetProfile.add(function(profile) {
  dataLayer.push({
    'event': 'ecwid_profile_set',
    'customer_id': profile.id,
    'customer_email': profile.email
  });
});

Combining Hooks for Full Funnel Tracking

Here is a complete example that pushes all key events to the dataLayer for GTM consumption:

Ecwid.OnAPILoaded.add(function() {

  // Track all page navigations
  Ecwid.OnPageLoaded.add(function(page) {
    dataLayer.push({
      'event': 'ecwid_page_load',
      'ecwid_page_type': page.type
    });
  });

  // Track cart changes with add/remove detection
  var previousItemCount = 0;
  Ecwid.OnCartChanged.add(function(cart) {
    var currentCount = cart.items.length;
    var action = currentCount > previousItemCount ? 'add' :
                 currentCount < previousItemCount ? 'remove' : 'update';
    dataLayer.push({
      'event': 'ecwid_cart_' + action,
      'cart_total': cart.total,
      'cart_items_count': currentCount
    });
    previousItemCount = currentCount;
  });

  // Track completed orders
  Ecwid.OnOrderPlaced.add(function(order) {
    dataLayer.push({
      'event': 'ecwid_purchase',
      'transaction_id': order.vendorOrderNumber,
      'value': order.total,
      'currency': order.currency
    });
  });
});

Common Pitfalls

iFrame Isolation Breaking Tracking

When Ecwid is embedded on an external site, the storefront renders inside an iFrame in some configurations. Tags deployed on your host page cannot access the Ecwid iFrame DOM, and JavaScript running inside the iFrame cannot access the parent page's dataLayer. If your GA4 events are not firing on the embedded store, confirm that you added your tracking code through the Ecwid admin panel's custom JavaScript field rather than injecting it into your host page's HTML.

The window.ec vs Ecwid Object Confusion

Ecwid exposes two global objects: window.ec (configuration object set before the storefront loads) and Ecwid (the runtime API available after initialization). A common mistake is trying to use Ecwid.OnPageLoaded before the API has loaded. Always wrap API calls inside Ecwid.OnAPILoaded.add() or check that the Ecwid object exists before referencing it.

// Wrong - may fail if Ecwid hasn't loaded yet
Ecwid.OnPageLoaded.add(function(page) { /* ... */ });

// Correct - waits for API to be ready
Ecwid.OnAPILoaded.add(function() {
  Ecwid.OnPageLoaded.add(function(page) { /* ... */ });
});

The window.ec object is used for pre-initialization configuration like setting the store ID:

window.ec = window.ec || {};
window.ec.config = window.ec.config || {};
window.ec.config.storefrontUrls = window.ec.config.storefrontUrls || {};
window.ec.config.storefrontUrls.cleanUrls = true;

Do not confuse the two. window.ec is for configuration. Ecwid is for event listeners and runtime API calls.

Missing Events on Instant Site vs Embedded Store

Ecwid Instant Sites (hosted at yourstore.ecwid.com or a custom domain) and embedded stores on external sites behave differently for tracking. On Instant Sites, the GA4 snippet loads with the page and fires normally. On embedded stores, the storefront loads asynchronously after the host page, so standard GTM page view triggers miss the initial storefront load. Always use Ecwid.OnPageLoaded events as your trigger source for embedded stores rather than relying on the host page's DOM ready event.

Lightspeed Migration Impact on Tracking

Ecwid was acquired by Lightspeed in 2021, and some admin panel paths and API endpoints have changed during the platform migration. If you are following an older tutorial that references Ecwid Control Panel paths, look for the equivalent in the current Lightspeed-branded admin at my.ecwid.com. The JavaScript API (Ecwid.OnPageLoaded, Ecwid.OnCartChanged, etc.) has remained stable through the migration. Tracking codes entered through the old admin panel are preserved, but double-check that they are still active after any account migration.

Duplicate Event Firing

If you enable the native GA4 integration in the Ecwid admin AND deploy your own GA4 tags via GTM or custom JavaScript, every ecommerce event fires twice. Choose one method: either use the native integration for zero-code setup, or disable it and handle all event firing through GTM. Do not use both simultaneously.

Next Steps

• GA4 Ecommerce Tracking -- Full enhanced ecommerce implementation with code examples
• GTM Data Layer Setup -- Configure GTM variables and triggers for Ecwid
• Meta Pixel Setup -- Facebook and Instagram conversion tracking
• Events Not Firing -- Debug tracking issues on Ecwid stores
• CLS Troubleshooting -- Fix layout shift caused by Ecwid widget loading