Skip to main content

Using a Universal File for Multiple Conversions API Programs

With LiveRamp’s Partner Conversions API programs, you can often use one universal file for most or all of your conversions programs.

Note

  • Our Conversions API programs were formerly known as "attribution programs".

  • There are some situations where we recommend creating separate files or a completely new file. This to ensure that there are no disruptions to your existing conversions feeds.

See the sections below for more information on using a universal file for your conversion data files.

Situations That Require Additional Files

If you’re working with any of the conversions programs listed below, you might need to create additional files or use a different file template:

Note

When you’re sending multiple files, make sure to name each file distinctly so that it’s easier for us to send the data to the correct program(s).

  • The Trade Desk: If you have multiple values for the transaction category field, then you will need to create a separate file for each value. This is to ensure that LiveRamp does not remove any event data.

  • Facebook or Meta Conversions API Program for Offline Conversions:

    • If you’re sending RampIDs, AbiliTec IDs, MAIDs, or CIDs, you need to send those in a separate file that does not include the PII columns. For Facebook, you can download the non-PII identifier template for that data by clicking here. For Meta, you can download the non-PII identifier template for that data by clicking here.

    • If you’re sending PII to the Facebook or Meta Conversions API Program for Offline Conversions and other programs, you can use the regular universal file template which does not include the “maid” or “lr_id” columns.

  • Meta Conversions API for Offline Conversions: You will need to include only plaintext email addresses and/or plaintext phone numbers in the email and phone columns in the file.

  • Google Store Sales, Snapchat or TikTok: These programs use our Passthrough Activation integration to pass through SHA256-hashed PII, so you will need to include plaintext email addresses and/or plaintext phone numbers in the "email_1" and "phone_1" columns in the file so that we can hash those values. If desired, you can also include hashed email addresses and/or phone numbers in the other email or phone columns but they will not be utilized by these programs.

  • Snapchat: If you are sending online conversion data, you will need to create a separate file for that online data, as the other conversions programs only allow offline conversion data.

File Format for the Universal File

See the sections below for information on formatting guidelines, information on using our universal file template, and a table that lists all possible columns you might include in your universal file.

Formatting Guidelines for the Universal File

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

Note

If any guidelines listed here conflict with the guidelines in our general file formatting instructions, follow these guidelines.

Caution

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

  • Make sure to include all required columns with the exact column headers as shown.

  • Make sure to keep the columns up to and including the phone number columns in the exact order as shown. After those columns, the remaining columns can be in any order.

  • Provide the recommended values when possible. If you do not have values for a required field, include the column but with no values (do not include “N/A” or “null”).

  • Provide plaintext (raw) PII when possible as this is required for the programs that use a Passthrough Activation integration . For more information, see the "Situations That Require Additional Files" section above.

  • Provide your best email and phone for the user that you are trying to measure in columns “email_1” and “phone_1” (try to keep each column as close to a 100% fill rate as possible).

  • Not all programs utilize every column in the universal file. See the table in the "List of All Universal File Columns" section below to understand which programs utilize which fields so that you know which columns you can leave out.

  • If you're sending data on EMEA and/or UK consumers to Google Store Sales, you must also include the "ad_user_data" and "ad_personalization" columns listed in the "List of All Universal File Columns" section below. For all other regions, these columns are optional. For more info on Google's consent policy, see this Google article.

  • 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).

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

Using the Universal File Template

To make things easier for you, we've created a universal file template that you can use.

Note

The template contains formatting instructions in the second row of the file, along with info on whether a column is required and whether values are required, depending on which conversions programs you're using. You can also refer to the information in the "List of All Universal File Columns" section below.

  1. Download the file template by clicking here.

  2. If desired, you can remove any non-required columns that aren't utilized by one of your conversions programs, but you can also leave those columns in the file and not populate them with values.

  3. Transfer your data into the template.

  4. After transferring your data into the file template, delete the second row with the formatting instructions.

  5. Save the file in one of our allowed file types (.csv, .tsv, .psv, or .txt).

  6. Upload the file to LiveRamp.

List of All Universal File Columns

The table below lists all possible columns you might include in your universal file, along with the following information:

  • The columns that are always required

  • The columns that are required in certain situations, such as the types of identifiers you're sending or the conversions programs you're using

  • Whether values are required for each column

  • Formatting instructions for column values

  • Which columns are utilized by which conversions programs, when applicable

Column Name

Column Required?

Values Required?

Notes

Programs That Utilize This Field

first_name

Yes

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

  • Must be plaintext.

last_name

Yes

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

  • Must be plaintext.

address_1

Yes

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

  • Must be plaintext.

address_2

Yes

No

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

  • Must be plaintext.

city

Yes

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

  • Must be plaintext.

state

Yes

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

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

  • Must be plaintext.

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).

  • Must be plaintext.

email_1

Yes

Yes (if email is used as an identifier)

  • Must be plaintext if using this file for Meta Conversions API, Google Store Sales, Snapchat, or TikTok.

  • Can be SHA-256 hashed if not using this file for Meta Conversions API, Google Store Sales, Snapchat, or TikTok.

  • Can be MD5 or SHA-1 hashed if not using this file for Facebook, Google Store Sales, Snapchat, or TikTok.

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

email_2

Yes

No

  • Must be plaintext if using this file for Meta Conversions API, Google Store Sales, Snapchat, or TikTok.

  • Can be SHA-256 hashed if not using this file for Meta Conversions API, Google Store Sales, Snapchat, or TikTok.

  • Can be MD5 or SHA-1 hashed if not using this file for Facebook, Google Store Sales, Snapchat, or TikTok.

email_3

Yes

No

  • Must be plaintext if using this file for Meta Conversions API, Google Store Sales, Snapchat, or TikTok.

  • Can be SHA-256 hashed if not using this file for Meta Conversions API, Google Store Sales, Snapchat, or TikTok.

  • Can be MD5 or SHA-1 hashed if not using this file for Facebook, Google Store Sales, Snapchat, or TikTok.

email_4

Yes

No

  • Must be plaintext if using this file for Meta Conversions API, Google Store Sales, Snapchat, or TikTok.

  • Can be SHA-256 hashed if not using this file for Meta Conversions API, Google Store Sales, Snapchat, or TikTok.

  • Can be MD5 or SHA-1 hashed if not using this file for Facebook, Google Store Sales, Snapchat, or TikTok.

transaction_category

Yes

Yes

  • Enter a “transaction category” value in this field for each transaction row, such as something like "store sales."

  • Include all possible values in the initial file, and include only those values in subsequent files.

  • Use 1 value in order to support all conversions programs

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)

transaction_amount

Yes

Yes

  • The transaction amount.

  • Do not include any (currency) symbols.

  • Do not include any negative amounts, such as a return.

  • Format required: XXX.XX

phone_1

Yes

Yes (if phone is used as an identifier)

  • Do not include any hyphens or parentheses.

  • Must be plaintext if using this file for Meta Conversions API, FBOC, Google Store Sales, Snapchat, or TikTok.

  • Can be SHA-1 hashed if using this file only for Google Campaign Manager, The Trade Desk, Pinterest, Nextdoor, Yelp, Bing, Criteo, StackAdapt, Spotify, or Yahoo!.

  • 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.

  • Must be plaintext if using this file for Meta Conversions API, FBOC, Google Store Sales, Snapchat, or TikTok.

  • Can be SHA-1 hashed if using this file only for Google Campaign Manager, The Trade Desk, Pinterest, Nextdoor, Yelp, Bing, Criteo, StackAdapt, Spotify, or Yahoo!.

order_id

Yes

Yes

  • A unique ID (such as a transaction ID) that corresponds to the order that the particular item belongs to (this is often referred to as an “ordinal”). If the value is not unique, a partner may deduplicate some of these events when ingesting your conversion data.

  • To measure item-level events, the value will need to be a unique value for each item within a basket. LiveRamp recommends using the concatenated value of the order ID + product SKU. For example, if the  order ID is “123” and SKU is “456”, the “order_id” value would be “123456”.

  • Do not include special characters, currency symbols, or commas.

item_number

No

Yes (if this column is included in the file)

  • A number delineating a unique item in an order. For example, if three socks are purchased in one transaction, you could have three transaction rows with different item numbers for each pair of socks but the same order ID.

  • Do not include special characters, currency symbols, or commas.

  • Meta Conversions API

  • FBOC

  • TTD

quantity

Yes

Yes (if this column is included in the file)

  • The quantity of the items purchased.

  • If blank or null, this will default to a value of 1.

  • For Google Campaign Manager, see Google Campaign Manager's Help Article to understand how this field impacts reporting.

  • Google Campaign Manager

  • Pinterest

  • Yelp

  • Criteo

  • StackAdapt

  • TikTok

product_id

No

Yes (if this column is included in the file)

  • An alphanumeric value delineating a unique item in an order.

  • Do not include special characters, currency symbols, or commas.

  • Common product identifier types include UPC, ISBN, Brand, and MPN.

  • Meta Conversions API

  • FOBC

  • Pinterest

  • Criteo

  • StackAdapt

  • TikTok

