Conversion events: GTM client-side quickstart

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.

If you are a merchant or data provider sending audience or measurement data to The Trade Desk to monetize through the platform, this guide is for you. This guide walks you through the minimum steps to start sending conversion events using the official Trade Desk Google Tag Manager (GTM) client-side template. For full implementation details, see Item-level event tracking tag.

Is this the right implementation for you?

Prerequisites

Before you begin, make sure you have the following:

Merchant ID (provided by your Technical Account Manager)
Event tracker ID (the ID of the tracking tag tied to your conversion event configuration)
A GTM account with a web container configured for your site
The GTM container snippet already installed on your site

Step 1: Map your event types

Map your site actions to The Trade Desk standard event names.

The following table provides the most common examples. For a full list, see POST /track/realtimeconversion. If needed, you can also create custom events.

Step 2: Install the GTM template

The Trade Desk GTM template is available directly in the GTM template gallery. This is the recommended approach—gallery installations receive automatic updates when new versions are published.

1. In your GTM workspace, go to Templates in the left sidebar.
2. Under Tag Templates, click Search Gallery.
3. Search for The Trade Desk or Conversion Events SDK.
4. Select the template and click Add to workspace.
5. Review the permissions and click Add.

NOTE: If you need a specific version or cannot use the gallery, you can install the template manually from GitHub. For details, see Manually import GTM template from GitHub.

Step 3: Configure GTM variables

1. Under Variables > User-Defined Variables > New, create the following variables:

   • Constant variables (static account IDs):

     Variable name	GTM variable type	Value
     TTD Merchant ID	Constant	Your merchant ID
     TTD Pixel IDs	Constant	Your event tracker ID

   • Data layer variables (dynamic event data):

     Variable name	GTM variable type	Data layer variable name
     Data Layer - Transaction ID	Data layer variable	ecommerce.transaction_id
     Data Layer - Order Value	Data layer variable	ecommerce.value
     Data Layer - Order Currency	Data layer variable	ecommerce.currency
     Data Layer - Ecommerce Items	Data layer variable	ecommerce.items

2. Under Variables > Configure, enable the Page URL built-in variable.

3. Create a Lookup Table variable to translate your site's event names into The Trade Desk standard event names:

   Setting	Value
   Variable name	TTD Event Name
   Type	Lookup table
   Input variable	{{Event}}
   Default value	{{Event}}

4. Configure the lookup table rows using your event name mappings from Step 1.

Step 4: Create and configure the tag

1. In GTM, go to Tags and click New.

2. Click Tag Configuration and select the Trade Desk template installed in Step 2.

3. Configure the tag fields:

   Tag field	Value
   Merchant ID	{{TTD Merchant ID}}
   Pixel IDs	{{TTD Pixel IDs}} (Enter multiple IDs as a comma-separated list.)
   Page URL	{{Page URL}}
   Event Name	{{TTD Event Name}}
   Order ID	{{Data Layer - Transaction ID}}
   Order Value	{{Data Layer - Order Value}}
   Order Currency	{{Data Layer - Order Currency}}
   Ecommerce Event Item/Product Data	{{Data Layer - Ecommerce Items}}

   For the Ecommerce Event Item/Product Data field, use the following item field mappings:

   TTD field	Item field name
   Item Code	item_id
   Name	item_name
   Category	item_category
   Price	price
   Quantity	quantity

Step 5: Configure triggers

1. Create a custom event trigger for each event you want to track and assign all triggers to your tag.

   Trigger name	Trigger type	Event name
   TTD - Add to Cart	Custom event	add_to_cart
   TTD - Begin Checkout	Custom event	begin_checkout
   TTD - Purchase	Custom event	purchase

2. Add additional triggers for any other events you are tracking.

IMPORTANT: Your site must push events to the GTM data layer for triggers to fire.

Here's an example purchase push:

window.dataLayer.push({
  event: 'purchase',
  ecommerce: {
    transaction_id: 'order12345',
    value: 13.49,
    currency: 'USD',
    items: [
      {
        item_id: 'item1234',
        item_name: 'Washing Liquid',
        item_category: 'Laundry',
        price: 5.99,
        quantity: 1
      }
    ]
  }
});

NOTE: If your site already sends Google Analytics 4 (GA4) events to GTM, the Trade Desk template can read from the same data layer pushes with no changes to your site code.

Step 6 (optional): Test your implementation

Use GTM Preview mode to verify that your tag is firing correctly and that events are reaching The Trade Desk platform.

1. In GTM, enable Preview mode to activate the GTM Tag Assistant debugger.
2. Navigate to your site and trigger each event you have configured.
3. In the debugger, verify the following:
   • The correct trigger is firing for each event.
   • The tag is receiving the expected variable values (merchant ID, pixel IDs, event name, order and item data).
4. In The Trade Desk platform, check your conversion tag reporting to confirm events are being received.

Troubleshooting

If your tag is not behaving as expected, use the following common issues and fixes as a starting point.

Tag is not firing

Confirm that the event names in your custom event triggers exactly match what your site pushes to the GTM data layer (window.dataLayer). Use GTM Preview mode to inspect which triggers activate on each page action.

Event name is showing as undefined or empty

Verify that the TTD Event Name lookup table variable is configured correctly and that the data layer event name matches an input row. Confirm the default value is set to {{Event}}.

Order or item data is missing

Confirm your data layer pushes include the ecommerce object with the correct structure. Check that data layer variable names use the exact dot-notation paths (ecommerce.transaction_id, ecommerce.items, and so on).

Items array is not being sent

Ensure the Ecommerce Event Item/Product Data field is populated with your Data Layer - Ecommerce Items variable, and that the item field mappings (for example, item_id to item code) are correctly configured on the tag.

Manually import GTM template from GitHub

If you want a specific template version or cannot use the GTM template gallery in Step 2, import the template manually:

1. Download the template file from the GitHub repository: github.com/thetradedesk/conversion-events-sdk-for-googletagmanager.
2. In your GTM workspace, go to Templates in the left sidebar.
3. Under Tag Templates, click New.
4. In the template editor, click the menu (three vertical dots in the top-right corner) and select Import.
5. Upload the template file from the repository.
6. Review the Template Preview. To see the editable fields, click the Tag Configuration header.
7. Click Save, then click Close (x) to return to the workspace.

The new template appears in your Templates list and is available when creating new tags. Continue to Step 3.

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.