Skip to main content

The Facebook Conversions API Program for Offline Conversions

LiveRamp’s integration with the Facebook Offline Conversions API allows clients to enable attribution analysis of offline conversion data for ad campaigns that are run in the Facebook platform (including any Meta properties, such as Instagram, WhatsApp, and Audience Manager). You can send offline conversion data (such as in-store transactions or call center contacts) and conversion data for in-app purchases or other events.

Note

  • US customers will be implemented via the Meta Conversions API for Offline Conversions instead of Facebook Conversions API. EMEA customers can continue to follow this process.

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

When you send us conversion data, we match the records to Facebook users in our Identity Graph through LiveRamp custom IDs and deliver the conversion event data to Facebook. For PII-based conversion data files, we also deliver hashed PII (personally identifiable information) from the records to Facebook (“Passthrough Activation”), which increases match rates by allowing matches to be made for additional users that exist only in Facebook’s graph. Due to our robust match process with Facebook, we are able to provide you with not only an automated process, but also an optimized match rate for your conversions.

This attribution analysis is done by Facebook and is available in Facebook Ads Manager. Ad exposure data does not leave the Facebook platform.

Program Benefits

With the Offline Conversions API, you can measure how much your Facebook ads lead to real-world outcomes, such as purchases in your stores, phone orders, bookings and more, with Offline Events. To help you understand the effectiveness of your ad campaigns, Offline Events matches transactions from your physical stores or locations with metrics from people who saw or clicked on your ads.

Use Offline Events to:

  • Track offline activity and see how much of it can be attributed to your ads.

  • Measure the offline return on your ad spend.

  • Reach people offline and show ads to people based on the actions they take offline. You can also create lookalike audiences to deliver Facebook ads to people who are similar to your offline customers.

For more information on the optimizations you can perform with the attribution information in Facebook, see Facebook’s information on creating custom and lookalike audiences.

Overview of Steps Involved

The following steps need to be performed to enable the attribution analysis in Facebook:

  1. You send us a sample conversion data file and provide the ID for your Facebook Business Manager to your LiveRamp technical representative.

  2. LiveRamp creates an event set for you in LiveRamp’s Facebook Business Manager account. LiveRamp shares the event set to your Business Manager account and assigns “Advertiser” level permission to the event set.

  3. Before a campaign starts, you assign the event set to your Facebook campaign and ad accounts in your Business Manager account (once LiveRamp has shared the event set, you can use the same event set for future campaigns).

  4. You activate the campaign.

  5. You send conversion data to LiveRamp.

    Caution

    Conversion data must be uploaded within 62 days of the conversion event and within 90 days of the earliest attribution event (such as a click or a view) for that Facebook user. For each record, the conversion event must have happened within 7 days of the attribution event for that user.

  6. LiveRamp matches the data using our mapping of Facebook users and delivers your data to the appropriate event set in your Facebook Business Manager account.

  7. You view the attribution analysis in Facebook.

Note

Managing multiple campaigns? If you need to tie data from more than one campaign to your conversion data, you might need multiple event sets. Talk to your LiveRamp technical account representative to discuss this option.

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

Meta's Limited Data Use Feature

Meta's Limited Data Use (LDU) feature requires advertisers to specify when Meta should process data in accordance with its role as a service provider or processor with respect to people in states where Limited Data Use is available (currently California, Colorado, and Connecticut). This means that Meta will restrict the use of this data as specified in their state-specific terms.

All advertisers using this integration must include a “data_processing_options” column at the end of their transaction data files. This column will be the basis for LiveRamp to pass the appropriate LDU flags to the Facebook Conversions API.

Note

Meta does use the LDU-enabled transaction events for attribution reporting. For more information, see Meta’s LDU documentation.

Use one of the two allowed values for each row in this column:

  • Enter the value “LDU” (to indicate that LiveRamp should upload data to Meta with the LDU mode enabled) in either of the following situations:

    • 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

    • When you have opted to have Meta process data as a service provider, as defined by their state-specific terms.

    Entering "LDU" informs LiveRamp that we are to provide an LDU flag when uploading the event to the Facebook Conversions API. This flag enables LDU, and indicates to Meta that it should limit its use of personal information for that given event in accordance with their state-specific terms.

  • Enter the value “non-ldu” (to indicate that LiveRamp should upload data to Meta with the LDU mode disabled) for transactions where you would like LiveRamp to upload the event to the Meta Conversions API, explicitly indicating that Meta should not enable LDU.

