Configure events for Meta Ads Manager

Send events to Meta Ads Manager to help your brand track offline conversions that result from your marketing campaigns. Events may be matched with audiences in Facebook, Facebook Messenger, Instagram, and WhatsApp.

Transaction events that occurred within the previous seven days and contain positive values for product quantity may be sent to Meta Ads Manager using the Conversions API for events .

Important

The first time transaction events are sent to Meta Ads Manager, and when action_source is set to physical_store, up to 62 days of transactions data may be sent, after which Amperity should be configured to send updates that maintain a 7-day rolling window of transaction events.

Note

Events are not immediately available in Meta Ads Manager. Allow for up to 24 hours after the point at which Amperity has finished sending events for them to be available.

Events that are sent to Meta Ads Manager can be accessed from Meta Events Manager .

Caution

The values for EMAIL, PHONE, FN, LN, ST, CT, ZIP, COUNTRY, GEN, and EXTERN_ID sent to Meta Ads Manager are SHA-256 hashed automatically by Amperity before sending. Do not use the TO_HEX() function with the EMAIL, PHONE, FN, LN, ST, CT, ZIP, COUNTRY, GEN, and EXTERN_ID fields for queries that return results for Meta Ads Manager.

Get details

Review the following details before configuring credentials for Meta Ads Manager and before configuring Amperity to send events to Meta Ads Manager.

	Credential settings Refresh token Required A refresh token is generated by the OAuth process and authorizes Amperity to send data to Meta Ads Manager. The value for the refresh token is automatically updated.
	Meta Ads Manager settings Dataset ID May be required at orchestration Datasets connect and manage event data from different sources–such as from websites, mobile apps, physical store locations or business chats–from one location. A dataset ID configured in Meta Ads Manager supports sending send events from Amperity.

Configure credentials

Configure credentials for Meta Ads Manager before adding a destination.

An individual with access to Meta Ads Manager should use SnapPass to securely share “refresh token” details with the individual who configures Amperity.

To configure credentials for Meta Ads Manager events

	From the Settings page, select the Credentials tab, and then click the Add credential button.
	In the Credentials settings dialog box, do the following: From the Plugin dropdown, select Meta Ads Manager. Assign the credential a name and description that ensures other users of Amperity can recognize when to use this destination.
	The settings that are available for a credential vary by credential type. For the “facebook” credential type, configure settings, and then click Save. Refresh token Required A refresh token is generated by the OAuth process and authorizes Amperity to send data to Meta Ads Manager. The value for the refresh token is automatically updated.

Reauthorize Amperity

You may need to reauthorize access to Meta Ads Manager. This is necessary when an authorization token has expired or when it has been removed by someone with permission to manage access within Meta Ads Manager. To reauthorize access to Meta Ads Manager, follow the steps to configure OAuth and create a new credential.

Terms of service

The custom audience terms of service must be signed by each business user that is associated with your Meta Ads Manager account. If the terms of service are not signed, a permissions error prevents Amperity from sending data to Meta Ads Manager.

The permissions error is similar to:

Permissions error: To create or edit an audience with an uploaded
customer list, please agree to the Custom Audience terms at
https://business.facebook.com/ads/manage/customaudiences/tos/?act=123.

To resolve this error the terms of service must be signed by a business user who has a role in your Meta Ads Manager account.

Add destination

Use a sandbox to configure a destination for Meta Ads Manager. Before promoting your changes, send a sample audience, and then verify the results in Meta Ads Manager. After verifying the end-to-end workflow, push the destination from the sandbox to production.