store_id

No

Yes (if this column is included in the file)

  • A "shop code." A unique ID that clients assign to each of their store locations.

  • Must not be longer than 64 characters.

  • Must not include special characters (i,e., "<" or ">") or contain a URL.

  • Google Store Sales Improvements

  • Criteo

  • StackAdapt

Country

Yes (for TTD only)

Yes (if this column is included in the file)

  • The 3-digit ISO 3166 country code where the transaction occurred (for example, “USA”).

  • TTD

Region

Yes (for TTD only)

Yes (if this column is included in the file)

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

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

  • TTD

Metro

No

No

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

  • TTD

City

No

No

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

  • For The Trade Desk, this field is used for attribution and not for matching. Make sure the field header is “City” and not “city” in order to distinguish the field for matching VS attribution.

  • TTD

product_name

No

No

  • Short name of the product.

  • Pinterest

  • Criteo

  • StackAdapt

  • TikTok

promo_code

No

No

  • Promotion code that was used for the purchase.

  • Pinterest

  • Criteo

  • StackAdapt

product_category

No

No

  • Top-level category of the product.

  • Pinterest

  • Criteo

  • StackAdapt

  • TikTok

product_subcategory

No

No

  • Subcategory of the product.

  • Pinterest

  • Criteo

  • StackAdapt

product_variant

No

No

  • Can include any product variation identifiers of the product.

  • Pinterest

  • Criteo

product_brand

No

No

  • Brand name of the product.

  • Pinterest

  • Criteo

  • StackAdapt

  • TikTok

source_type

Yes (for Snapchat only and only if sending online data)

Yes (if this column is included in the file)

Use one of the following source types:

  • app_android

  • app_ios

  • web

  • Snapchat

is_new_customer

No

No

  • Identifies whether the customer is a new or existing customer:

    • “Y” is new customer

    • “N” is existing customer

  • Pinterest

product_price

No

No

  • The product price.

  • Do not include currency symbols (for example, “XX.XX”).

  • StackAdapt

  • TikTok

GTIN

No

No

  • Global Trade Item Number (GTIN) is a unique and internationally recognized identifier for a product.

  • StackAdapt

department

No

No

  • The department for the product.

  • StackAdapt

brand

No

No

  • The name of the brand.

  • StackAdapt

custom_field

No

No

  • You can include an unlimited number of custom fields in order to create custom conversions.

  • Custom field column headings must start with "custom_", followed by the field name. For example "custom_store_ID".

  • Create separate custom fields for each partner due to specific nuances and requirements.

  • Meta Conversions API

  • FBOC

  • Google Campaign Manager

  • Google Store Sales

  • TTD

  • Nextdoor

  • Yelp

  • StackAdapt

data_processing_options

Yes (for Meta Conversions API or FBOC only)

Yes

  • Enter a value of “LDU” when an event is tied to a person who is subject to a state Privacy Act and who has opted out of the sale of their data, or when you have opted to have Meta process data as a service provider, as defined by their state-specific terms. See the “Meta's Limited Data Use Feature” section of this article for more information.

  • Enter the value “non-ldu” to indicate that LiveRamp should upload data to Meta with the LDU mode disabled.

  • Meta Conversions API

  • FBOC

data_processing_options_state

Yes (for Meta Conversions API or FBOC only)

No

  • Enter one of the following values if you entered a value of “LDU” for the “data_processing_options” column:

    • Enter “CA” for users located in California

    • Enter “CO” for users located in Colorado

    • Enter “CT” for users located in Connecticut

    • Enter “0” to request that Meta perform geolocation

  • Meta Conversions API

  • FBOC

data_processing_options_country

Yes (for Meta Conversions API or FBOC only)

No

  • Enter one of the following values if you entered a value of “LDU” for the “data_processing_options” column:

    • Enter “US” for United State of America

    • Enter “0” to request that Meta perform geolocation

  • Meta Conversions API

  • FBOC

ad_user_data

Yes (for UK and EMEA data)

No

  • This column is only required if the file contains UK or EMEA data.

  • Enter "granted" to confirm that the consumer has consented to the use of their data.

  • if no value is entered, LiveRamp will mark the event as "unspecified" on your behalf.

  • Google Store Sales

ad_personalization

Yes (for UK and EMEA data)

No

  • This column is only required if the file contains UK or EMEA data.

  • Enter "granted" to confirm that the consumer has consented to ad personalization.

  • if no value is entered, LiveRamp will mark the event as "unspecified" on your behalf.

  • Google Store Sales

In this section: