Skip to main content

The Trade Desk Conversions API Program for Offline Conversions

The Trade Desk Conversions API program enables LiveRamp customers who currently distribute data to The Trade Desk (TTD) to send conversion data to TTD. TTD performs attribution analysis on the impact of that advertiser’s TTD campaigns on conversions. This allows advertisers to understand how TTD campaigns drive offline conversions and to find additional data to better optimize ad spend or customer experience.

Note

  • See this one pager for a summary of this integration.

  • TTD must approve all program participants. Contact your LiveRamp or TTD rep to find out about getting approved for the TTD Conversions API program.

  • The Trade Desk Conversions API Program for Offline Conversions was formerly known as "the Trade Desk Conversions API Attribution Program".

Overview of Steps Involved

The following steps need to be performed for each campaign to enable the attribution analysis in TTD:

  1. You contact LiveRamp to set up an additional LiveRamp audience in Connect for the purposes of uploading conversion data for that campaign.

  2. At least two weeks before the start of your campaign, you upload a formatted sample conversion data file to the new audience that contains the transaction category and all of the custom fields that you plan to use.

  3. You activate a TTD Conversions API destination account in the Connect UI.

  4. You distribute the uploaded sample conversion data to the TTD destination account, which generates TTD’s required tracking tag.

  5. Apply the tracking tag to your campaign in TTD.

  6. You activate your campaign on TTD.

  7. You send your formatted offline (in store) conversion data from the last 30 days to LiveRamp.

  8. LiveRamp matches the offline identifiers to TDIDs and delivers matched data to TTD.

  9. TTD creates a conversion report.

  10. You view the conversion report in TTD.

See the appropriate sections below for more information on performing these steps.

Format the Conversion Data File

Before sending your conversion data to LiveRamp, make sure to strictly follow the guidelines listed below:

Note

Caution

If an uploaded file does not meet these requirements, you will need to reformat the file until it is formatted correctly.

  • Headers must be included in the exact order as listed below and must match exactly.

  • This program uses our Activation workflow. Make sure to follow our recommended file limits for Activation workflow files (such as a maximum of 500,000,000 rows per file and a maximum uncompressed file size of 50 GB).

  • Fields must not have leading or trailing white space.

  • Your conversion data file must use one of our allowed delimiters (commas, tabs, or pipes), and be one of our allowed file types (.csv, .tsv, .psv, or .txt).

  • Include all of the required columns shown in bold below, including all PII columns (even if a particular PII column does not have values).

  • Unless values are required for a field, fields can be left blank if there is no data for the given row (do not include “N/A” or “null”).

  • The file must be rectangular. That is every row must have the same number of delimiters and columns of data.

Tip

To download an Excel file template that contains all possible columns and formatting instructions, click here.

After transferring your data into the file template, be sure to delete the row with the formatting instructions and save the file in one of our allowed file types (.csv, .tsv, .psv, or .txt) before uploading.

Once the file has been formatted correctly, upload the file to LiveRamp. See the “Upload the File” section below for more information.

Note

Once you set up the file format for an existing attribution program feed, try to keep the file format (such as the column headers or the column order) the same for all subsequent files. If you change the file format for an existing feed, create a support case before uploading the new file to ensure your existing attribution feeds are not impacted. For more information, see "Changing the Format of an Existing File".

List of All File Columns

See the table below for a list of columns and formatting instructions:

Field Name

Column Required?

Values Required?

Notes

first_name

Yes

Yes (if Name and Postal is used as an identifier)

last_name

Yes

Yes (if Name and Postal is used as an identifier)

address_1

Yes

Yes (if Name and Postal is used as an identifier)

address_2

Yes

No

  • Include values in this column if you have additional street address info for a given row.

city

Yes

Yes (if Name and Postal is used as an identifier)

state

Yes

Yes (if Name and Postal is used as an identifier)

  • Must be a two-character, capitalized abbreviation ("CA", not "California" or "Ca").

zip

Yes

Yes (if Name and Postal is used as an identifier)

  • ZIP codes can be in 5-digit format or 9-digit format (ZIP+4).

email_1

Yes