To add a destination

	Open the Destinations tab to configure a destination for Meta Ads Manager. Click the Add Destination button to open the Destination dialog box. Enter the name of the destination and a description. For example: “Meta Ads Manager events” and “Send events to Meta Ads Manager.”.
	Credentials allow Amperity to connect to Meta Ads Manager. The credential type is set automatically. You may use an existing credential or you may add a new one. Select an existing credential from the Credential dropdown. – or – Select Create a new credential from the Credential dropdown. This opens the Credential dialog box. Meta Ads Manager requires using OAuth to authorize Amperity to send events to your Meta Ads Manager account. Note You may use the same credentials to send both custom audiences and events to Meta Ads Manager.
	In the “Destination settings” dialog box, assign the destination a name and description that ensures other users of Amperity can recognize when to use this destination. Configure business user access By default a destination is available to all users who have permission to view personally identifiable information (PII). Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies. Enable the PII setting checkbox to allow limited access to PII for this destination. Use the Restrict PII access policy option to prevent users from viewing data marked as PII anywhere in Amperity and from sending data to downstream workflows.
	Configure the following settings, and then click “Save”. Dataset ID May be required at orchestration Datasets connect and manage event data from different sources–such as from websites, mobile apps, physical store locations or business chats–from one location. A dataset ID configured in Meta Ads Manager supports sending send events from Amperity.
	After configuring this destination users may use orchestrations to send query results Meta Ads Manager.
	Validate the audience with Meta Ads Manager by using a sample audience with a very small membership. For example: 10 or 100 members or the minimum audience size recommended by Meta Ads Manager. Send the sample audience to Meta Ads Manager and verify the sample audience is correct in Meta Ads Manager. Make adjustments if necessary. Only send full audiences after validation is complete.

Build a query

Use a query to build a combination of data from the Unified Itemized Transactions, Unified Transactions, and Customer 360 tables to represent the set of events that your brand wants to use within Meta Ads Manager.

A query that returns a collection events for use in Meta Ads Manager is similar to:

SELECT
  c360.amperity_id AS external_id
  ,c360.email AS email
  ,c360.phone AS phone
  ,c360.given_name AS given_name
  ,c360.surname AS surname
  ,c360.birthdate AS birthdate
  ,c360.gender AS gender
  ,c360.city AS city
  ,c360.state AS state
  ,c360.postal AS postal
  ,c360.country AS country
  ,uit.order_id AS order_id
  ,uit.item_quantity AS quantity
  ,uit.product_id AS product_id
  ,uit.order_datetime AS timestamp
  ,CAST(uit.item_revenue / uit.item_quantity AS DOUBLE) AS price
  ,'USD' AS currency
  ,'physical_store' AS action_source
FROM Unified_Itemized_Transactions uit
LEFT JOIN Customer_360 c360 ON uit.amperity_id = c360.amperity_id
WHERE uit.order_datetime > (CURRENT_DATE - interval '7' day)

The query MUST contain the following fields: email or phone and timestamp. For Purchase events (or when event_name is not specified), the query must also contain currency and either quantity and price, or value. The fields external_id and order_id are recommended. When action_source is not specified the default value is “physical_store”.

You may include any of the following customer profile fields to help improve match rates in Meta Ads Manager: given_name, surname, birthdate, gender, city, state, postal, and country.

Tip

Extend the WHERE clause to filter query results by purchase channel, purchase brand, purchase quantity, and to remove items that were returned or canceled.

For example:

WHERE uit.order_datetime > (CURRENT_DATE - interval '7' day)
AND uit.purchase_channel = 'channel'
AND uit.purchase_brand = "ACME Essentials"
AND uit.item_quantity > 0
AND (c360.email IS NOT NULL OR c360.phone IS NOT NULL)
AND (
    (is_cancellation IS NULL)
    OR (NOT is_cancellation)
)
AND (
    (is_return IS NULL)
    OR (NOT is_return)
)

Multiple event types in the same query

Events parameters can vary depending on the type of event. For example, website purchases capture more events data than in-store purchases. To send consolidated events data to Meta Ads Manager create a database table to store the consolidated events and map the values in that table to the values required by Meta Ads Manager Conversions API parameters or to NULL values.

The following SQL shows how to send multiple event types stored in a table named Customer Events:

SELECT
  c360.amperity_id AS external_id
  ,c360.email AS email
  ,c360.phone AS phone
  ,events.order_id AS order_id
  ,events.event_datetime AS timestamp
  ,events.event_type AS event_name
  ,events.channel AS action_source
  ,events.revenue AS value
  ,'USD' AS currency
  ,events.user_agent AS client_user_agent
  ,events.event_uuid AS event_id
  ,events.page_url AS event_source_url
  ,events.client_ip AS client_ip_address
