Real-Time Conversion Events API

NOTE: This guide describes one method for uploading real-time conversion events. If you only need the minimum steps, use the Offline Conversion Events API quickstart instead. 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.

The Real-Time Conversion Events API enables partners to send conversion events they captured to The Trade Desk platform so that they can be used for retargeting and attribution as part of an advertiser’s marketing campaigns.

Here's what you need to know about the Real-Time Conversion Events API:

• This guide is intended for partners interested in uploading website or app conversion events in real time. For uploading conversion events that occurred offline (for example, in-store sales), or to upload online conversions in bulk, see Offline conversion events.
• To optimize real-time web tracking, the universal pixel automatically sends URL conversion data to the POST track/realtimeconversion endpoint. For details, see Universal pixel.

Before you begin, note that the API supports the following capabilities:

• Upload conversion events in real-time.
• Support for sending page view events and named user-interaction events, for example, addtocart.
• Support for including multiple items in a single event. For example, cart-level data.
• Support for different types of user IDs to facilitate retargeting and campaign attribution. Supported types include Unified IDs such as UID2 and EUID, TDID, device IDs (IDFA, AAID, NAID, DAID), RampID (formerly IDL).
• Custom fields, TD1-TD10, for conversion event metadata such as promo codes. For details, see FAQs.
• Support for all event types defined by the advertiser in The Trade Desk platform, which supports all event types without restrictions.

Workflow diagram

To use the Real-Time Conversion Events API, you must first have a captured event such as a page view, user interaction, or transaction. To ensure that the event can be used for retargeting and attribution, use one of the supported IDs to identify the user who triggered the event. After you capture the event with the associated user ID, you can map the event to a URL for page views (URL mapping) or an event tracker for user interactions and transactions (event mapping).

The following diagram illustrates the decision you need to make to determine which ID types you want to use to identify the user and how you need to map and send your events to the platform.

Supported user ID types

To ensure that the event you send can be used in The Trade Desk platform for retargeting and attribution, use one of the supported ID types to identify the user who triggered the event.

Here's what you need to know about specifying user IDs when uploading events with the POST /track/realtimeconversion endpoint:

• You can include a user ID in either the adid field with the adid_type (recommended), or any of the respective field values such as uid2_token.
• You can include multiple types of IDs for a user, but only one ID for each type.
• For third-party measurement partners, be sure to also include an impression ID.

The following table lists the types of user IDs that you must include when you send an event to the platform.

For details about which ID you should use and access for generating an ID, contact your Technical Account Manager.

Conversion event mapping

IMPORTANT: If you're using item-level tracking and you want to collect revenue data to measure revenue or ROAS, you must include the quantity and item price for each item. When these two values are used for segment creation or during attribution, we calculate the revenue by multiplying them together to understand how much revenue is driven by each item.

There are different types of events you can upload: page views through URL mapping and user interactions. Here's what you need to know about sending events to The Trade Desk platform:

• To send events to The Trade Desk platform, use the POST /track/realtimeconversion endpoint.
• You can send multiple events in a single request by including them as separate objects in the data object array.
• You can map a page view and a user-interaction event to the same user, but only one of each event type.
• Regardless of the event type, include the following fields:
  • pixel_ids field with universal pixel IDs, event tracker IDs, or both.
  • adid and adid_type with the user ID and its type.
• Depending on the event type, you must include one of the following:
  • For page views, include an advertiser ID in the adv field and the page URL in the referrer_url field.
  • For user interactions, include a merchant ID in the merchant_id field and an event name in the event_name field.

TIP: To retrieve the relevant advertiser, merchant, pixel information, and details about the required use cases, contact your Technical Account Manager.

The following sections demonstrate different ways of sending events to The Trade Desk platform.

URL mapping (page views)

To send a page view event that tracks which web page the user viewed, in a POST /track/realtimeconversion call, include the following in the request:

An advertiser ID (adv).
An ID of a Universal pixel with URL mappings.
The URL (referrer_url) of the webpage where the event occurred.
The unique ID (adid) of user who viewed the web page and the ID type (adid_type).

Here's an example of tracking a user (identified by a UID2) who viewed site.com.

{
  "data": [
    {
      "adv": "ADVERTISER_ID_PLACEHOLDER",
      "referrer_url": "site.com",
      "pixel_id": "UNIVERSAL_PIXEL_ID_PLACEHOLDER",
      "adid": "USER_ID_PLACEHOLDER",
      "adid_type": "UID2"
    }
  ]
}

User interaction event mapping

To send user interactions and transaction events to the platform, in a POST /track/realtimeconversion call, include the following in the request:

The merchant ID assigned during the onboarding process.
An event tracking tag ID configured in the platform UI (pixel_id). For details, see Item-level event tracking tag.
The name of the event such as addtocart and purchase. For a list of standard names, see Event names. For details about using a custom event name, see Define Events in the Knowledge Portal.
The unique ID of the user who triggered the event and the ID type (adid and adid_type).
(Optional) If needed, include a list of items (items) or product-level details from a merchant's product catalog.

NOTE: To configure and manage events as a merchant with a product catalog, you need to use the platform UI. For details, see Item-Level Event Tracking in the Knowledge Portal.

Here's an example of tracking a user (identified by a UID2) who added two items to their cart.

{
  "data": [
    {
      "merchant_id": "MERCHANT_ID_PLACEHOLDER",
      "event_name": "addtocart",
      "pixel_id": "EVENT_TRACKING_TAG_ID_PLACEHOLDER",
      "adid": "USER_ID_PLACEHOLDER",
      "adid_type": "UID2",
      "items": [
        {
          "item_code": "203319203",
          "name": "Deluxe Twin Room",
          "qty": 1,
          "price": 264.00,
          "cat": "23",
          "item_brand": "Sample Hotel Group"
        },
        {
          "item_code": "2234567892",
          "name": "King Terrace Suite",
          "qty": 1,
          "price": 399.00,
          "cat": "1110",
          "item_brand": "Sample Hotel Group"
        }
      ]
    }
  ]
}

