Send offline events to Meta Ads Manager¶

Send offline events to Meta Ads Offline Events 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 Offline Events using the Conversions API for offline events .

Important

The first time transaction events are sent to Meta Ads Offline Events, 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

Offline events are not immediately available in Meta Ads Offline Events. 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 Offline Events can be accessed from Meta Events Manager .

Get details¶

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

Credential settings

Refresh token

Required

A refresh token is generated by the OAuth process and authorizes Amperity to send data to Meta Ads Offline Events. The value for the refresh token is updated automatically.

Meta Ads Manager settings

Datasets allow you to 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 must be configured in Meta Ads Offline Events to support sending send offline events from Amperity.

Configure credentials¶

Configure credentials for Meta Ads Offline Events before adding a destination.

An individual with access to Meta Ads Offline Events should use SnapPass to securely share “refresh token” details with the individual who will configure Amperity.

To configure credentials for Meta Ads Manager offline 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 Offline Events.

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 are determined by the 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 Offline Events. The value for the refresh token is updated automatically.

Reauthorize Amperity¶

You may need to reauthorize access to Meta Ads Offline Events. 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 Offline Events. To reauthorize access to Meta Ads Offline Events, 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 Offline Events account. If the terms of service are not signed, a permissions error will prevent Amperity from sending data to Meta Ads Offline Events.

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 Offline Events account.

Add destination¶

Use a sandbox to configure a destination for Meta Ads Offline Events. Before promoting your changes, send a test audience, and then verify the the results in Meta Ads Offline Events. After the end-to-end workflow has been verified, push the destination from the sandbox to production.

To add a destination

	Open the Destinations tab to configure a destination for Meta Ads Offline Events. Click the Add Destination button to open the Destination dialog box. Enter the name of the destination and a description. For example: “Meta Ads Offline Events offline events” and “Send offline events to Meta Ads Offline Events.”.
	Credentials allow Amperity to connect to Meta Ads Offline Events. 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 drop-down. – or – Select Create a new credential from the Credential drop-down. This opens the Credential dialog box. Meta Ads Offline Events requires using OAuth to authorize Amperity to send offline events to your Meta Ads Manager account. Note You may use the same credentials to send both custom audiences and offline events to Meta Ads Offline Events.
	Each destination has settings that define how Amperity will deliver data to Meta Ads Offline Events. These settings are listed under the Settings section of the Destination dialog box. Datasets allow you to 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 must be configured in Meta Ads Offline Events to support sending send offline events from Amperity.
	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 users with limited access to PII access to this destination. Restricted PII access is enabled when the Restrict PII access policy option that prevents users who are assigned to that option from viewing data that is marked as PII anywhere in Amperity and from sending that data to any downstream workflow.
	Configure the following settings, and then click “Save”. Dataset ID Datasets allow you to 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 must be configured in Meta Ads Offline Events to support sending send offline events from Amperity.
	After this destination is configured, users may configure Amperity to use orchestrations to send query results Meta Ads Offline Events.

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 Offline Events.

A query that returns a collection offline events for use in Meta Ads Offline Events 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 Offline Events: 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.

Conversions API parameters¶

The following table describes each of the parameters that are required by Meta Ads Offline Events 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 Offline Events.

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 Offline Events 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 Offline Events, 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 Offline Events; 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. event_id and event_source_url 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 Offline Events 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 Offline Events. 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 Offline Events 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 Offline Events; 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 Offline Events. 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 Offline Events. This is because transactions within the query are grouped by Order ID as the data is sent to Meta Ads Offline Events. 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 Offline Events 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 Offline Events 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 Offline Events 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.