FROM Customer_Events events
LEFT JOIN Customer_360 c360 ON events.amperity_id = c360.amperity_id
WHERE events.event_datetime > (CURRENT_DATE - interval '7' day)

The table from which multiple events are sourced must have values that map to values required by the Conversions API:

1. Line 8 sets the value of action_source to the value of the channel field in the Customer Events table. In this example the values in the channel field are physical_store or website.

2. Lines 11-14 are events that only apply to website events in the Customer Events table. When action_source is physical_store the values for user_agent, event_uuid, page_url, and client_ip in the Customer Events table are NULL.

Review the Conversions API parameters section for detailed information about the columns returned by your query.

Conversions API parameters

The following table describes each of the parameters that are required by Meta Ads Manager for events. The final row lists the optional fields your brand may include to extend the customer profile information that is associated with events that are returned by the query and sent to Meta Ads Manager.

The fields are listed alphabetically, but may be returned by a query in any order.

Field name	Description
action_source	Optional Action sources group events into categories and enable ad measurmeent and custom audience creation abilities from within the Meta Ads Manager user interface. The default value for action_source is physical_store. Add action_source to your query and then set a value: ,'physical_store' AS action_source The value for action_source must be one of the following: app Use when the offline conversion was made from a mobile app. business_messaging Use when the offline conversion was made from ads associated with Facebook Messenger, Instagram, or WhatsApp. chat Use when the offline conversion was made over a messaging app, SMS, or online messaging feature. email Use when the offline conversion happened over email. other Use when the offline conversion occurred by some other workflow. phone_call Use when the offline conversion was made over a phone call. physical_store Default Use when the offline conversion was made in-person at a physical store location. Note The first time transaction events are sent to Meta Ads Manager, and when action_source is set to physical_store, up to 62 days of transactions data may be sent, after which Amperity should be configured to send updates that maintain a 7-day rolling window of transaction events. For example, the initial send: ,'physical_store' AS action_source ... WHERE uit.order_datetime > (CURRENT_DATE - interval '62' day) Update “62” to “7” before the next send to maintain a 7-day rolling window. system_generated Use when the offline conversion occurred automatically, such as from a subscription renewal or monthly auto-pay. website Use when the offline conversion was made on a website. When action_source is set to website the following fields are required: client_user_agent, event_id, and event_source_url. These fields must be in the results that are sent to Meta Ads Manager. Missing or empty values are filtered from the results. The value for client_user_agent must be the user agent for the browser corresponding to the event. The value for event_id is a unique string chosen by advertiser. The value for event_source_url should be browser URL at which the event occurred. client_ip_address is an optional field that, when present, is passed through to Meta. Meta recommends providing it to improve event matching quality. The value must be the IP address of the browser corresponding to the event. event_id, event_source_url, and client_user_agent are server event parameters for the Conversions API. The value for action_source is used by the Conversions API to categorize offline conversions within the Meta Ads Manager user interface and may not be customized. Use the action source that best associates how your brand wants to use offline conversions within Meta Ads Manager. When action_source is not specified the default value is “physical_store”.
currency	Required for Purchase events A value for currency is required by the Conversions API for Purchase events. When the event_name column is present in the dataset, currency is only required for rows where the event name is “Purchase” (or blank, which defaults to “Purchase”). When event_name is not present, all events are treated as Purchase and currency is required. Currency must be a valid ISO 4217 three-digit currency code, such as “USD” (United States dollar), “AUD” (Australian dollar), “CAD” (Canadian dollar), “EUR” (Euro), “JPY” (Japanese yen) or “MXN” (Mexican peso). Add currency to your query, and then set a value: ,'USD' AS currency Note When viewing parameters in the Meta Ads Manager user interface, price, quantity, and currency are combined to be shown as value, which represents the sum of price times quantity, shown in the currency used for the transaction.
delivery_category	Optional for “Purchase” events. Possible values: in_store, curbside, home_delivery, or shipping.
email or phone	Required You must send an email address or a phone number to Meta Ads Manager. You may configure the query to send both. Add at least one of email or phone to your query: ,c360.email AS email ,c360.phone AS phone Note Amperity performs the same actions for email addresses and phone numbers when sending to the Conversions API as when sending to the Marketing API.
event_name	Optional Identifies an offline event within Meta Ads Manager. Note The default value for event_name is “Purchase”. Blank or NULL values for event_name will default to “Purchase”. This value may be set to one of: “ViewContent”, “Search”, “AddToCart”, “AddToWishlist”, “InitiateCheckout”, “AddPaymentInfo”, “Purchase”, “Lead”, or “Other”. To send non-“Purchase” event types add the event_name field to the SQL query and set the value to the event type. For example: SELECT c360.amperity_id AS external_id ,c360.email AS email ,c360.phone AS phone ,leads.lead_datetime AS timestamp ,'Lead' AS event_name ,'website' AS action_source FROM Customer_Leads leads LEFT JOIN Customer_360 c360 ON leads.amperity_id = c360.amperity_id WHERE leads.lead_datetime > (CURRENT_DATE - interval '7' day)
external_id	Recommended The amperity_id field MUST be renamed to external_id. Add external_id to your query: ,c360.amperity_id AS external_id Note Amperity performs the same actions for the external ID when sending to the Conversions API as when sending to the Marketing API.
order_id	Optional The order ID that is associated with the offline event. When transactions data is available Use the Order ID field that is available from the Unified Itemized Transactions or Unified Transactions tables: ,uit.order_id AS order_id or: ,ut.order_id AS order_id Important The number of rows that results from the query may not be the same as the number of events that are uploaded to Meta Ads Manager. This depends on the table from which the order ID is returned. Transactions from the Unified Itemized Transactions table group items by order ID to ensure that individual events are combined to describe a complete transaction. Meta Ads Manager processes each item as a unique conversion. For example, an order ID with three individual items is attributed by Meta Ads Manager as three conversions. Transactions from the Unified Transactions table are grouped by order ID. Each unique combination of order_id and event_name is sent to Meta Ads Manager as a single conversion. If event_name column is not included all rows grouped by order ID are assigned the “Purchase” event type and each order_id produces one conversion.
phone	See email.
price	Required for Purchase events The price that is associated with the offline event. When the event_name column is present in the dataset, price is only required for “Purchase” events. Non-“Purchase” events (such as “Lead”) do not require price. Note When viewing parameters in the Meta Ads Manager user interface, price, quantity, and currency are combined to be shown as value, which represents the sum of price times quantity, shown in the currency used for the transaction. When transactions data is available Calculate price by dividing item revenue by item quantity. These fields are available from the Unified Itemized Transactions or Unified Transactions tables: ,CAST( uit.item_revenue / uit.item_quantity AS DOUBLE ) AS price
product_id	Optional A unique product identifier that can be associated with the offline event. When transactions data is available Use the Product ID field that is available from the Unified Itemized Transactions or Unified Transactions tables: ,uit.product_id AS product_id
quantity or value	Required for Purchase events A field that describes a quantity or a value amount associated with the offline event. When the event_name column is present in the dataset, quantity (or value) is only required for “Purchase” events. Non-“Purchase” events (such as “Lead”) do not require quantity or value. Note When viewing parameters in the Meta Ads Manager user interface, price, quantity (or value), and currency are combined to be shown as value, which represents the sum of price times quantity, shown in the currency used for the transaction. When transactions data is available Use the Item Quantity field from the Unified Itemized Transactions or Unified Transactions tables to define quantity: ,uit.item_quantity AS quantity
timestamp	Required A Unix timestamp in seconds that indicates when the offline event occurred. Note When viewing parameters in the Meta Ads Manager user interface, timestamp is shown as event_time. When transactions data is available Use the Order Datetime field from the Unified Itemized Transactions or Unified Transactions tables to define timestamp: ,uit.order_datetime AS timestamp Use a WHERE clause to limit the number of days to a maximum of seven: WHERE uit.order_datetime > ( CURRENT_DATE - interval '7' day )
value	The total value for a “Purchase” event. Required when price and quantity are not provided. Note value is not required for non-“Purchase” events, such as “Lead”.
Optional profile attributes	You may include any of the profile attributes that are supported by the Marketing API, including Gender, Birthdate, First Name, Last Name, City, State, Zip Code, and Country Code.