Multiple event mapping

If you want to map multiple pixel IDs and events to a single user, you can send multiple events in the same data child object. Here's what you need to know:

• You can map a page view and a user-interaction event to the same user, but only one of each type.
• Include all of the universal pixel and event tracking tag IDs you want to map in the pixel_ids array instead of the pixel_id field.
• Be sure to include the applicable information and requirements for URL mapping and Event mapping.
• If you include both page view and user-interaction events, you need to include only your advertiser ID or merchant ID but not both.

Here's an example of a user who visited a website and added two items to the cart which triggered both a page view and a user-interaction event.

{
  "data": [
    {
      "adv": "ADVERTISER_ID_PLACEHOLDER",
      "pixel_ids": ["EVENT_TRACKING_TAG_ID_PLACEHOLDER", "UNIVERSAL_PIXEL_ID_PLACEHOLDER"],
      "event_name": "addtocart",
      "referrer_url": "site.com",
      "adid": "USER_ID_PLACEHOLDER",
      "adid_type": "UID2",
      "items": [
        {
          "item_code": "203319203",
          "name": "Deluxe Twin Room",
          "qty": 1,
          "price": 264.00,
          "cat": "23",
          "item_brand": "Sample Hotel Group"
        },
        {
          "item_code": "2234567892",
          "name": "King Terrace Suite",
          "qty": 1,
          "price": 399.00,
          "cat": "1110",
          "item_brand": "Sample Hotel Group"
        }
      ]
    }
  ]
}

FAQs

The following is a list of frequently asked questions about the Real-Time Conversion Events API:

Can I use The Trade Desk and my own attribution models?

Advertisers can leverage The Trade Desk attribution as well as partners' own models for attribution. The results of the attribution that a partner and The Trade Desk calculate, however, don’t always align. This may cause confusion for advertisers, especially the calculation of key metrics such as CPA.

To address this problem, The Trade Desk provides a solution that enables the partner to communicate the results of their attribution model to The Trade Desk by adding an optional property to the event used to communicate conversions: imp. When this property is set, it indicates whether the event is attributed to an impression from The Trade Desk.

If the event is attributed to The Trade Desk, The Trade Desk attributes the event to the impression ID specified in the imp property. This bypasses The Trade Desk attribution models and aligns attribution results with those delivered by the partner to advertisers.

Is the Real-Time Conversion Events API intended exclusively for commerce partners who have a merchant ID?

No, any advertiser who wants to catalog multiple items can use the Real-Time Conversion Events API. Advertisers must provide only their advertiser ID, similar to the setup for the Universal pixel. A merchant ID is required only for advertisers who want to use a product catalog. To request a merchant ID, contact your Technical Account Manager.

Does the Real-Time Conversion Events API support backfill?

No, the API supports only real-time conversion events. To upload late or batch data, use the POST /providerapi/offlineconversion endpoint. For details, see Upload offline conversion events.

How is the Real-Time Conversion Events API different from Universal Pixels?

The Real-Time Conversion Events API is now the server-side feature for the universal pixel. For details, see Universal pixel.

Can I use dynamic parameter rules with the Real-Time Conversion Events API?

For commerce clients, The Trade Desk recommends using the product catalog item sets to split events into sub-events. For non-commerce clients, the Real-Time Conversion Events API supports dynamic rules through one of the following methods:

• You do not need to populate the td1-td10 fields yourself — the platform derives these values from your items payload. This mapping occurs only on rule-matched conversion copies. The original conversion record always reflects your payload as sent.
• If you do not include an items array in your request, the td1-td10 fields are available as general-purpose custom fields. You can use them to pass any additional conversion metadata relevant to your use case.
• Standard dynamic parameter rules enable you to use the td1-td10 fields to provide additional metadata to the event.
• Custom line-item dynamic rules enables you to provide item-level data without using a product catalog. This enables the platform to generate a custom td1-td10 mapping per line item against which your dynamic rules are applied. If you send a single event with 10 line items, the platform will run the custom line-item rules 10 times—once per line item.

IMPORTANT: If your payload includes both an items array and explicit td1-td10 values, the item-based mapping will overwrite your td1-td10 values on any rule-matched copies. Avoid populating the td1-td10 fields manually if you are also sending an items array. If you have a use case that requires both, contact your Trade Desk representative to understand how these fields interact and their downstream impact on optimization and reporting prior to implementation.

Can I use the Real-Time Conversion Events API for URL mapping?

Yes. For details, see URL mapping.

Can I use events from the Real-Time Conversion Events API for both URL and event mapping?

Yes. For details, see Multiple event mapping.

Is there an alternative method to send events to The Trade Desk platform?

Yes. For details, see Item-level events tracking tag.

As a merchant, do I need a unique tracker ID for each type of event that I want to send to The Trade Desk platform?

No. However, for every event that you want to send, you must include the following values:

• The name of the event as the event_name value.
• Your parent tracking tag ID as the pixel_id value. This was created during the merchant onboarding process.

For details, see Event mapping.

How do I troubleshoot or get more insight into validation issues?

To identify and troubleshoot issues, such as missing parameters, consent mismatches, or implementation errors, include the debug field with a value of 1 in your post-track-realtimeconversionrequest payload. See also tips on the built-in debugging options in universal pixels in FAQs that might apply.

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.