Note

This column is not to identify the user as being from a specific state. Instead this column informs LiveRamp how to treat the data under specific state privacy laws.

Starting September 30, 2023, all advertisers will need to include two additional columns, “data_processing_options_state” and “data_processing_options_country” in addition to the “data_processing_options” column. The additional columns will allow LiveRamp to pass the appropriate state and country information when an advertiser has marked an event as “LDU.”

If an event is marked as “LDU,” then you will need to include one of the following possible values for each column.

Note

Do not enter any other values as it will cause issues with your conversion upload.

  • For the “data_processing_options_state” 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

  • For the “data_processing_options_country” column:

    • Enter “US” for United State of America

    • Enter “0” to request that Meta perform geolocation

If an event is marked as “non-ldu” (lowercase), then you will need to include these columns but no values.

Note

If you’re adding these columns to a file for an existing feed, create a support case before uploading the file so that we can adjust the column mapping. For more information, see “Announcement: Additional Data Processing Options Columns Required for Meta Attribution Programs (9/5/23)”.

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.

  • Each record in PII-based files must contain at least one PII identifier (such as name and postal, email, or phone).

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

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

  • Include the columns listed below, depending on the identifier type.

  • Each record must contain values for transaction category, timestamp, transaction amount, order ID, and data processing options.

  • The “data_processing_options” column must be populated with an "LDU" or "non-ldu" value. Do not leave this field blank. This column will be the basis for LiveRamp to pass the appropriate LDU (Limited Data Use) flags to the Facebook Conversions API.

  • PII-based files should include all PII columns, even if not all columns have values.

  • When sending files containing RampID s, AbiliTec IDs, or Custom IDs (CIDs), you must include all 10 “lr_id” columns for these identifiers (even if you don’t have 10 identifiers in each record).

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

Note

Each file goes to the same event set, unless you set up multiple event sets with your LiveRamp representative.

Tip

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

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.

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 conversions 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 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, if PII is used as an identifier (otherwise remove the column)

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

last_name

Yes, if PII is used as an identifier (otherwise remove the column)

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

address_1

Yes, if PII is used as an identifier (otherwise remove the column)

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

address_2

Yes, if PII is used as an identifier (otherwise remove the column)

No

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

city

Yes, if PII is used as an identifier (otherwise remove the column)

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

state

Yes, if PII is used as an identifier (otherwise remove the column)

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

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

zip

Yes, if PII is used as an identifier (otherwise remove the column)

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, if PII is used as an identifier (otherwise remove the column)

Yes (if email is used as an identifier)

  • Can be plaintext or SHA-256 hashed emails (Facebook does not accept MD5 or SHA-1 hashed emails).

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

email_2

Yes, if PII is used as an identifier (otherwise remove the column)

No

  • Can be plaintext or SHA-256 hashed emails (Facebook does not accept MD5 or SHA-1 hashed emails).

email_3

Yes, if PII is used as an identifier (otherwise remove the column)

No

  • Can be plaintext or SHA-256 hashed emails (Facebook does not accept MD5 or SHA-1 hashed emails).

email_4

Yes, if PII is used as an identifier (otherwise remove the column)

No

  • Can be plaintext or SHA-256 hashed emails (Facebook does not accept MD5 or SHA-1 hashed emails).

maid

Yes, if mobile advertising ID is used as an identifier (otherwise remove the column)

Yes (if this column is included)

  • Include only plaintext MAIDs (mobile advertising IDs such as IDFAs and AAIDs).

  • All MAIDs must be downcased and hyphenated.

lr_id

Yes, if RampID , AbiliTec ID, or Custom ID is used as an identifier (otherwise remove the column)

Yes (if this column is included)

  • Include 10 “lr_id” columns (lr_id1|lr_id2|LR_ID3|lr_id4|lr_id5|lr_id6|lr_id7|lr_id8|lr_id9|lr_id10) even if you do not have 10 identifiers per record

transaction_category

Yes

