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.

To add custom events in Shopify, go to Settings → Customer events → Add custom pixel and write JavaScript that subscribes to Shopify’s standard events with analytics.subscribe(). That tells you what shoppers do on your store: when they add products to their cart, start checkout, or reach your thank-you page, 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
• collection_viewed - fires when a collection page is viewed
• cart_viewed - fires when the cart page is viewed

Product events:

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

Checkout events:

• checkout_started - fires when checkout begins
• checkout_contact_info_submitted - fires when contact details are entered
• 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

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

For the checkout.liquid tracking these events replace, see Migrating From checkout.liquid to Checkout Extensions.

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

    // Push to the dataLayer of a GTM container loaded inside this pixel
    window.dataLayer = window.dataLayer || []
    window.dataLayer.push({
        event: 'add_to_cart',
        ecommerce: {
            currency: cartLine.cost.totalAmount.currencyCode,
            items: [
                {
                    item_id: cartLine.merchandise.sku,
                    item_name: cartLine.merchandise.product.title,
                    price: cartLine.merchandise.price.amount,
                    quantity: cartLine.quantity,
                },
            ],
        },
    })
})

And for a Meta Pixel purchase event on checkout completion. Load the Meta Pixel base code at the top of the same custom pixel so fbq exists:

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.

Browser-side Meta events like this one get filtered by ad blockers and iOS privacy settings, so pair them with server-side tracking - see Shopify Meta Conversions API setup for that half.

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 preferences 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

For the other ways to add tracking code, see How to Add Tracking Scripts to Shopify.

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.

FAQ