Shopify installation

11 min

This guide covers adding Chord event tracking to any Shopify store — Liquid themes, Hydrogen, or custom headless storefronts. The setup has three parts:

Add @chordcommerce/analytics to your storefront — loads the tracking library on your site

Add the custom web pixel in Shopify Admin — tracks checkout events and, for Liquid themes, storefront events

Enable server event tracking via webhooks — tracks server-side events such as order creations and order refunds

Adding all three elements ensures that all events, from browsing through checkout — including on Shopify's hosted checkout pages, are tracked in Chord.

Due to technical limitations within Shopify, the Chord analytics package does not load on Shop Pay pages.

Prerequisites

Before starting, ensure you have the values listed in Getting Started.

How it works

Chord tracking on Shopify uses two components that work together:

@chordcommerce/analytics runs on your storefront pages and sends tracking events to Chord. It also loads any device-mode destination scripts (such as Google Analytics or Meta Pixel) directly in the browser. Additionally, it listens for events forwarded from the custom web pixel.

The custom web pixel runs within Shopify's event system, where it subscribes to all customer events (page views, add-to-cart, checkout steps, order completion). For storefront events, the web pixel forwards them to a listener on the top window within @chordcommerce/analytics, which processes the event and delivers it to Chord and any configured destinations (device-mode and cloud-mode). For checkout events that occur on Shopify-hosted pages, the web pixel sends them directly to Chord via cloud mode.

This architecture ensures complete event coverage — storefront interactions, Shopify-hosted checkout pages, and post-purchase events are all captured through a single, unified pipeline.

Note: Due to technical limitations in Shopify, device-mode destinations (scripts that run in the browser) cannot be loaded or executed on Shopify-hosted pages. These pages include:

Checkout

Order status

Thank you page

Events on these pages are delivered exclusively via cloud mode. Storefront pages are not affected — device-mode destinations load and execute normally there.

Step 1: Add @chordcommerce/analytics to Your Storefront

Option A: Liquid Theme

For stores using a standard Shopify Liquid theme, add the Chord analytics snippet to your theme.

In your Shopify Admin, go to Online Store > Themes > Edit code.

Create a new snippet called chord.liquid and paste the following:

{% comment %} //Instantiates analytics-liquid-identifiers, which handles reading/parsing of Cookies to Shopify cart attributes {% endcomment %}
  <script
    src='https://cdn.chord.co/analytics-liquid-identifiers/v1/analytics-liquid-identifiers.min.js'
    defer='defer'
  ></script>

{% comment %} //Instantiates Chord Analytics {% endcomment %}
<script type="module">
  import { ChordAnalytics } from 'https://cdn.jsdelivr.net/npm/@chordcommerce/[email protected]/+esm'

  window.chord = new ChordAnalytics({
    cdpDomain: 'https://production.cdp.ingest.chord.co',
    cdpWriteKey: 'your-chord-write-key',
    enableLogging: false,
    consent: null, // set to 'shopify' | 'onetrust' | 'ketch' | 'segment' to enable consent management
    awaitConsent: false, // when true, blocks all events until the consent provider confirms the user can be tracked
    formatters: {
      objects: {
        cart: (props) => props.cart,
        checkout: (props) => props.checkout,
        lineItem: (props) => props.lineItem,
        product: (props) => props.product,
      },
    },
    metadata: {
      i18n: {
        currency: {{ cart.currency.iso_code | default: 'USD' | json }},
        locale: "{{ localization.language.iso_code | default: 'en' }}-{{ localization.country.iso_code | default: 'US' }}",
      },
      ownership: {
        omsId: 'your-oms-id',
        storeId: 'your-store-id',
        tenantId: 'your-tenant-id',
      },
      platform: {
        name: 'shopify',
        type: 'web',
      },
      store: {
        domain: 'your-store-slug',
      },
    },
  })
</script>

In layout/theme.liquid, add the following before the closing </body> tag:

{% render 'chord' %}

Option B: Hydrogen / Headless Storefront

For Hydrogen or other JavaScript-based storefronts, install the npm package.

Install the package:

Initialize the library in your root layout or app entry point:

Add your environment variables:

See Configuration for the full list of options, and SDK API Reference for tracking methods you can call from your storefront code.

Step 2: Add the Custom Web Pixel

The custom web pixel subscribes to all Shopify customer events and tracks events on Shopify-hosted pages, such as checkout. Specifically for each platform:

Liquid themes: All storefront and checkout tracking

Headless storefronts: Checkout tracking only (storefront events are handled by your SDK integration in Step 1)

Installation

In your Shopify Admin, go to Settings > Customer events.

Click Add custom pixel.

Name the pixel (e.g., "Chord").

Paste the web pixel code provided by the Chord team. The code includes configuration constants at the top that must be filled in:

Under Customer privacy, select Does not require consent (consent is managed by @chordcommerce/analytics — see Consent Management).

Click Save, then click Connect to activate the pixel.

Verifying the Installation

After installing both components, open your browser's developer console and verify:

On a storefront page (e.g., a product page): You should see Chord network requests when browsing products, adding to cart, etc.

On the checkout page: Checkout events (Checkout Started, Payment Info Entered, Order Completed) should appear in your Chord Live Events view.

Tip: Set debug: true in your @chordcommerce/analytics configuration during development. This validates events against the tracking plan and logs warnings for missing or incorrect properties

Step 3: Enable Server Event Tracking

In addition to front-end tracking, Chord can receive server-side events from Shopify via webhooks. This enables tracking for events that occur outside the browser, such as order refunds.

See Shopify server event trackingShopify server event tracking for setup instructions.

Troubleshooting

Events not appearing in Chord

Verify the Domain and Write Key are correct in both the analytics library and the web pixel.

Check the browser console for error messages from Chord.

Ensure the web pixel status is "Connected" in Shopify Admin > Customer events.

Storefront events missing (Liquid themes)

Confirm {% render 'chord' %} is in your theme.liquid layout.

Check the browser console for script loading errors from jsdelivr.

Checkout events missing

Verify the web pixel is connected (not just saved) in Shopify Admin.

Check that the credentials in the web pixel match your analytics library configuration.