How to Add Custom Events in Shopify (2026)

Key takeaways

• Shopify’s Customer Events API (Settings → Customer events → Add custom pixel) is the right place for custom event tracking.
• Standard Shopify events include page_viewed, product_viewed, product_added_to_cart, and checkout_completed.
• Custom pixels run in a sandboxed environment with access to all checkout events - something theme.liquid scripts can’t do.
• You write standard JavaScript inside the custom pixel editor - no Shopify-specific syntax required.

Custom event tracking tells you what shoppers actually do on your store — not just which pages they visit, but when they add products to their cart, start checkout, or reach your thank-you page. Shopify’s Customer Events API makes this trackable without digging into theme code.

How do I add events in Shopify?

Go to Settings → Customer events → Add custom pixel. This opens a JavaScript editor where you write code that listens to Shopify’s standard events and fires your own tracking code in response.

Shopify’s standard events

Shopify exposes a set of standard events across the shopping journey. Your custom pixel can listen to any of them:

Page events:

• page_viewed — fires on every page load

Product events:

• product_viewed — fires when a product page is viewed
• product_added_to_cart — fires when an item is added to the cart
• search_submitted — fires when a search query is submitted

Checkout events:

• checkout_started — fires when checkout begins
• checkout_address_info_submitted — fires when address is entered
• checkout_shipping_info_submitted — fires when shipping method is selected
• payment_info_submitted — fires when payment info is entered
• checkout_completed — fires on the order confirmation page
• order_created — fires when an order is successfully placed

These events come with contextual data — the product that was viewed, the cart value at checkout start, the order total at completion.

Writing a custom pixel

Here’s a basic example that sends a GA4 event when a product is added to cart:

analytics.subscribe('product_added_to_cart', (event) => {
  const cartLine = event.data.cartLine;

  // Send to GA4 via dataLayer (if GTM is installed)
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({
    event: 'add_to_cart',
    ecommerce: {
      currency: cartLine.merchandise.product.vendor,
      items: [{
        item_id: cartLine.merchandise.sku,
        item_name: cartLine.merchandise.product.title,
        price: cartLine.cost.totalAmount.amount,
        quantity: cartLine.quantity
      }]
    }
  });
});

And for a Meta Pixel purchase event on checkout completion:

analytics.subscribe('checkout_completed', (event) => {
  const order = event.data.checkout;

  fbq('track', 'Purchase', {
    value: order.totalPrice.amount,
    currency: order.currencyCode,
    content_ids: order.lineItems.map(item => item.variant.sku),
    content_type: 'product'
  });
});

Important: The analytics.subscribe() function is provided by Shopify’s sandbox environment. You don’t need to import it — it’s available automatically in all custom pixels.

Setting up a custom pixel step by step

Step 1 - Go to Settings → Customer events

Step 2 - Click Add custom pixel

Step 3 - Give it a name (e.g., “GA4 Custom Events” or “Meta Purchase Event”)

Step 4 - In the Code section, write your JavaScript using analytics.subscribe()

Step 5 - Set the Customer privacy permission level:

• Not required — fires for all visitors regardless of consent
• Preferences — requires analytics consent
• Analytics — requires analytics consent
• Marketing — requires marketing consent

For purchase tracking, select “Marketing” if you’re sending to ad platforms, or “Analytics” for GA4.

Step 6 - Click Save then Connect

Testing your custom pixel

Shopify’s built-in debugger. In the Customer Events editor, there’s a live event feed that shows events firing in real time. Open your storefront in another tab and browse around — you should see page_viewed events appear immediately.

Browser console. Because custom pixels run in a sandboxed iframe, you can’t see their console.log output directly. Use Shopify’s debugger panel instead.

GA4 DebugView. In your GA4 property, go to Configure → DebugView. Trigger events on your storefront and watch them appear in real time.

Custom events vs. standard app integrations

Shopify has pre-built integrations for Google Analytics, Google Ads, Meta, TikTok, Snapchat, and others in the Customer events section. These handle standard purchase tracking automatically.

Use custom pixels when:

• You need to track events the standard integration doesn’t cover (e.g., specific button clicks, scroll depth, custom funnel steps)
• You need to send events to a less common analytics platform
• You want to send additional custom data with standard events (e.g., customer lifetime value, product category)

For most stores, the standard integrations cover 80% of needs. Custom pixels fill the gaps.