Yes (if email is used as an identifier)

  • Can be plaintext or one of our allowed hash types (SHA-256, MD5, or SHA-1).

  • If you have multiple emails for a consumer, send your best one in the “email_1” column.

email_2

Yes

No

  • Can be plaintext or one of our allowed hash types (SHA-256, MD5, or SHA-1).

email_3

Yes

No

  • Can be plaintext or one of our allowed hash types (SHA-256, MD5, or SHA-1).

email_4

Yes

No

  • Can be plaintext or one of our allowed hash types (SHA-256, MD5, or SHA-1).

transaction_category

Yes

Yes

  • A category of event type or segment that the transaction is in (for example, “category_1”).

  • All rows in files for the same feed/audience should contain the same transaction category value.

  • If you need to use multiple transaction categories, use a separate feed for each transaction category.

transaction_timestamp

Yes

Yes

  • Corresponds to the date/time of transaction in UTC - (example “2017-02-07T13:25:00Z-0800" should be the time the conversion happened in UTC).

  • Standard formats:

    • yyyy-MM-dd

    • yyyy-MM-dd'T'HH:mm:ss'Z'-0000 (for example, 2021-06-04T10:01:00Z-0000)

  • Additional formats:

    • MM/dd/yyyy h:mm:ss aa

    • MM,dd,yyyy h:mm:ss

    • MM/dd/yyyy HH:mm:ss

    • yyyy-MM-dd HH:mm:ss

    • yyyy-MM-dd'T'HH:mm:ss

    • yyyy-MM-dd HH:mm:ssZ

transaction_amount

Yes

Yes

  • The transaction amount.

  • Do not include any (currency) symbols.

  • Format required: XXX.XX

phone_1

Yes

Yes (if phone is used as an identifier)

  • Do not include any hyphens or parentheses.

  • Can be plaintext or SHA-1 hashed.

  • If you have multiple phone numbers for a consumer, send your best one in the “phone_1” column.

phone_2

Yes

No

  • Do not include any hyphens or parentheses.

  • Can be plaintext or SHA-1 hashed.

TD10

Yes

Yes

  • The transaction or order ID, which should be a unique ID per transaction.

Value

No

No

  • The transaction amount (usually the same as the field “transaction_amount”).

  • Do not include any (currency) symbols.

  • Format Required: XXX.XX

ValueCurrency

No

No

  • The currency the transaction was paid in (i.e., “USD” or “CAD”).

  • Default value is “USD”.

Country

Yes

Yes

  • The country where the transaction occurred (for example, “USA”).

  • Must be in ISO3 format (for example, “USA” instead of “United States”).

Region

Yes

Yes

  • The region where the transaction occurred (for example, “New York”).

  • Must use full state names (for example, “California” instead of “CA”).

Metro

No

No

  • The metro area where the transaction occurred (for example, “501”).

City

No

No

  • The city where the transaction occurred (for example, “Brooklyn”).

Postal Code

No

No

  • The postal code where the transaction occurred (for example, “11223”).

TD1….. TD9

No

No

  • Optional custom reporting fields that can be used for user category or flags (such as region/store location or department).

  • Up to 9 can be included (for example, “TD1”, TD2”, etc.).

  • Do not use “TD10” (this is reserved for the transaction ID).

Header Row Example

first_name|last_name|address_1|address_2|city|state|zip|email_1|email_2|email_3|email_4|transaction_category|transaction_timestamp|transaction_amount|phone_1|phone_2|TD10|Country|Region|TD1|TD2

Conversion Data Examples

Alex|Chen|44 Main Street|#12|San Francisco|CA|94101|4371|alex@gmail.com|ac@ymail.com|||New Customer|2017- 02-07T13:25:00Z|99.99|555-123-4567|4152234123|USA|California|In-store|Bayfair Mall

Julian|Rogers|55 Mission Street||San Francisco|CA|94500|8435|julian@gmail.com||||Active Customer|2017- 03-07T15:15:00Z|127.18|555-999-4567|4152234124|USA|California|Outlet|Solano Mall

Send Conversion Data to LiveRamp

To set up the integration with TTD for each campaign, send LiveRamp a file that contains sample conversion data at least two weeks before the start of each campaign. The file must include the desired transaction category and all possible subcategories (contained in the custom fields (such as “TD1”, TD2”, etc.)) that you intend to use. This enables us to send TTD the required tracking tags that TTD will use to categorize your exposure data and associate each exposure to the correct transaction category and subcategory (if used).

Caution

Each campaign must use a single transaction category for all of the transactions in that campaign.

Once your campaign has started, send conversion data to LiveRamp at your preferred cadence (daily, weekly, monthly, etc.). We highly suggest automated weekly delivery as it gives LiveRamp the greatest ability to match

Caution

Most platforms require that at least 1,000 unique transaction events be uploaded over a 28-day period.

Conversion Data Guidelines

Each conversion data record must include at least one PII identifier (name and postal address, email, or phone) and the required conversion data:

Tip

Include as many identifiers per record as possible for the highest match rates.

Files must also contain the following required fields (all of these fields must be distributed to the TTD):

  • Transaction category

  • Transaction timestamp

  • Transaction amount

  • Country

  • Region

  • Transaction ID (the “TD10” field)

Make sure to also follow these additional guidelines:

  • Avoid sending duplicate transactions (transactions already sent to LiveRamp). If you send weekly or monthly files, only send transactions that occurred since the previous file was sent.

  • Do not include conversions with a conversion date in the future.

  • Conversion data should be uploaded within 30 days of the conversion.

Upload the File

Caution

When you upload your files, be sure to upload them to the appropriate audience for that campaign.

After uploading, email your LiveRamp technical account specialist to confirm that you have uploaded conversion data.

Note

For future uploads, you do not have to email LiveRamp to confirm that you have uploaded data assuming headers have not changed or additional columns have not been added.

Once the file is uploaded, information on file processing status can be viewed in LiveRamp Connect.

Tip

Most customers automate this process to send files on a regular cadence.

Email your LiveRamp technical account specialist if you have any questions.

Distribute Conversion Data to Your TTD Destination Account

Once you’ve uploaded your sample conversion data to the appropriate audience and and the fields are available to distribute in Connect, follow the instructions in “Distribute Data to a Destination” to send your data to the TTD:

  • Make sure to use the correct TTD Conversions API destination account for the campaign.

  • Use the Audience dropdown to filter the list by the audience for the campaign.

  • Distribute all required conversion fields and any optional fields that you want to be included in the attribution reports. Make sure to distribute all of these required fields:

    • Transaction category

    • Transaction timestamp

    • Transaction amount

    • Country

    • Region

    • Transaction ID (the “TD10” field)

Note

When the sample conversion data are distributed, tracking tags for all transaction categories and subcategories are generated and sent to TTD so TTD can properly attribute exposure and conversion data once your campaign starts.

After TTD has ingested the conversion data, you can view the attribution reports in the TTD UI.

FAQs

At what cadence should I send my conversion data files?

LiveRamp can receive conversion data files for the TTD Conversions API program on a daily, weekly, or monthly basis, but we highly suggest automated weekly delivery as it gives LiveRamp the greatest ability to match.

What conversion data should I include in my conversion data file?

Include all traceable transactions in your delivery.

Avoid sending duplicate transactions (transactions already sent to LiveRamp). If you send daily files, only include transactions that occurred on that day. If you send weekly or monthly files, only send transactions that occurred since the previous file was sent.

Do not include transactions with a transaction date in the future.

Can I upload multiple files containing portions of the complete dataset (one file split into multiple parts)?

No. Because these are “full refresh” uploads, each file replaces the data in the previously uploaded file. For a given audience/distribution, one file containing all relevant fields should be uploaded.

How long until will it take after I upload my data before I can view the attribution reports in the TTD UI?

It usually takes 1-3 days to get the data to TTD and then about 2 days for TTD to ingest the data.

How can I indicate the end date of my campaign so data stops being sent to TTD?

When creating the Conversions API destination account, you can set an end date that will turn off the distribution to TTD. It is up to your discretion if you’d like to continue sending data after media ends to capture additional conversions.

In this section:

In the context of LiveRamp Connect, a way to group your consumers within LiveRamp.