Conversion events: Real-Time Conversion Events API quickstart

NOTE: This guide describes one method for uploading real-time conversion events. For detailed implementation instructions, see Real-Time Conversion Events API. 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 Real-Time Conversion Events API (RT CAPI). For full implementation details, see Real-Time Conversion Events API.

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 conversion events (`purchase`, `addtocart`, `viewitem`, and so on)
Best for	Providers who need a server-to-server integration, or want to track in-app events
Implementation	Server-side without GTM; client-side (in-app only)

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: Send a conversion event

Send a POST request to the Real-Time Conversion Events API endpoint. Include each event as an object in the data array and replace the placeholders with your actual ID values:

{
  "data": [
    {
      "merchant_id": "MERCHANT_ID_PLACEHOLDER",
      "pixel_ids": ["EVENT_TRACKING_TAG_ID_PLACEHOLDER"],
      "event_name": "EVENT_NAME_PLACEHOLDER",
      "adid": "EVENT_ADVERTISING_ID_PLACEHOLDER",
      "adid_type": "UID2"
    }
  ]
}

For events with product-level data, such as purchase, include the full event details:

{
  "data": [
    {
      "adv": "ADVERTISER_ID_PLACEHOLDER",
      "pixel_ids": ["EVENT_TRACKING_TAG_ID_PLACEHOLDER"],
      "event_name": "purchase",
      "referrer_url": "https://yoursite.com/checkout/confirmation",
      "adid": "EVENT_ADVERTISING_ID_PLACEHOLDER",
      "adid_type": "UID2",
      "items": [
        {
          "item_code": "203319203",
          "name": "Blue T-Shirt",
          "qty": 1,
          "price": 19.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.