Offline Conversion Events API

NOTE: This guide describes one method for uploading offline conversion events. For all available methods, see Upload offline conversion events. If you're uploading event data as part of the product catalog integration workflow, first complete Step 2: Upload product catalog data.

Offline conversions can include use cases such as attributing in-store sales, place visits, or custom events. To facilitate insights into conversions in verticals where purchases predominantly occur offline, The Trade Desk enables partners and trusted marketplace providers to send offline measurement data to the platform and then use it for attribution and targeting.

Roles

This guide is for partners interested in uploading offline conversions such as in-store sales, place visits, or custom events. For uploading real-time conversions such as cart-level data, see Real-time conversion events.

Measurement marketplace providers

Measurement marketplace providers make their offline measurement offering available to buyers. In the platform UI, information for each provider is listed in a tile on the Measurement Marketplace page under Reports. For details, see Measurement Marketplace and Measurement Marketplace Partners in the Knowledge Portal.

To get started as an offline data provider, contact The Trade Desk Data Partnerships team.

Buyers

Buyers are partners who use The Trade Desk platform to buy inventory. Buyers can choose to rely on third-party measurement marketplace providers or upload offline measurement data themselves.

• Buyers who don't use marketplace third-party providers build directly using the offline conversion APIs. They can use offline conversions for campaign performance improvements: for example, for retargeting (including Koa retargeting), Audience Predictor, and look-alike model building.

• Buyers who rely on third-party providers typically reach out to the selected provider with their advertiser ID and negotiate the events to be tracked. Buyers provide their advertiser ID to offline data providers, and the data providers give the tracking tag name and ID to their buyers.

In the platform UI, buyers can access offline data via the Conversion Details and Path to Conversion Data reports. Their campaign dashboard will include the offline conversions. The Trade Desk platform tracks campaign-level, ad-group level, and log-level metrics (certain limitations may apply).

IMPORTANT: To attribute to the offline tracking tag created during integration, buyers must also set up campaign reporting columns in the UI.

For additional information, see the following pages in the Knowledge Portal:

• Attribution
• Rp - Reports
• Measurement Marketplace Partners

To get started with offline measurement for attribution as a buyer, contact your Technical Account Manager.

Integration steps

NOTE: The offline conversion events endpoint does not support email addresses and phone numbers. To create a segment for conversion measurement, use the POST /v3/crmdata/conversion/segment endpoint. For details, see CRM data integration.

Here's what you need to know and do before you start an offline measurement integration:

• Be sure to obtain the following from The Trade Desk Data Partnerships and your Technical Account Manager:
  • An offline data provider ID.
  • An advertiser ID. If you are uploading measurement events for a buyer, use the buyer's advertiser ID.
• The Platform API and the Data API use different authentication methods. Be sure to use the correct method.
• Buyers may need to perform additional steps in the platform UI, such as setting up campaign attribution, after the offline tracking tag ID is generated.

The following table outlines the integration steps for uploading offline data.

1. Create an offline tracking tag

To create an offline tracking tag, use the POST /v3/offlinetrackingtag endpoint.

Here's what you need to know:

• You must have an advertiser ID and an offline data provider ID.
• The tracking tag name must be unique across all offline tracking tags, especially if shared between an advertiser and an offline provider.
• The tracking tag name will appear in the UI exactly as entered in the API. You can update it, if needed.
• You cannot change the AdvertiserId and OfflineDataProviderId values after creating the offline tracking tag. The combination of the two IDs establishes an advertiser-provider relationship and is required for looking up offline tracking tags.
• If you are uploading data on behalf of a buyer, be sure to provide the tracking tag name to the buyer so that they can find it and add it to their campaigns.

Here's an example of a POST /v3/offlinetrackingtag request.

{
    "AdvertiserId": "advert12",
    "TrackingTagName": "2022 Widget Phone Sales",
    "OfflineDataProviderId": "provid34"
}

When successful, the POST /v3/offlinetrackingtag response returns the ID of the newly created offline tracking tag. This ID is required for uploading offline conversion data.

{
    "AdvertiserId": "advert12",
    "TrackingTagId": "a1b2c3d4",
    "TrackingTagName": "2022 Widget Phone Sales",
    "OfflineDataProviderId": "provid34"
}

From the end user's perspective, an offline tracking tag looks like a static tag that would normally be placed on a domain. Ideally, this tracking tag name is human-readable.

2. Upload offline conversion events

TIP: If you have a Snowflake account, you can upload your conversion data using the The Trade Desk connector native app: Conversions.

To upload offline measurement events, you can use any of these:

• The POST /providerapi/offlineconversion endpoint. For the setup and request preparation guidelines, see the endpoint documentation. See also FAQs.
• The Data API SDK.
• Snowflake. See The Trade Desk connector native app: Conversions.
• Databricks. See TTD Connector for Databricks: Audience and conversion data SDK.

TIP: For real-world use cases and request samples, see Conversion event data examples and Merchant event data examples.

Offline tracking tag management tasks

You can perform the following common offline tracking tag management tasks using the platform API.

Look up tag details

#lookupindividualott

Get tag details for a specific offline tracking tag by its ID.

Endpoint: GET /v3/offlinetrackingtag/{trackingTagId}

Look up offline tracking tags

#lookupmultipleott

Get tag details by provider and advertiser.

Endpoint: POST /v3/offlinetrackingtag/query/advertiser

Notes: You can also filter search results by a specific part of the tracking tag name or ID by specifying the string in the SearchTerms property.

Update tag

#updateofflinetrackingtag

Update an offline tracking tag.

