Tracking full-site events in Shopify

NOTE: This guide describes one method for uploading real-time conversion events. For all available methods, see Upload real-time conversion events. If you're uploading event data as part of the product catalog integration workflow, first complete Step 2: Upload product catalog data.

This solution is for customers of The Trade Desk who use Shopify and want to implement events tracking on their site pages. It includes tracking of multiple events across the full site, not just the checkout funnel.

Event tracking allows you to capture different events, such as add to cart or purchase events, with flexibility and granularity. For more information about event tracking, see Item-Level Event Tracking in the Knowledge Portal.

NOTE: This document is about implementing event tracking. To implement URL mapping, place the universal pixel for events outside the checkout funnel. For details, see Universal pixel or contact your Technical Account Manager.

Here's what you need to know about event tracking:

Events are fired depending on customizable triggers; they are not dependent on URL change. For example, a click action, such as a customer adding an item to the shopping cart, is still a standalone event that you might want to track. If you implement event tracking, you can set it up so that events of that type are treated as conversions and reported to The Trade Desk platform. This integration is set up to be triggered based on Shopify API events.
If you're using event tracking tags, you can build to the product catalog and take advantage of the item-level details being sent in this integration, for SKU-level reporting and custom audience building. For details, see Product catalog integration, or contact your Technical Account Manager.

The following sections provide additional information, give step-by-step instructions with script samples, and include reference information to help you.

Full list of events

The following table shows the events supported by this feature and indicates which events include SKU-level data.

Event	Includes SKU-Level Data?
Site visit	No
Product page view	Yes
Add to cart	Yes
Checkout	Yes
Purchase	Yes

Intended audience

This document serves two audiences:

Those who want to set up a new integration with The Trade Desk in Shopify to track any or all of the supported site events.
Those who have an existing integration, such as Tracking checkout events in Shopify, but want to update their integration to take advantage of the additional events supported.

Prerequisites

To implement this solution, you'll need to have the following:

Access to The Trade Desk Platform
Parent event tracker ID (added into the script in Step 2)
Your merchant ID

If you don't have a merchant ID, contact your Technical Account Manager, who will generate one and send it to you. When you have a merchant ID, a new tab becomes available in the platform UI: In Libraries > Advertiser Data, the new tab is Events Tracking.

Implementation steps

The instructions in the following sections use the Trade Desk Events SDK to implement event tracking in Shopify. The steps are summarized in the following table.

Step	Task	Tool / Platform	Notes
1	Set up full-site events tracking.	The Trade Desk UI	Copy the merchant ID and parent event tracker ID for use in Step 2.
2	Prepare the script.	Text editor	Replace placeholder values for your merchant ID and parent event tracker ID.
3	Implement the script.	Shopify UI	Save the updated script in Shopify.

Step 1: Set up full-site events tracking

To set up full-site events tracking in The Trade Desk platform, follow these steps:

On the left, choose Libraries > Advertiser Data and click the Events tracking tab.

There are various data columns such as Name, Tracker ID, and Merchant ID. Copy the Tracker ID and Merchant ID and save them for use in Step 2: Prepare the script.
In the Events Tracking tab, create the following events:
- sitevisit
- viewitem
- addtocart
- startcheckout
- purchase

Step 2: Prepare the script

This script implements item-level event tracking using The Trade Desk Events SDK.

To customize the script, follow these steps:

Make a copy of the script.
Replace the following placeholders with your own values:
- MERCHANT_ID_PLACEHOLDER: Use your own merchant ID.
- PARENT_EVENT_TRACKER_ID_PLACEHOLDER: Use your own parent event tracker ID (Tracker ID column in the platform UI).
(Optional) If you've configured dynamic parameters in the Event Tracker, add the optional parameters TD1 through TD9, as applicable. TD10 is also a dynamic parameter, but the script uses it.

For assistance with configuring dynamic parameters, if needed, ask your Technical Account Manager.

// TTD Full Site Events Tracking
(function () {
  var script = document.createElement('script');
  script.src = 'https://js.adsrvr.org/up_loader.3.0.0.js';
  document.head.appendChild(script);
  window.ttdConversionEventsLayer = window.ttdConversionEventsLayer || [];
  function ttdConversionEvents() {
    window.ttdConversionEventsLayer.push(arguments);
  }
  script.onerror = function() { console.error('TTD: Failed to load SDK from', script.src); };
  script.onload = function () {
    ttdConversionEvents("init", { merchantId: "MERCHANT_ID_PLACEHOLDER", pixelIds: ["PARENT_EVENT_TRACKER_ID_PLACEHOLDER"] });
    // Site visit
    analytics.subscribe('page_viewed', function(event) {
      ttdConversionEvents("event", {
        referrer_url: event.context.document.location.href,
        event_name: "sitevisit",
        td10: "TTDxShopifyIntegration"
      });
    });
    // View Item
    analytics.subscribe('product_viewed', function(event) {
      setTimeout(function() {
        ttdConversionEvents("event", {
          referrer_url: event.context.document.location.href,
          event_name: "viewitem",
          td10: "TTDxShopifyIntegration",
          items: [{
            item_code: event.data?.productVariant?.sku ?? null,
            name: event.data?.productVariant?.product?.title ?? null,
            price: event.data?.productVariant?.price?.amount ?? null,
            cat: event.data?.productVariant?.product?.type ?? null
          }]
        });
      }, 2000);
    });
    // Add to cart
    analytics.subscribe('product_added_to_cart', function(event) {
      var cartLine = event.data?.cartLine;
      ttdConversionEvents("event", {
        referrer_url: event.context.document.location.href,
        event_name: "addtocart",
        td10: "TTDxShopifyIntegration",
        items: [{
          item_code: cartLine?.merchandise?.sku ?? null,
          name: cartLine?.merchandise?.product?.title ?? null,
          qty: cartLine?.quantity ?? null,
          price: cartLine?.cost?.totalAmount?.amount ?? null,
          cat: cartLine?.merchandise?.product?.type ?? null
        }]
      });
    });
    // Checkout started
    analytics.subscribe('checkout_started', function(event) {
      setTimeout(function() {
        ttdConversionEvents("event", {
          referrer_url: event.context.document.location.href,
          value: event.data?.checkout?.totalPrice?.amount,
          currency: event.data?.checkout?.currencyCode,
          event_name: "startcheckout",
          td10: "TTDxShopifyIntegration",
          items: event.data?.checkout?.lineItems?.map(function(item) {
            return {
              item_code: item?.variant?.sku ?? null,
              name: item?.variant?.product?.title ?? null,
              qty: item?.quantity ?? null,
              price: item?.variant?.price?.amount ?? null,
              cat: item?.variant?.product?.type ?? null
            };
          }) ?? []
        });
      }, 2000);
    });
    // Purchase
    analytics.subscribe('checkout_completed', function(event) {
      setTimeout(function() {
        ttdConversionEvents("event", {
          referrer_url: event.context.document.location.href,
          value: event.data?.checkout?.totalPrice?.amount,
          currency: event.data?.checkout?.currencyCode,
          event_name: "purchase",
          td10: "TTDxShopifyIntegration",
          order_id: event.data?.checkout?.order?.id,
          items: event.data?.checkout?.lineItems?.map(function(item) {
            return {
              item_code: item?.variant?.sku ?? null,
              name: item?.variant?.product?.title ?? null,
              qty: item?.quantity ?? null,
              price: item?.variant?.price?.amount ?? null,
              cat: item?.variant?.product?.type ?? null
            };
          }) ?? []
        });
      }, 2000);
    });
  };
})();

For details about the steps in the script, see What the script is doing.

Step 3: Paste the script in Shopify

In the Shopify UI, paste the script:

Go to Admin > Settings > Customer events.
Click Add Custom Pixel.
Paste the script and save.

NOTE: Shopify handles consent checking for custom pixels automatically: Customer events > Customer privacy. However, these steps help verify that the permission settings are configured appropriately for your store's requirements.

Next steps

If you uploaded event data only for measurement, your integration is complete.

If you uploaded event data as part of a product catalog integration, the next step is to activate the data through your product catalog. To share access, continue to Step 4. Manage product catalog access. After an advertiser has access to the catalog, they can create product lists to build audiences and measure sales performance.

Reference information

This section contains reference information to support the procedures in this document.

Shopify sandbox features

In Shopify, pixels are always implemented in the Shopify sandbox, which is a secure, isolated environment that allows you to run scripts without affecting the rest of your online store. For details, see Sandbox environment for pixels in the Shopify documentation.

The Checkout Extensibility feature runs in the Shopify sandbox environment.

Here's what you need to know about the Shopify sandbox:

Shopify supports the ability to subscribe to certain events, such as checkout_completed, so that the pixel only fires when those events occur. For a summary of supported events, see Standard Events in the Shopify documentation.
Shopify allows use of the Web Pixels API to dynamically retrieve the order ID (orderId), order totals, and other item-level metadata related to site events.

Optional dynamic parameters

You can track one or more of the additional dynamic parameters, TD1 through TD9, with any of these procedures. TD10 is also a dynamic parameter, but the script uses it.

To implement dynamic parameters, just add them to the custom script. The script can pick up the values and send them to The Trade Desk. For details, see Dynamic parameters. For additional assistance, if needed, ask your Technical Account Manager.

What the script is doing

The script performs these actions, in sequence:

It loads the Events SDK from The Trade Desk, and initializes the SDK with your merchant credentials.
It uses the Shopify Web Pixels API to listen for customer actions across your site: page views, product views, add-to-cart actions, checkout starts, and completed purchases.
When one of these events fires, it performs the following steps:
1. Pulls the relevant data directly from Shopify's event payload, including item-level details such as SKU, product name, quantity, price, and category.
2. Sends the data to The Trade Desk platform as a granular, SKU-level tracking event.

NOTE: The script uses the dynamic parameter TD10 to identify this integration as the event source in the platform. The TD10 parameter is reserved for this purpose: you can use parameters TD1 through TD9 for custom tracking.

Troubleshooting

The following is some troubleshooting information for implementations of this SDK.

Pixel not firing

If you think the pixel is not firing, follow these steps to check network requests:

Right-click on the page > choose Inspect > go to the Network tab.
Filter by realtimeconversion.
Trigger an event on the site: view a product, add an item to the cart, or complete a checkout.
In the Network tab, look for a realtimeconversion request where Type = xhr. Ignore the preflight ones; those are normal CORS checks. Click on the request and confirm that the following values are present:
- Headers tab: Status code 200 OK.
- Payload tab: merchantId matches your merchant ID.
- Payload tab: pixelIds contains your parent event tracker ID.
- Payload tab: event_name matches the event you triggered (for example sitevisit, addtocart, purchase).
- Payload tab: For product events, items array contains item_code, name, price, and qty.

No request appearing

If there is no request, follow these steps:

Make sure that the pixel is saved and connected in Shopify (Settings > Customer Events). For details, see Paste the script in Shopify.
Refresh and try again.