---
title: Shopify (RUM)
description: Monitor Shopify storefront and checkout pages using Datadog RUM
breadcrumbs: Docs > Integrations > Shopify (RUM)
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Shopify (RUM)
Supported OS Integration version1.0.0
{% callout %}
# Important note for users on the following Datadog sites: us2.ddog-gov.com

{% alert level="info" %}
To find out if this integration is available in your organization, see your [Datadog Integrations](https://app.datadoghq.com/integrations) page or ask your organization administrator.

To initiate an exception request to enable this integration for your organization, email [support@ddog-gov.com](mailto:support@ddog-gov.com).
{% /alert %}

{% /callout %}

## Overview{% #overview %}

Instrument your Shopify store with Datadog Real User Monitoring using the Datadog RUM Shopify bundle. One bundle covers both surfaces of a Shopify store:

- **Storefront pages** (`/`, `/products/*`, `/collections/*`, etc.) - added through a Theme Liquid snippet. Full RUM feature set: views, resources, long tasks, user interactions, errors, and Session Replay.
- **Checkout pages** (`/checkouts/*`, `/checkout`) - added through a Custom Pixel. Shopify deprecated `checkout.liquid` in August 2024, so checkout pages cannot be reached by theme edits at all; a [Web Pixel](https://shopify.dev/docs/api/web-pixels-api) running in a sandboxed iframe is the only mechanism that can observe them.

Use both deployment paths together for full-funnel coverage.

## Setup{% #setup %}

### Prerequisites{% #prerequisites %}

Before you begin, gather the following Datadog RUM values:

- A Datadog RUM Application ID
- A Datadog RUM Client Token
- A Datadog site, such as `datadoghq.com`

You can get those values in Datadog under **Digital Experience > Real User Monitoring > Manage Applications > Set Up Manually**.

The snippets below are written for the US1 site. If your organization is on a different [Datadog site](https://docs.datadoghq.com/getting_started/site.md#access-the-datadog-site), substitute both of the following in every snippet:

- `us1` in the bundle URL, with your site's datacenter code (for example `eu1`, `us3`, `us5`, `ap1`).
- `<YOUR_DATADOG_SITE>`, with your site's domain (for example `datadoghq.eu`, `us3.datadoghq.com`).

You'll also need:

- Admin access to your Shopify store (**Settings** and **Online Store > Themes**).
- For the Custom Pixel path: access to **Settings > Customer events** in Shopify Admin.

### Installation and Configuration{% #installation-and-configuration %}

#### Theme Liquid Setup{% #theme-liquid-setup %}

Use this path to cover storefront pages (product, collection, cart, home).

##### Steps{% #steps %}

1. In Shopify Admin, go to **Online Store > Themes**.

1. On your live theme, click the kebab menu, then **Edit code**.

1. Open `layout/theme.liquid`.

1. Initialize the Browser RUM SDK by adding the following snippet inside the `<head>` tag, replacing the placeholder values with your Datadog RUM configuration:

   ```html
   <script>
     (function (h, o, u, n, d) {
       h = h[d] = h[d] || { q: [], onReady: function (c) { h.q.push(c) } }
       d = o.createElement(u); d.async = 1; d.src = n
       d.crossOrigin = 'anonymous'
       n = o.getElementsByTagName(u)[0]; n.parentNode.insertBefore(d, n)
     })(
       window,
       document,
       'script',
       'https://www.datadoghq-browser-agent.com/us1/v7/datadog-rum-shopify.js',
       'DD_RUM'
     );
   
     DD_RUM.onReady(function () {
       DD_RUM.init({
         applicationId: '<YOUR_DATADOG_APPLICATION_ID>',
         clientToken: '<YOUR_DATADOG_CLIENT_TOKEN>',
         site: '<YOUR_DATADOG_SITE>',
         service: '<YOUR_SERVICE_NAME>',
         env: '<YOUR_ENV_NAME>',
         version: '1.0.0',
         sessionSampleRate: 100,
         sessionReplaySampleRate: 100,
         trackUserInteractions: true,
         trackResources: true,
         trackLongTasks: true,
         defaultPrivacyLevel: 'mask-user-input',
       })
       DD_RUM.startSessionReplayRecording()
     })
   </script>
   ```

1. Save the file.

##### Out-of-the-box functionality{% #out-of-the-box-functionality %}

`DD_RUM.init()` here behaves exactly like the regular [`@datadog/browser-rum`](https://github.com/DataDog/browser-sdk/blob/main/packages/rum/README.md) package. You get:

- Automatic view tracking as visitors navigate storefront pages.
- Web Vitals, resource timing, long tasks, and automatic click tracking.
- Session Replay recording.
- Runtime error tracking (`window.onerror`, `unhandledrejection`).

##### Limitations{% #limitations %}

- **No checkout coverage.** Checkout, Thank You / Order Status, and Customer Account pages are fully controlled by Shopify and cannot be reached by any Liquid edit. Use the Custom Pixel Setup below for that funnel.
- Theme code changes require re-editing `theme.liquid` on every theme update or theme switch - there's no install-once mechanism on this path.

#### Custom Pixel Setup{% #custom-pixel-setup %}

Use this path to cover checkout pages (`/checkouts/*`, `/checkout`). It runs inside a Shopify **Custom Pixel**, a sandboxed `<iframe sandbox="allow-scripts allow-forms">` that Shopify injects to observe checkout events - the only place JavaScript can run on checkout pages at all.

##### Steps{% #steps-1 %}

1. In Shopify Admin, go to **Settings > Customer events**.

1. Click **Add custom pixel**, give it a name, and open its code editor.

1. Paste the following snippet, replacing the placeholder values with your Datadog RUM configuration:

   ```javascript
   (function (h, o, u, n, d) {
     h = h[d] = h[d] || { q: [], onReady: function (c) { h.q.push(c) } }
     d = o.createElement(u); d.src = n
     d.crossOrigin = 'anonymous'
     n = o.getElementsByTagName(u)[0]; n.parentNode.insertBefore(d, n)
   })(
     window,
     document,
     'script',
     'https://www.datadoghq-browser-agent.com/us1/v7/datadog-rum-shopify.js',
     'DD_RUM'
   )
   
   DD_RUM.onReady(function () {
     DD_RUM.init({
       applicationId: '<YOUR_DATADOG_APPLICATION_ID>',
       clientToken: '<YOUR_DATADOG_CLIENT_TOKEN>',
       site: '<YOUR_DATADOG_SITE>',
       service: '<YOUR_SERVICE_NAME>',
       env: '<YOUR_ENV_NAME>',
       version: '1.0.0',
       sessionSampleRate: 100,
       plugins: [DD_RUM.shopifyPlugin({ shopifyAnalytics: analytics })],
     })
   })
   ```

1. Save the pixel, then set its required consent category under **Settings** for the pixel (for example, Analytics) to match your store's privacy configuration - the bundle does not add its own consent gate; it defers entirely to whatever the merchant declares in Shopify's Pixel Manager.

**Note on `shopifyAnalytics`:** `analytics` is a bare global that only exists inside a Custom Pixel's code editor scope - pass it straight through as shown.

##### Out-of-the-box functionality{% #out-of-the-box-functionality-1 %}

Once `shopifyAnalytics` is set, the bundle automatically:

- Starts a RUM view on each checkout step (bound to Shopify's `page_viewed` standard event).
- Converts Shopify's `clicked` DOM event into a RUM click action.
- Converts Shopify's `ui_extension_errored` event (a checkout UI extension crashing) into a RUM error, tagged with the failing extension's name, target, type and the app the extension belongs to.
- Continues the storefront session: the sandbox shares the top frame's cookie jar, so if a visitor already has a `_dd_s` session cookie from the Theme Liquid snippet, checkout events land in that same session.
- Is a no-op in effect on storefront pages: Shopify fires the pixel's `page_viewed` event on every page, not just checkout, but the bundle only calls `startView` for checkout-path URLs - so no duplicate session or duplicate view is created alongside the Theme Liquid instance.

##### Instrumenting extra Shopify events{% #instrumenting-extra-shopify-events %}

The snippet above only wires up the three events the bundle binds automatically. Shopify's [standard events](https://shopify.dev/docs/api/web-pixels-api/standard-events) cover the full checkout funnel - `checkout_started`, `checkout_contact_info_submitted`, `checkout_shipping_info_submitted`, `payment_info_submitted`, `checkout_completed`, `alert_displayed` and more. Subscribe to any of them yourself, using `DD_RUM.onReady()` to queue calls made before the SDK has finished loading:

```javascript
analytics.subscribe('checkout_completed', (event) => {
  const checkout = event.data.checkout
  DD_RUM.onReady(() =>
    DD_RUM.addAction('checkout_completed', {
      orderId: checkout?.order?.id,
      totalPrice: checkout?.totalPrice,
    })
  )
})

analytics.subscribe('checkout_contact_info_submitted', (event) => {
  const checkout = event.data.checkout
  DD_RUM.onReady(() => {
    if (checkout?.email) {
      DD_RUM.setUser({ email: checkout.email }) // capture the guest email here
    }
    DD_RUM.addAction('checkout_contact_info_submitted', { checkoutToken: checkout?.token })
  })
})
```

You can also emit and subscribe to [custom events](https://shopify.dev/docs/api/web-pixels-api/emitting-data) the same way.

##### Limitations{% #limitations-1 %}

- **No Session Replay or Profiling.** The sandbox iframe has no real checkout DOM - recording or profiling it would capture nothing meaningful. Both are force-disabled regardless of what you pass to `init()`.
- **No Web Vitals, resource timing, or runtime JS errors.** `PerformanceObserver`, `fetch`/`XMLHttpRequest` instrumentation, and `window.onerror`/`unhandledrejection` all observe the sandbox iframe itself, not the checkout page's main thread - that boundary can't be crossed from a Custom Pixel.
- **Click actions are partial.** Only Shopify's basic `clicked` DOM event is available (no automatic DOM click listener, since there's no real DOM to listen on):
  - Emitted for inputs, links, and buttons - not for empty space or plain text.
  - Not emitted for payment card fields (card number, expiration, CVC, name on card) or the "Sign in" link.
  - Not emitted for a second click on a field that's already focused.
- **Advanced DOM Events are unavailable.** Shopify restricts that API to apps approved for it in the Partner Dashboard - a bar that doesn't apply to (and can't be met by) a Custom Pixel.
- **Checkout-path detection is regex-based**, matching `/checkouts?/` with an optional two-letter locale prefix (for example, `/en/checkout`). A store with a non-standard checkout URL structure won't currently have an override flag to adjust it.

### Validate the Installation{% #validate-the-installation %}

#### Storefront (Theme Liquid){% #storefront-theme-liquid %}

1. Open your storefront in a new browser session with developer tools open.
1. Confirm `datadog-rum-shopify.js` loads successfully (Network tab) and `window.DD_RUM` is defined (Console tab).
1. Navigate between a few storefront pages (home, a product, the cart).
1. In Datadog, open **Digital Experience > RUM Explorer**, filter by your configured `service` and `env`.
1. Confirm view events appear for each page you visited, and that a Session Replay recording is available for the session.

#### Checkout (Custom Pixel){% #checkout-custom-pixel %}

1. Place a test order (or go far enough into checkout to trigger `checkout_started`) on a storefront that has the Custom Pixel configured.
1. In the RUM Explorer, filter by the same `service`/`env` and look for views whose URL is under `/checkouts/`.
1. Confirm the view URL matches the real checkout URL (not a sandbox/iframe address) - this validates the `page_viewed`-driven `startView` binding is working.
1. Click a few checkout fields/buttons during the test run, then confirm corresponding click actions appear on the view.
1. If you added extra event subscriptions (see Instrumenting extra Shopify events), confirm their custom actions or user attributes (such as `checkout_completed`, the identified email from `setUser`) show up on the same view/session.
1. If nothing appears: check the pixel's consent category under **Settings > Customer events** - in opt-in (GDPR-style) regions, Shopify won't load the sandbox at all until the visitor consents, so no events fire until then.

## Data Collected{% #data-collected %}

### Metrics{% #metrics %}

The Shopify (RUM) integration does not include any metrics. To generate custom metrics from your RUM application, see [Generate Metrics](https://docs.datadoghq.com/real_user_monitoring/generate_metrics.md).

### Events{% #events %}

For more information about events and attributes, see [RUM Browser Data Collected](https://docs.datadoghq.com/real_user_monitoring/browser/data_collected.md).

### Service Checks{% #service-checks %}

The Shopify (RUM) integration does not include any service checks.

### Logs{% #logs %}

The Shopify (RUM) integration does not include Logs. To forward your Shopify store's logs to Datadog, see [JavaScript Logs Collection](https://docs.datadoghq.com/logs/log_collection/javascript.md).

## Troubleshooting{% #troubleshooting %}

Need help? Contact [Datadog Support](https://docs.datadoghq.com/help/).
