Tracking checkout 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 guide is for customers of The Trade Desk who use Shopify and want to have conversion information from their Checkout or Thank You pages reported to The Trade Desk, for checkout or confirmation events, in a direct implementation.

Intended audience

This document serves two audiences:

Those who want to set up a new integration with The Trade Desk in Shopify.
Those who have an existing integration, but must update it because of Shopify's deprecation of the checkout.liquid file and the requirement to use the Checkout Extensibility feature instead. For details, see deprecation of the checkout.liquid file in the Shopify documentation.

These instructions are valid for both scenarios.

Implementation options

There are two implementation options:

URL mapping
Event tracking

The following sections provide details about the available options, give step-by-step instructions with script samples, and include reference information to help you.

URL mapping

URL mapping extends the universal pixel into the Shopify Checkout Extensibility funnel to track checkout and purchase events.

Here's what you need to know about the URL mapping option:

URL mapping uses the universal pixel.
URL mapping events are only fired when the user's URL changes.
URL mapping allows tracking of customer events during checkout without modifying the universal pixel code in the Shopify theme.liquid file.
We provide a script that runs in a secure Shopify sandbox environment.
If you're a merchant and want to track item-level details for checkout and confirmation events, for the product catalog, event tracking is a better choice.
To set it up in the platform UI: Libraries > Advertiser Data > Universal Pixels.

For more information, see Universal pixel.

Prerequisites

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

Access to The Trade Desk Platform
Your advertiser ID

Implementation steps

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

Step	Task	Tool / Platform	Notes
1	Create a universal pixel.	The Trade Desk UI	Copy the pixel ID for use in Step 2.
2	Prepare the script.	Text editor	Replace placeholder values for your advertiser ID and pixel ID.
3	Implement the script.	Shopify UI	Save the updated script in Shopify.

Step 1: Create a universal pixel

NOTE: If you already have the universal pixel, there's no need to create one. Just get the ID of your existing pixel.

To create the universal pixel, follow these steps:

Log in to The Trade Desk platform.
On the left, choose Libraries > Advertiser Data and click the Universal Pixels tab.
In the Universal Pixels tab, create the following URL mappings:

URL Mapping Type Pattern

Checkout Custom */checkouts/*/en-us

Purchase Contains thank-you

NOTE: The checkout pattern is based on the US English locale (en-us). If the client's store uses a different locale, contact your Technical Account Manageronfirm the correct pattern.
Copy the universal pixel ID and save it for use in Step 2: Prepare the script.

For details, see Create a Universal Pixel in the Knowledge Portal.

URL Mapping	Type	Pattern
Checkout	Custom	`/checkouts//en-us`
Purchase	Contains	`thank-you`

Step 2: Prepare the script

This script initializes and calls The Trade Desk Events SDK. It includes some generic placeholder values. To prepare the script for your own implementation, you'll need to customize it with your own values. Follow these steps:

Make a copy of the script.
Replace the following placeholders with your own values:
- ADVERTISER_ID_PLACEHOLDER: Use your own advertiser ID.
- UPIXEL_ID_PLACEHOLDER: Use the universal pixel ID that you copied from the platform UI in Create a universal pixel.
(Optional) Adjust optional dynamic parameters TD1 through TD9. TD10 is also a dynamic parameter, but the script uses it.

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

// The Trade Desk URL Mapping 
(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", {
      advertiserId: "ADVERTISER_ID_PLACEHOLDER",
      pixelIds: ["UPIXEL_ID_PLACEHOLDER"]
    });
 
    // Checkout Started
    analytics.subscribe('checkout_started', function (event) {
      ttdConversionEvents("event", {
        referrer_url: event.context.document.location.href,
        value: event.data?.checkout?.totalPrice?.amount,
        currency: event.data?.checkout?.currencyCode,
        td10: "TTDxShopifyIntegration"
      });
    });
 
    // Checkout Completed (Purchase)
    analytics.subscribe('checkout_completed', function (event) {
      ttdConversionEvents("event", {
        referrer_url: event.context.document.location.href,
        value: event.data?.checkout?.totalPrice?.amount,
        currency: event.data?.checkout?.currencyCode,
        order_id: event.data?.checkout?.order?.id,
        td10: "TTDxShopifyIntegration"
      });
    });
  };
})();

Step 3: Paste the script in Shopify

In the Shopify UI, follow these steps:

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.

Event tracking

Event tracking allows you to capture different events, such as purchases from the checkout basket, with flexibility and granularity. For details, see Item-Level Event Tracking in the Knowledge Portal.

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.

Prerequisites

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

Access to The Trade Desk Platform
Parent event tracker ID (collected 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 events tracking.	The Trade Desk UI	Copy the Tracker ID and Merchant ID for use in Step 2.
2	Prepare the script.	Text editor	Replace placeholder values for your advertiser ID and pixel ID.
3	Implement the script.	Shopify UI	Save the updated script in Shopify.

Step 1: Set up events tracking

To set up 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:
- 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 dynamic 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.

// The Trade Desk Events Tracking (startcheckout and purchase)
(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"]
    });
 
    function mapLineItems(lineItems) {
      return (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
        };
      }) ?? []);
    }
 
    // Checkout Started
    analytics.subscribe('checkout_started', function (event) {
      ttdConversionEvents("event", {
        referrer_url: event.context.document.location.href,
        value: event.data?.checkout?.totalPrice?.amount,
        currency: event.data?.checkout?.currencyCode,
        event_name: "startcheckout",
        items: mapLineItems(event.data?.checkout?.lineItems),
        td10: "TTDxShopifyIntegration"
      });
    });
 
    // Checkout Completed (Purchase)
    analytics.subscribe('checkout_completed', function (event) {
      ttdConversionEvents("event", {
        referrer_url: event.context.document.location.href,
        value: event.data?.checkout?.totalPrice?.amount,
        currency: event.data?.checkout?.currencyCode,
        event_name: "purchase",
        order_id: event.data?.checkout?.order?.id,
        items: mapLineItems(event.data?.checkout?.lineItems),
        td10: "TTDxShopifyIntegration"
      });
    });
  };
})();

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. You can also create product lists to build audiences and measure sales performance.

Reference information

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

Shopify sandbox features
Optional dynamic parameters

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.