---
title: Shopify installation
slug: shopify-installation
docTags: 
createdAt: 2026-03-09T17:25:14.192Z
---

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

1. **Add **`@chordcommerce/analytics`** to your storefront** — loads the tracking library on your site
2. **Add the custom web pixel in Shopify Admin** — tracks checkout events and, for Liquid themes, storefront events
3. **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.

:::hint{type="warning"}
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:

1. `@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.
2. **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.

:::hint{type="info"}
**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.

1. In your Shopify Admin, go to **Online Store > Themes > Edit code**.
2. Create a new snippet called `chord.liquid` and paste the following:

:::CodeblockTabs{indent="1"}
```javascript
{% 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/analytics@1.23.1/+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>

```
:::

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

:::CodeblockTabs{indent="1"}
```javascript
{% render 'chord' %}
```
:::

### Option B: Hydrogen / Headless storefront

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

1. Install the package:
2. Initialize the library in your root layout or app entry point:
3. 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

1. In your Shopify Admin, go to **Settings > Customer events**.
2. Click **Add custom pixel**.
3. Name the pixel (e.g., "Chord").
4. Paste the web pixel code provided by the Chord team. The code includes configuration constants at the top that must be filled in:
5. Under **Customer privacy**, select **Does not require consent** (consent is managed by `@chordcommerce/analytics` — see [Consent Management](#)).
6. Click **Save**, then click **Connect** to activate the pixel.

### Verifying the installation

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

1. **On a storefront page** (e.g., a product page): You should see Chord network requests when browsing products, adding to cart, etc.
2. **On the checkout page**: Checkout events (Checkout Started, Payment Info Entered, Order Completed) should appear in your Chord Live Events view.

:::hint{type="info"}
**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 tracking](docId\:xbL7zBqE14BT7gbTMl0un) for setup instructions.



## Step 4: Install Chord's data ingestor app

In addition tracking, Chord also requires the ability to ingest Shopify data in order to read historical transactional information.

See [Chord Data ingestor app](https://docs.chord.co/chord-data-ingestor-app) 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.