Conversion events: JS SDK 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 JavaScript (JS) SDK. For full implementation details, see Item-level event tracking tag.

Is this the right implementation for you?

Aspect	Description
Who it's for	Merchants and data providers not using Google Tag Manager (GTM)
What it does	Tracks specific user actions and sends them to The Trade Desk
What it tracks	Item-level web conversion events (`purchase`, `addtocart`, `viewitem`, and so on)
Best for	Providers who control the site directly
Implementation	Client-side (browser, web events only), without GTM

Required IDs

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)

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.

Your site action	TTD event name
Page view	`sitevisit`
Product view	`viewitem`
Add to cart	`addtocart`
Begin checkout	`startcheckout`
Purchase	`purchase`
Lead / form submit	`messagebusiness`
Search	`searchitem`
View cart	`viewcart`
Add to wishlist	`wishlistitem`
Login	`login`

Step 2: Embed the script on your web pages

Embed the following script on the pages where you expect conversion events to fire and replace the placeholders with your actual ID values:

<script async src="https://js.adsrvr.org/up_loader.3.0.0.js"></script>
<script>
  window.ttdConversionEventsLayer = window.ttdConversionEventsLayer || [];
  function ttdConversionEvents() { window.ttdConversionEventsLayer.push(arguments); }
  ttdConversionEvents("init", { merchantId: MERCHANT_ID_PLACEHOLDER, pixelIds: ["EVENT_TRACKING_TAG_ID_PLACEHOLDER"] });
  ttdConversionEvents("event", { merchantId: MERCHANT_ID_PLACEHOLDER, pixelIds: ["EVENT_TRACKING_TAG_ID_PLACEHOLDER"] });
</script>

For events with product-level data (for example, purchase), include the full event details in the event call:

ttdConversionEvents("event", {
  merchantId: "MERCHANT_ID_PLACEHOLDER",
  pixelIds: ["EVENT_TRACKING_TAG_ID_PLACEHOLDER"],
  event_name: "purchase",
  currency: "USD",
  order_id: "ORDER_ID_PLACEHOLDER",
  value: 29.98,
  items: [
    { item_code: "203319203", name: "Blue T-Shirt", qty: 1, price: 19.99, cat: "Clothes" },
    { item_code: "2234567892", name: "Blue Shorts", qty: 1, price: 9.99, cat: "Clothes" }
  ]
});

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.