Endpoint: PUT /v3/offlinetrackingtag

Notes: You can update only the tracking tag name.

Look up details for a specific offline tracking tag by its ID

To retrieve the details for a specific offline tracking tag, use the GET /v3/offlinetrackingtag/{trackingTagId} endpoint. For example:

curl -L -X GET 'https://api.thetradedesk.com/v3/offlinetrackingtag/a1b2c3d4' -H 'Content-Type: application/json' -H 'TTD-Auth: {AuthToken}'

Look up all offline tracking tags for specific advertisers and providers

To look up all offline tracking tags that belong to a specific provider-advertiser ID combination, use the POST /v3/offlinetrackingtag/query/advertiser. For example:

{
    "OfflineDataProviderId": "provid34",
    "AdvertiserId": "advert12",
    "PageStartIndex": 0,
    "PageSize": 10
}

A successful response returns a list of all offline tracking tags for the specified IDs. For example:

{
    "Result": [
        {
            "AdvertiserId": "advert12",
            "TrackingTagId": "a1b2c3d4",
            "TrackingTagName": "2020 Widget Phone Sales",
            "OfflineProviderId": "provid34"
        }
    ],
    "ResultCount": 1,
    "TotalFilteredCount": 1,
    "TotalUnfilteredCount": 1
}

Look up offline tracking tags for specific advertisers and providers using search terms

To filter search results for offline tracking tags for a specific provider-advertiser ID combination, use the POST /v3/offlinetrackingtag/query/advertiser and include the SearchTerms property with the terms entered either in the TrackingTagId or TrackingTagName property values. For example:

{
    "OfflineDataProviderId": "provid34",
    "AdvertiserId": "advert12",
    "SearchTerms": "Phone Sales",
    "PageStartIndex": 0,
    "PageSize": 10
}

Here's an example of a successful response.

{
    "Result": [
        {
            "AdvertiserId": "advert12",
            "TrackingTagId": "a1b2c3d4",
            "TrackingTagName": "2022 Widget Phone Sales",
            "OfflineProviderId": "provid34"
        }
    ],
    "ResultCount": 1,
    "TotalFilteredCount": 1,
    "TotalUnfilteredCount": 1
}

Update an offline tracking tag name

To update the name of an offline tracking tag, specify the tag ID and the new tag name in a PUT /v3/offlinetrackingtag request. For example:

{
    "TrackingTagId": "a1b2c3d4",
    "TrackingTagName": "2022 Widget Phone and In-Person Sales"
}

FAQs

The following is a list of commonly asked questions about offline conversion events.

How do you de-duplicate conversions?

If duplicate conversions are received where the tracking tag ID, TDID or DAID, advertiser ID, campaign ID, monetary value, and order ID match, the platform chooses the earliest conversion based on the offline conversion time within the advertiser’s de-duplication window and then attributes the conversion if it has not yet been attributed.

Here's what you need to know about the de-duplication process:

• De-duplication is controlled by the user within advertiser preferences in the UI.
• The default de-duplication window setting is 60 seconds, but it can be extended up to 90 days.
• Only conversions with the offline conversion time within the last 29 days are attributed.
• You have the option of excluding order ID from the de-duplication logic.

Is it possible to use latitude and longitude for offline measurement?

Uploading conversion events that have a certain latitude and longitude can be accomplished by uploading the device and other IDs of users that pass through your geofence area. Narrow down what is sent to us by relying on an ad server, using our %%TTD_TDID%% and %%TTD_DEVICEID%% macros, and associating it to creatives served via the campaign. You could also restrict attribution by storing our impression ID, %%TTD_IMPRESSIONID%%, and sending that in your data mapping requests to the offline tracking tag you created.

Can I add merchant product catalog information when uploading offline conversions?

Yes. You can specify the product name, code, quantity, and price in a POST /providerapi/offlineconversion call in the Items.LineItems object array.

TIP: For real-world use cases and request samples, see Merchant event data examples.

What are the benefits of using TD01-TD10 in offline conversion?

The main benefit of using TD01-TD10 is on POST /providerapi/offlineconversion user reporting. Geography, price, cost, order numbers, and other optional information can be dynamically gathered from the advertiser's page and delivered back through reporting. Except for any user-level identifiers included in named fields (TDID, DAID, RampID, UID2, EUID, UID2Token, or EUIDToken), all other user-level identifiers (including but not limited to any IP addresses or user IDs) and any precise location data must be provided to the Offline Measurement API in fields TD8, TD9, or TD10.

How do you incorporate your own impression tracking?

If you are a marketplace provider, you can have your customers append an impression pixel to their creatives and put macros in place. If you'd like to automate this process, please reach out to your Technical Account Manager.

Can we use cross-device for incremental attribution?

Yes. We have direct integrations with cross-device vendors such as Drawbridge, Adbrain, Crosswise, and Tapad. This attribution reporting will show incremental lift and any dynamic parameters associated to the additional conversion, like order ID or shopping cart amount. Please let us know if you are using your own solution so clients are aware.

Is there a way to include or exclude users from audiences based on the attribution we upload?

Not directly through the pixels that are created by the provider. Instead, you would upload a segment to the user on the first-party endpoints (for advertisers uploading data) or third-party endpoints (for providers uploading data).

Is there a backfill limit from the time the event occurred and when I upload the data?

Avoid uploading anything longer than 25 days after the date the event occurred (as defined by the Items.TimestampUtc property). Subject to any contractual requirements or limitations, we generally prefer data to be sent as soon as possible from when the event occurred; for example, within a day or two after the event occurred.

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.