PennyLens
Get Started

Shopify

PennyLens auto-detects Shopify stores — including Shopify Plus, hydrogen-fronted storefronts, and the standard Online Store 2.0 themes. Drop the SDK snippet onto your storefront and cart_add, checkout_started, and purchase start flowing without any further wiring.

This page covers what auto-detect actually does, what to expect on Shopify's hosted checkout, and how to recover when events aren't flowing.

When auto-detect activates

When the SDK loads, it checks three signals. Any single positive enables the Shopify hooks:

  • window.Shopify global — present on virtually every Shopify storefront, including custom-coded themes and headless setups that ship with the Shopify JS.
  • A /cdn/shopify or /cdn/shopifycloud/ script tag — catches Shopify's core scripts even when the global is unavailable (rare CSP setups).
  • A template-* body class (e.g. template-product, template-cart, template-checkout) — set by all stock Dawn-derived themes via the standard theme layout.

The check runs cheapest-first, short-circuits on the first positive, and silently no-ops on non-Shopify sites. The auto-detect logic ships in the core 8 KB SDK bundle.

Cart events

PennyLens intercepts the Shopify Ajax Cart API to capture cart_add without any theme modification:

  • /cart/add.js (and the GraphQL Storefront equivalent on hydrogen sites) — every line item added to the cart emits a cart_add event with product_id, variant_id, quantity, and the line total.
  • /cart/update.js and /cart/change.js — quantity edits and removals update the cart-state model used for abandonment analysis, but don't emit duplicate cart_add events.

Exactly one network-level interceptor is installed per page, shared with any other PennyLens e-commerce integration to avoid stacking patches.

Checkout and purchase

Shopify's checkout runs on Shopify-owned domains (or a checkout.* subdomain on Plus). Cross-domain JavaScript can't follow the user there, so PennyLens uses two anchor pages:

  • checkout_started — emitted when the customer lands on /checkout on your storefront, or when they click the standard checkout button on /cart. The event includes cart_value and item_count from the captured cart state.
  • purchase — emitted when the order status page (/thank_you / /orders/*/authentication) loads. The event includes order_id, total, currency, and tax. On Shopify Plus stores with custom checkout extensions, an additional Web Pixel app event (checkout_completed) is captured as a backup signal.

For per-customer attribution, install the PennyLens Web Pixel from the Shopify app store. Without it, purchases still capture but customer identity is anonymous beyond the order ID.

Mutual exclusion with WooCommerce

If both Shopify and WooCommerce signals appear on the same page — usually only on agency development sites — Shopify takes precedence and the WooCommerce auto-hook silently no-ops. Manual wiring still works on dual-signal sites.

Zero-event fallback

If 24 hours after install you don't see any events in the PennyLens dashboard, walk through these in order:

  1. Confirm the SDK is loaded. Open your storefront's browser developer console and run window.PennyLens. It should be defined. If it isn't, check that the snippet is in your theme's theme.liquid <head> block — not just on /products/* pages.
  2. Confirm Shopify is detected. In the same console, run window.Shopify. It should be a non-null object. If it's undefined, your theme has stripped the standard Shopify JS — fall back to manual wiring.
  3. Check the Web Pixel app (Shopify Plus only). If the dashboard shows cart_add events but no purchase events, the order status page redirect may be skipping the standard /thank_you route. Install the PennyLens Web Pixel from the Shopify app store to capture purchases directly through Shopify's events API.
  4. Headless storefronts. Hydrogen and other custom storefronts that don't render the standard Shopify body classes or load /cdn/shopify scripts won't trigger auto-detect. Use the manual snippet in the SDK reference — same API as any custom event.

Confidence indicator

Once at least one cart_add or purchase event has arrived, the dashboard Overview displays a confidence badge above the KPI row:

Shopify detected — 1,247 events captured

The badge is informational — no action required when it appears. If you don't see it after 24 hours, return to the Zero-event fallback above.

Manual wiring

If your storefront falls outside the auto-detect signals — headless hydrogen sites, custom-coded themes that strip Shopify's standard globals, or storefronts behind a CDN that hides Shopify origin scripts — wire the events manually:

pennylens.track("cart_add", {
  product_id: 7281928392,
  variant_id: 41827382,
  qty: 1,
  total: 49.0,
  currency: "USD",
});

Same API as any custom event. See Event Tracking for the full reference.

Next steps