Skip to main content

The Meta Conversions API Program for Offline Conversions

LiveRamp’s integration with the Meta 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

When you send us offline conversion data, we match the records to Meta users in our Identity Graph through LiveRamp RampIDs and deliver the conversion event data to Meta.

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

Program Benefits

With the Meta Conversions API, you can measure how much your ads on Meta properties 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 ads on Meta properties to people who are similar to your offline customers.

Overview of Steps Involved

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

  1. You send a sample conversion data file to your LiveRamp technical representative.

  2. You create a Dataset ID or share an existing Pixel or Dataset ID to LiveRamp's Business Manager account and assign "use events dataset" level permission to the dataset.

  3. Before a campaign starts, you assign the dataset to your Meta campaign and ad accounts in your Business Manager account.

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

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

  7. You view the attribution analysis in Meta.

Note

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

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

Create Dataset IDs and Share with LiveRamp

For LiveRamp to upload conversion data to your Meta account, you need to create Dataset IDs and share those Dataset ID(s) to LiveRamp’s Business Manager.

Note

If you already have an existing Pixel ID/Dataset ID (if you’are already sending online events via LiveRamp through the ATS Facebook Conversions API adapter or directly to Meta), you can use that Pixel/Dataset ID. LiveRamp will work with Meta to migrate your Pixel ID to a DatasetID. Your LiveRamp representative will let you know when this has been completed.

  1. Follow Meta’s instructions to create a Dataset ID.

  2. Once the Dataset ID(s) have been created (or migrated), go to Settings in Meta Business Manager and enable “allow historical conversion uploads”. This allows LiveRamp to upload history to your Dataset ID(s).

    C-Meta_CAPI_Offline-allow_uploads_toggle.png

  3. Click Share with a business.

    C-Meta_CAPI_Offline-share_with_business.png

  4. Select "Assign Partners".

  5. Enter LiveRamp’s Business Manager ID (705664196188477) in the Partner business ID field.

    C-Meta_CAPI_Offline-partner_business_ID.png

  6. Enable the “Use events dataset” toggle and then click Next.

  7. Navigate to Business Settings > Data Sources > Datasets and assign the appropriate ad accounts and campaigns to your Dataset by clicking Add assets.

    C-Meta_CAPI_Offline-add_assets_button.png

  8. Search for the ad account by name or ID.

  9. Select Add.

  10. When adding campaigns, select Offline Events.

    C-CAPI_Migration-Offline_Events_checkbox.png

  11. If you created new Dataset ID(s) in the earlier step, share those with your LiveRamp representative.

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

  • The Meta Conversions API program for offline conversions 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 Meta 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. You can download the Meta Conversions API 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)

  • Include only plaintext 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

  • Include only plaintext emails.

email_3

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

No

  • Include only plaintext emails.

email_4

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

No

  • Include only plaintext 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. For the custom event to be included in Meta’s Ad Manager, you will need to create a custom conversion in Meta Business Manager (for Meta’s instructions, click here).

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

    • MMM 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 Meta properties, but can be used to create Custom Conversions in Meta Business Manager).

  • 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” if a transaction is tied to where a person in California has opted out of the sale of data or that the business has opted to have Meta process data as a service provider, as defined by the CCPA. See the “Meta 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.

FAQs

What is a dataset?

A dataset is essentially a bucket that is created in the Meta. You can upload conversion data from your stores or locations to Events Manager so that you can attribute offline events and transactions to your Meta ad campaigns. Read more about Meta datasets here.

Where can I find my dataset?

You can view your available datasets in the Meta Events Manager.

How do I determine if I have a Pixel or Dataset ID?

You can search for your ID in Meta Events Manager. Once you click into the ID, it will tell you the ID type on the right side of the screen.

C-Meta_CAPI_Offline-dataset_ID.png

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 only the US is supported. All transaction amounts must be entered in USD.

Why is my custom event not showing up in Meta Ad Manager?

In order for a custom event to show up in Ad Manager reporting, you need to set up a custom conversion in Meta Business Manager (for Meta’s instructions, click here).

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

The number of events that populates in the Meta 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 Meta users (for example, a shopper might use their mom’s email for the loyalty card but have their own address).

Today, the Meta Conversions API only accepts one Meta user per event, so in the case that there are multiple Meta users linked to a transaction, they will be delivered in separate “events”. Meta 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 Meta Events Manager UI?

The Meta 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 Meta platform via Meta's deduplication logic. Matching your data via LiveRamp can initially result in more than one RampID being delivered for the same transaction, which would result in seemingly duplicate event data being uploaded.

Having multiple sets of PII in a record can increase match rates significantly as it increases the number of RampIDs we match for each record, effectively increasing the number of Ramp IDs we deliver with a particular event to Meta.

In this section: