Send offline events to Meta Ads Manager¶
Send offline events to Meta Ads Manager to help your brand track offline conversions that result from your marketing campaigns. Offline 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 offline events .
Important
The first time transaction events are sent to Meta Ads Manager, seven days of data is sent, after which Amperity should be configured to send daily updates, which will maintain a 7-day rolling window of transaction events.
Note
Offline events are not immediately available in Meta Ads Manager. Allow for up to 24 hours after the point at which Amperity has finished sending offline events for them to be available.
Offline events that are sent to Meta Ads Manager can be accessed from Meta Events Manager .
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 offline events that your brand wants to use within Meta Ads Manager.
A query that returns a collection offline 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: external_id, order_id, quantity, email (OR phone), timestamp, price, and currency. 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 and/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)
)
Review the Conversions API parameters section for detailed information about the columns that must be (or may be) returned by your query.
Add orchestration¶
An orchestration defines the relationship between query results and a destination, including the location to which those query results will be sent and the frequency at which the orchestration will be run.
Note
Meta Ads Manager must be enabled before you can configure an orchestration to send query results.
To add an orchestration
From the Destinations tab, click Add Orchestration. This opens the Add Orchestration dialog box.
From the Object Type drop-down, select Query.
From the Object drop-down, select the query for which results will be sent to Meta Ads Manager.
From the Destination drop-down, select a destination that is configured for sending data to Meta Ads Manager.
From the Data Template drop-down, select a data template.
Verify all settings.
Set the workflow to Manual. (You can change this to automatic later, after verifying the end-to-end workflow.)
Click Save.
Run orchestration¶
Run the orchestration manually to validate that it works.
Important
Amperity requires access to Meta Ads Manager. This access may expire or be removed periodically, depending on how OAuth is managed at Meta Ads Manager. If Amperity is unable to send data to Meta Ads Manager ask your DataGrid Operator to reauthorize access to Meta Ads Manager.
To add an orchestration
From the Destinations tab, click Add Orchestration. This opens the Add Orchestration dialog box.
From the Object Type drop-down, select Query.
From the Object drop-down, select the query for which results will be sent to Meta Ads Manager.
From the Destination drop-down, select a destination that is configured for sending data to Meta Ads Manager.
From the Data Template drop-down, select a data template.
Verify all settings.
Set the workflow to Manual. (You can change this to automatic later, after verifying the end-to-end workflow.)
Click Save.
Warning
If the Terms of Service (ToS) for Custom Audiences have not been accepted you will get a permissions error with a link to the ToS. Someone with access to the Facebook account will need to accept the ToS before Custom Audiences will be sent.
Conversions API parameters¶
The following table describes each of the parameters that are required by Meta Ads Manager for offline events. The final row lists the optional fields your brand may include to extend the customer profile information that is associated with offline 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 offline 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:
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 A value for currency is required by the Conversions API for offline events. 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. |
email and/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”. This value may be set to one of: “ViewContent”, “Search”, “AddToCart”, “AddToWishlist”, “InitiateCheckout”, “AddPaymentInfo”, “Purchase”, “Lead”, or “Other”. |
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
Important The number of rows that results from the query will not be the same as the number of events that are uploaded to Meta Ads Manager. This is because transactions within the query are grouped by Order ID as the data is sent to Meta Ads Manager. Grouping by Order ID ensures that individual events are combined to describe a complete transaction. Amperity performs the GROUP BY action automatically if a GROUP BY clause is not set to “order_id”. |
phone |
See email. |
price |
Required The price that is associated with the offline event. 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 A field that describes a quantity or a value amount associated with the offline event. 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 |
See quantity. |
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. |