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:
You send us a sample conversion data file and provide the ID for your Facebook Business Manager to your LiveRamp technical representative.
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.
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).
You activate the campaign.
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.
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.
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
If any guidelines listed here conflict with the guidelines in our general file formatting instructions, follow these guidelines.
If you're using multiple programs, you can often use one universal file for most or all of those programs. For more information and a universal file template, see "Using a Universal File for Multiple Conversions API Programs".
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 |
|
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) |
|
zip | Yes, if PII is used as an identifier (otherwise remove the column) | Yes (if Name and Postal is used as an identifier) |
|
email_1 | Yes, if PII is used as an identifier (otherwise remove the column) | Yes (if email is used as an identifier) |
|
email_2 | Yes, if PII is used as an identifier (otherwise remove the column) | No |
|
email_3 | Yes, if PII is used as an identifier (otherwise remove the column) | No |
|
email_4 | Yes, if PII is used as an identifier (otherwise remove the column) | No |
|
maid | Yes, if mobile advertising ID is used as an identifier (otherwise remove the column) | Yes (if this column is included) |
|
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) |
|
transaction_category | Yes | Yes |
|
transaction_timestamp | Yes | Yes |
|
transaction_amount | Yes | Yes |
|
phone_1 | Yes, if PII is used as an identifier (otherwise remove the column) | Yes (if phone is used as an identifier) |
|
phone_2 | Yes, if PII is used as an identifier (otherwise remove the column) | No |
|
order_id | Yes | Yes |
|
product_id | No | No |
|
item_number | No | No |
|
custom_field | No | No |
|
data_processing_options | Yes | Yes |
|
data_processing_options_state | Yes | No |
|
data_processing_options_country | Yes | No |
|
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.
To upload files using LiveRamp's SFTP: Use the credentials provided by your technical contact once the agreement has been signed and follow the instructions in “Upload a File via LiveRamp's SFTP”.
To upload files using your SFTP: Follow the instructions in “Upload a File via Your SFTP”.
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).
 |
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?
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 LiveRamp owns and has shared with 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 on 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 populate 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 this post-deduplication count is currently 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 uploaded transaction event. 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.