Yes

  • Used to track standard and custom events. If you are using a standard event, use one of the allowed event names in Meta’s documentation. For example, an event that occurs in stores would use the event name “Purchase.” Otherwise, we will use the values within the “transaction_category” field to create custom events for tracking in Meta.

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, such as dollar signs ($).

  • Format required: XXX.XX

  • Only include USD amounts. If your transaction data contains international currency amounts, convert your amounts to USD prior to sending your data.

phone_1

Yes, if PII is used as an identifier (otherwise remove the column)

Yes (if phone is used as an identifier)

  • Do not include any hyphens or parentheses.

  • Must be plaintext (no hashed phone numbers allowed).

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

phone_2

Yes, if PII is used as an identifier (otherwise remove the column)

No

  • Do not include any hyphens or parentheses.

  • Must be plaintext (no hashed phone numbers allowed).

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, Meta 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.

product_id

No

No

  • The item # or product SKU.

item_number

No

No

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

custom_field

No

No

  • You can include an unlimited number of custom fields (these are not used for matching offline events to people on Facebook, but can be used to create Custom Conversions in Facebook).

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

data_processing_options

Yes

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.

data_processing_options_state

Yes

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

data_processing_options_country

Yes

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

Header Row Examples

The headers shown in bold are required.

PII identifier files:

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|order_id|phone_1|phone_2|custom_field1|custom_field2|custom_field3|...etc|data_processing_options|data_processing_options_state|data_processing_options_country

MAID identifier files:

maid|transaction_category|transaction_timestamp|transaction_amount|order_id|item_number|custom_field1|custom_field2|custom_field3|...etc|data_processing_options|data_processing_options_state|data_processing_options_country

RampID, AbiliTec ID, or Custom ID identifier files:

lr_id1|lr_id2|LR_ID3|lr_id4|lr_id5|lr_id6|lr_id7|lr_id8|lr_id9|lr_id10|transaction_category|transaction_timestamp|transaction_amount|order_id|item_number|custom_field1|custom_field2|custom_field3|...etc|data_processing_options|data_processing_options_state|data_processing_options_country

Conversion Data Examples For PII Identifier Files

Alex|Chen|44 Main Street|#12|San Francisco|CA|94100|alex@gmail.com|ac@ymail.com||||In-store|2014-03-31|99.99|1234567890|5553126556|non-ldu
Julian|Riediger|55 Mission Street||San Francisco|CA|94500|julian@gmail.com||||PhoneSales|2014-03-30|55.55|2223334444|5556400808|LDU

Send Conversion Data to LiveRamp

To set up the integration, send us a sample conversion data file. This file should contain at least 25 rows and each row should have values for the required fields (you can use placeholder data). Include all the possible transaction category values you plan on using in the “transaction_category” field and include only those values in subsequent files.

Once your campaign has started, send conversion data to LiveRamp at your preferred cadence. Files can be delivered at any cadence (daily, weekly, monthly, etc.), but do not send more than one file per day.

Tip

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

Caution

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

Conversion Data Guidelines

All conversion data files must include identifiers (such as PII or MAIDs) and the required conversion data:

  • Transaction category

  • Transaction timestamp

  • Transaction amount

  • Order ID

  • Data processing options

  • Data processing options state

  • Data processing options country

Other optional conversion data (such as item number or quantity) can be included as well. See the “Format the File” section below for more information.

Lookback Window

Conversion data must be uploaded within 62 days of the conversion event and within 90 days of the earliest attribution event (such as a click or a view) for that Facebook user. For each record, the conversion event must have happened within 7 days of the attribution event for that user.

Do not include conversion data that has already been sent in a previous file.

Upload the File

Upload conversion data files using LiveRamp’s SFTP server or your SFTP server.

You can also have us pull files from an AWS S3 bucket or GCS bucket. See “Getting Your Data Into LiveRamp” for more information.

Caution

Files for this program cannot be uploaded via Connect. We recommend either uploading via our SFTP server or having us pull files from an S3 bucket.

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 Connect (see "Check File Processing Status" for more information).

The conversion data can usually be viewed in Facebook 4-7 days after upload.

Tip

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

Files can be delivered at any cadence (daily, weekly, monthly, etc.), but do not send more than one file per day.

Check File Processing Status

You can check the status of the files you've uploaded on the Files page in Connect. See "Check the Status of an Uploaded File" for complete instructions.

