Shopify · GTM container configuration

Important limits (read first)#

Running GTM inside the Shopify Custom Pixel (Web Pixel) sandbox is not supported:

• Since 2025 Shopify removed the ability to paste third-party tags in custom HTML/Scripts; all third-party pixels must use Custom Pixels (sandboxed execution)
• Google's documentation explicitly does not recommend running GTM or Google tags inside the Custom Pixel sandbox — the sandbox delays and drops events, and Google does not support troubleshooting it
• The sandbox cannot access the page DOM: scroll depth, file downloads, outbound clicks, affiliate detection and DOM-based form submission are unavailable in a pure Custom Pixel setup

Prerequisites#

1. Shopify admin access (Settings → Customer events)
2. A GA4 measurement ID (G-XXXXXXXXXX)
3. A GTM container (for local preview / QA, or as a future GA4 configuration hop)

Configure a Custom Pixel to push the dataLayer#

1. Shopify admin → Settings → Customer events
2. Click Add custom pixel and name it e.g. metricsKit
3. Paste the code and save

import { register } from '@shopify/web-pixels-extension';

register(async (analytics) => {
  const browser = analytics.browser;

  analytics.subscribeAll((event) => {
    switch (event.name) {
      case 'payment_info_submitted':
        browser.dataLayer.push('event', 'add_payment_info');
        break;
      case 'checkout_address_info_submitted':
        browser.dataLayer.push('event', 'add_shipping_info');
        browser.dataLayer.push('event', 'view_item_list');
        break;
      case 'product_viewed':
        browser.dataLayer.push('event', 'view_item', {
          ecommerce: { items: [toItem(event.data)] }
        });
        break;
      case 'product_added_to_cart':
        browser.dataLayer.push('event', 'add_to_cart', {
          ecommerce: { items: [toItem(event.data)] }
        });
        break;
      case 'checkout_started':
        browser.dataLayer.push('event', 'begin_checkout');
        break;
      case 'checkout_completed':
        browser.dataLayer.push('event', 'purchase', {
          ecommerce: { transaction_id: event.data.checkout.id }
        });
        break;
    }
  });

  function toItem(d) {
    return {
      item_id: d.productVariant.id,
      item_name: d.productVariant.title,
      price: d.productVariant.price.amount,
      currency: d.productVariant.price.currencyCode
    };
  }
});

Getting events to GA4#

• Option A (recommended): Shopify's official Google & YouTube app. Install from the App Store and connect your GA4 property — Shopify's only official path since 2025, with complete events and support
• Option B: Measurement Protocol (advanced). Fetch the GA4 Measurement Protocol endpoint directly from the Custom Pixel (requires your own api_secret; for teams with development capacity)

On Shopify the GTM container only serves "preview / local QA": temporarily load the container in the theme to validate event parameters; production collection does not depend on GTM.

GTM container configuration items (Shopify-usable subset)#

If you configure on the GTM side, the container entities match the standard list, but the Shopify sandbox blocks DOM access, so only the ecommerce items apply (the rest are WordPress-only or unavailable):

The complete container configuration is as follows (identical to what the metricsKit "Import file" creates): 2 custom JavaScript variables, 4 data-layer variables, 9 triggers and 10 tags. Every tag is of type "Google Analytics: GA4 Event", using the site's bound GA4 measurement ID.

Import file structure example#

{
  "containerVersion": {
    "path": "accounts/0000000/containers/0000000/versions/0",
    "name": "metricsKit Tracking (example.com)",
    "trigger": [
      { "triggerId": "100", "name": "metricsKit - Form Submission",
        "type": "FORM_SUBMISSION", "fingerprint": "" },
      { "triggerId": "101", "name": "metricsKit - Outbound Click",
        "type": "LINK_CLICK", "fingerprint": "",
        "waitForTags": { "type": "TEMPLATE", "value": "2000" },
        "waitForTagsTimeout": { "type": "TEMPLATE", "value": "2000" },
        "checkValidation": { "type": "BOOLEAN", "value": "false" } },
      { "triggerId": "104", "name": "metricsKit - Ecommerce Purchase",
        "type": "CUSTOM_EVENT", "fingerprint": "",
        "customEventFilter": [{ "type": "EQUALS", "parameter": [
          { "type": "TEMPLATE", "key": "arg0", "value": "{{_event}}" },
          { "type": "TEMPLATE", "key": "arg1", "value": "purchase" } ] }] }
    ],
    "variable": [
      { "name": "mk - Affiliate Detector", "type": "jsm", "fingerprint": "",
        "parameter": [{ "type": "TEMPLATE", "key": "javascript",
          "value": "function(){ /* generated from your AFF patterns, per-site */ }" }] },
      { "name": "dlv - ecommerce.value", "type": "v", "fingerprint": "",
        "parameter": [{ "type": "TEMPLATE", "key": "name", "value": "ecommerce.value" }] }
    ],
    "tag": [
      { "tagId": "200", "name": "metricsKit - GA4 Event - Ecommerce Purchase",
        "type": "gaawe", "fingerprint": "",
        "parameter": [
          { "type": "TEMPLATE", "key": "measurementIdOverride", "value": "G-XXXXXXXXXX" },
          { "type": "TEMPLATE", "key": "eventName", "value": "purchase" },
          { "type": "TEMPLATE", "key": "value", "value": "{{dlv - ecommerce.value}}" },
          { "type": "TEMPLATE", "key": "items", "value": "{{dlv - ecommerce.items}}" } ],
        "firingTriggerId": ["104"] }
    ]
  }
}

Event mapping quick reference#

Customer event → dataLayer / GA4 event name:

Verification#

1. Shopify admin → Settings → Customer events; confirm the pixel is Connected
2. Place a test order (Shopify Bogus Gateway or another test payment)
3. The purchase event appears in GA4 Realtime after about 5-30 minutes
4. Verify data in the metricsKit ecommerce attribution report after 24-48 hours

References#

• Shopify Customer events: help.shopify.com/en/manual/promoting-marketing/pixels/customer-events
• Google & YouTube app (official Shopify integration): help.shopify.com/en/manual/promoting-marketing/pixels/google
• Shopify Web Pixel extension: shopify.dev/docs/api/web-pixels-extension
• Google's note on why GTM is unsupported in the sandbox: support.google.com/tagmanager/answer/16000892