Note

  • Once you've uploaded a file, it can take up to 20 minutes before the file appears associated with the appropriate audience(s) on the Files page. If the file does not appear after at least 20 minutes, create a support case.

  • Files for this program use our Measurement Enablement workflow, and so the column headings that display on the Files page will look different from the ones that display for files that use our Activation workflow.

  • When you open the details pane on the Files page, all of the stats for RampIDs will always show “0” since we are matching to Facebook CIDs.

Assign the Dataset ID in Meta

After LiveRamp creates the Dataset ID in LiveRamp’s Meta Business Manager account, you will receive a notification in your Meta Business Manager account. Before a campaign starts, you need to assign that Dataset ID to your Meta campaign and ad accounts in your Business Manager account. The Dataset ID needs to be assigned so that conversion data can be attributed to the appropriate campaign.

Tip

Once LiveRamp has shared the Dataset ID, you can use the same Dataset ID for future campaigns.

Note

Why does LiveRamp create the Dataset ID? In order to upload data via the Meta Conversions API, LiveRamp needs to use an Admin-level access token in our API requests. For a seamless experience for our clients and to make setup as frictionless as possible, we upload data to Dataset IDs that LiveRamp owns.

To assign the event set, navigate to Business Settings > Data Sources > Offline Event Sets in the Facebook UI and assign the appropriate ad accounts to your event set (see the image below).

1563831450253-PCs.png

Caution

We can only deliver data to an "event_name" of "Purchase."

Note

If your situation requires multiple Dataset IDs, discuss this with your LiveRamp representative.

FAQs

What is an event set?

An event set is essentially a bucket that is created in the Facebook platform. You can upload conversion data from your stores or locations to Events Manager so that you can attribute offline events and transactions to your Facebook ad campaigns. Read more about Facebook Offline Events here.

Why does LiveRamp need to create the event set ID for us? Why can't we create the offline event set directly in our own Business Manager?

In order to upload data via the Facebook Conversions API, LiveRamp needs to use an Admin-level access token in our API requests. For a seamless experience for our clients and to make setup as frictionless as possible, we upload data to event sets that LR owns and has shared to your Business Manager.

Where can I find the event sets that LiveRamp shared with me?

You can view your available event sets in the Facebook Events Manager.

What event types does LiveRamp support?

Although you can upload any desired conversion type, we only support “Purchase” event types in our integration with Facebook so all events will be labeled as “purchases” in Facebook’s UI.

What identifier types do you support?

We currently support name and postal (NAP), emails, phone numbers, Abilitec IDs, LiveRamp RampID s, MAIDs (mobile advertising IDs such as IDFA and AAID), and CIDs (as long as they are based off of offline PII).

What regions are supported?

Currently the U.S. and France are supported. However, all transaction amounts must be entered in USD.

Why is the number of events delivered in the Facebook UI greater than the number of rows in my original transaction file?

The number of events that populates in the Facebook Events Manager UI is the number of events delivered before any de-duplication occurs. It is possible that data from one transaction can resolve to multiple Facebook users (for example, a shopper might use their mom’s email for the loyalty card but have their own address).

Today, the Facebook Offline Conversions API only accepts one Facebook user per event, so in the case that there are multiple Facebook users linked to a transaction, they will be delivered in separate “events”. Facebook eventually does de-duplicate on the order_id, but currently this post-deduplication count is not surfaced in the Events Manager UI.

Why am I seeing that X% of events are duplicates in the Facebook Events Manager UI?

The Facebook Conversions API only supports uploading a single ID per transaction event uploaded. Each event uploaded via the API is registered as an “event uploaded” in the UI, but is then deduplicated in the Facebook platform via Facebook’s deduplication logic. Matching your data via LiveRamp can initially result in more than one ID being delivered for the same transaction, which would result in seemingly duplicate event data being uploaded.

There are two parts of the LiveRamp match process that can contribute to this effect:

The first is the nature of our Facebook integration. LiveRamp does not know which set of PII a person has shared with Facebook. Therefore, LiveRamp may send the same person to Facebook multiple times with different combinations of PII which may match to different Facebook users for the same event.

The second is having more than one RampID per record. Having multiple sets of PII in a record can increase match rates significantly as it increases the number of RampID s we match for each record, effectively increasing the number of IDs we deliver with a particular event to Facebook.

In this section: