Send data to Meta Ads Manager¶
Meta Ads Manager is a unified ad creation tool that your brand can use to create and publish ads to Facebook, Messenger, Instagram and the Meta Audience Network.
Your brand can send custom audiences and offline events to Meta Ads Manager:
|
Custom audiences Send custom audiences to Meta Ads Manager to help find people who already know about or have engaged with your brand. Use custom audiences for re-marketing, finding potential repeat customers, and finding lookalike audiences that can be activated from Facebook, Facebook Messenger, Instagram, and WhatsApp. The Facebook Marketing API, specifically the Replace Users endpoint, is used to send custom audiences. This endpoint removes existing customers from an audience without resetting your ad set’s learning phase when an audience is part of active ad sets, and then replaces those users with the list of customers that was sent to Meta Ads Manager from Amperity. Note Changes to audiences are not immediately available in Meta Ads Manager. Allow for up to 24 hours after the point at which Amperity has finished sending audience updates for them to be available. |
|
|
Offline events 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, 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 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. |
This topic describes the steps that are required to send customer data to Meta Ads Manager from Amperity:
How this destination works¶
You can build custom audiences in Meta Ads Manager. Send customer information, such as email addresses, phone numbers, names, birthdates, gender, city, state, postal code, and mobile advertising IDs, from Amperity to find customer matches on Meta Ads Manager.
Use audiences in Meta Ads Manager to advertise to customers on Facebook, Instagram, and Messenger, and to use Meta Audience Network to extend your advertising beyond Facebook to reach new audiences on apps and mobile devices, such as WhatsApp.
A Meta Ads Manager destination works like this:
|
Use a query or segment to build a custom audience. |
|
Configure the Meta Ads Manager destination and data template. |
|
Send a test set of first-party data from Amperity, and then from within Meta Ads Manager verify that this data is available from Meta Ads Manager. Important The custom audience terms of service must be signed by each business user that is associated with your Facebook Ads account. If the terms of service are not signed, a permissions error will prevent Amperity from sending data to Meta Ads Manager. Meta Ads Manager uses OAuth to grant access to Amperity. You may need to reauthorize OAuth if the token expires or is removed. |
|
Build ads for that audience in Meta Ads Manager. |
About Meta Ads Manager¶
Audiences sent to Meta Ads Manager have access to Facebook, Messenger, Instagram and the Meta Audience Network.
 |
Use Meta Ads Manager to configure a variety of ad placements across Facebook . |
 |
Use Meta Ads Manager to configure objectives that place ads on Instagram . |
 |
Use Meta Ads Manager to configure objectives that place ads on Messenger . |
 |
Use Audience Manager to reach users who are not on Facebook or Instagram, but are on mobile apps that are within the audience network. For example, creating ads that open conversation threads in WhatsApp . |
Get details¶
Meta Ads Manager requires the following configuration details:
|
The account ID. How do I find Facebook Ads account information? You can find all of this information and perform all of the required steps from within Facebook Business Manager. Click Business Settings, then Ad Accounts, and then the Facebook Ads account name. The account ID is visible under Details. Note You may use the same credentials to send offline events. |
|
|
The custom audience name and customer file source settings. The custom audience name is visible from Meta Ads Manager. This name should be clear and understandable to users of Meta Ads Manager. The custom audience name will be created if it does not exist. The customer file source specifies if the data was provided by users, provided by partners, or provided from both users and partners. Note The customer file source maps directly to the customer_file_source parameter in the Facebook Marketing API. This value describes how the customer information in the custom audience was originally collected:
|
|
|
Acccept the custom audience terms of service. Important Terms of service must be signed by each business user that is associated with your Facebook Ads account. |
|
|
Authorize Amperity to send data to the customer’s Facebook Ads account. This requires activation in the Amperity Meta Ads Manager account and approval in the customer’s Meta Ads Manager account. Note You may need to reauthorize Amperity at various intervals. |
|
|
Meta Ads Manager offline events only 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 Manager to support sending send offline events from Amperity. A query that defines the set of offline events to be sent to Meta Ads Manager. |
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 will prevent 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.
Configure OAuth¶
OAuth is an open standard for access delegation, commonly used to grant websites or applications access to information on other websites.
Use OAuth to configure Amperity to send customer data to Meta Ads Manager.
To configure OAuth
|
|
Open the Destinations tab and click Add Destination. The Add Destination dialog box opens. Select Meta Ads Manager from the Plugin drop-down, and then from the Credential drop-down, select Create a new credential. This opens the Create New Credential dialog box. |
|
|
In the Create New Credential dialog box, click “Generate authorization URL”. Copy the URL, and then provide the URL to a user who has credentials that allow access to Meta Ads Manager. The user must log in and complete the steps required by the OAuth process for Meta Ads Manager. After this is completed, you will be redirected to the Credentials page in Amperity. Verify the credential is on the page, and then return to the Destinations tab. |
|
|
Open the Destinations tab and click Add Destination. The Add Destination dialog box opens. Select Meta Ads Manager from the Plugin drop-down, and then from the Credential drop-down, select the credential that is authorized to access Meta Ads Manager. Note The value for the Refresh Token setting is updated automatically after you select the credential. |
Custom audiences¶
Send custom audiences to help find people who already know about or have engaged with your brand. Use custom audiences for re-marketing, finding potential repeat customers, and finding lookalike audiences that can be activated from Facebook, Facebook Messenger, Instagram, and WhatsApp.
The Facebook Marketing API, specifically the Replace Users endpoint, is used to send custom audiences.
This endpoint removes existing customers from an audience without resetting your ad set’s learning phase when an audience is part of active ad sets, and then replaces those users with the list of customers that was sent to Meta Ads Manager from Amperity.
Add destination¶
Configure Amperity to send customer data directly to Meta Ads Manager.
Warning
Amperity must be authorized to send data to your Meta Ads Manager account prior to configuring the destination.
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 a name for the destination and provide a description. For example: “Meta Ads Manager” and “This sends customer data to Meta Ads Manager”. From the Plugin drop-down, start typing “face” to filter the list, and then select 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 drop-down. – or – Select Create a new credential from the Credential drop-down. This opens the Credential dialog box. 
Enter the name for the credential, and then add a description. Steps to configure OAuth
|
||||||||
|
|
Each destination has settings that define how Amperity will deliver data to Meta Ads Manager. These settings are listed under the Settings section of the Destination dialog box. 
The following settings are specific to Meta Ads Manager:
|
||||||||
|
|
Business users are assigned to the Amp360 User and/or AmpIQ User policies. (Amp360 User allows access to queries and orchestrations and AmpIQ User allows access to segments and campaigns.) A business user cannot select a destination that is not visible to them. Business users – including users assigned to the DataGrid Operator policy – may have restricted access to PII. What is restricted access to PII? 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. You can make this destination visible to orchestrations and allow users with restricted access to PII to use this destination by enabling one (or both) of the following options: 
Note To allow business users to use this destination with campaigns, you must enable the Available to campaigns option within the data template. This allows users to send campaign results from Amperity to Meta Ads Manager. The other two settings may be configured within the data template instead of the destination. |
||||||||
|
Review all settings, and then click Save. 
Important You must configure a data template for this destination before you can send data to Meta Ads Manager. |
Add data template¶
A data template defines how columns in Amperity data structures are sent to downstream workflows. A data template is part of the configuration for sending query and segment results from Amperity to an external location.
About paid media campaigns
Amperity provides the right set of data to support your brand’s paid media advertising with Meta Ads Manager.
Merged Customers vs. Unified Paid Media
The Merged Customers table contains each of your customers’ best profiles.
The Unified Paid Media table contains all your customer’s known profile data.
Your brand will require additional data templates to use the Unified Paid Media table alongside the Merged Customers table to support paid media campaigns.
Enable dedicated data templates for each table.
Use a consistent naming pattern to label data templates that use data from the Merged Customers table. For example: “Best profile”.
Use a consistent naming pattern to label data templates that use data from the Unified Paid Media table. For example: “Full profile”.
After data templates are configured for both tables, use the default attributes component on the Campaigns page to configure which attributes will be associated with the destination, including the table from which those attributes will be pulled.
The selected table will affect your brand’s downstream match rates and overall customer matches within your paid media campaigns. The decision behind which table to use depends on your brand’s downstream use case and the type and amount of customer profile data your brand wants to use to match customers.
You brand should expect to see higher match rates when sending audiences from the Merged Customers table, but a higher number of matched customer profiles when sending audiences from the Unified Paid Media table. Use A/B testing to compare the results from each table, after which your brand can use the audience that works best for your campaigns.
To add a data template
|
|
From the Destinations tab, open the menu for a destination that is configured for Meta Ads Manager, and then select Add data template. This opens the Add Data Template dialog box. 
Enter the name of the data template and a description. For example: “Meta Ads Manager” and “Send customer data to Meta Ads Manager.”. |
|
|
Verify business user access to queries and orchestrations and access to segments and campaigns. A business user may also have restricted access to PII, which prevents them from viewing and sending customer profile data. 
If business user access was not configured as part of the destination, you may configure access from the data template. Important To allow business users to use this destination with campaigns, you must enable the Available to campaigns option. This allows users to send campaign results from Amperity to Meta Ads Manager. If you enable this option, the data extension settings require using campaign name and group name template variables to associate the name of the data extension to your campaign. |
|
|
Verify all configuration settings. 
Note When the account ID, custom audience, and the customer file source settings were are not configured as part of the destination, you must configure them as part of the data template before making this destination available to campaigns. |
|
|
Review all settings, and then click Save.
After you have saved the data template, and depending on how you configured it, business users can send query results and/or send campaigns to Meta Ads Manager. |
Offline events¶
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, 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 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 destination¶
Configure Amperity to send customer data directly to Meta Ads Manager.
Warning
Amperity must be authorized to send data to your Meta Ads Manager account prior to configuring the destination.
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 offline events” and “Send offline 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 drop-down. – or – Select Create a new credential from the Credential drop-down. This opens the Credential dialog box. Meta Ads Manager 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 Manager. |
|
|
Each destination has settings that define how Amperity will deliver data to Meta Ads Manager. 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 Manager to support sending send offline events from Amperity. |
|
|
Business users are assigned to the Amp360 User and/or AmpIQ User policies. (Amp360 User allows access to queries and orchestrations and AmpIQ User allows access to segments and campaigns.) A business user cannot select a destination that is not visible to them. Business users – including users assigned to the DataGrid Operator policy – may have restricted access to PII. What is restricted access to PII? 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. You can make this destination visible to orchestrations and allow users with restricted access to PII to use this destination by enabling one (or both) of the following options:
|
|
|
Review all settings, and then click Save.
Important You must configure a data template for this destination before you can send data to Meta Ads Manager. |
Add data template¶
Offline events must be sent using a query and orchestration. The data template associated with offline events should not be made available to the Campaigns editor.
To add a data template
|
|
From the Destinations tab, open the menu for a destination that is configured for Meta Ads Manager, and then select Add data template. This opens the Add Data Template dialog box. 
Enter the name of the data template and a description. For example: “Meta Ads Manager offline events” and “Send offline events to Meta Ads Manager.”. |
|
|
Verify business user access to queries and orchestrations and access to segments and campaigns. A business user may also have restricted access to PII, which prevents them from viewing and sending customer profile data. 
If business user access was not configured as part of the destination, you may configure access from the data template. |
|
|
Verify all configuration settings. 
Note If the dataset ID is not specified in the data template it must be specified at orchestration. |
|
|
Review all settings, and then click Save.
After you have saved the data template, and depending on how you configured it, business users can send query results and/or send campaigns to Meta Ads Manager. |
Workflow actions¶
A workflow will occasionally show an error that describes what prevented a workflow from completing successfully. These first appear as alerts in the notifications pane. The alert describes the error, and then links to the Workflows tab.
Open the Workflows page to review a list of workflow actions, choose an action to resolve the workflow error, and then follow the steps that are shown.
|
|
You may receive a notifications error for a configured Meta Ads Manager destination. This appears as an alert in the notifications pane on the Destinations tab. 
If you receive a notification error, review the details, and then click the View Workflow link to open this notification error in the Workflows page. |
|
|
On the Workflows page, review the individual steps to determine which step(s) have errors that require your attention, and then click Show Resolutions to review the list of workflow actions that were generated for this error. 
|
|
|
A list of individual workflow actions are shown. Review the list to identify which action you should take. 
Some workflow actions are common across workflows and will often be available, such as retrying a specific task within a workflow or restarting a workflow. These types of actions can often resolve an error. In certain cases, actions are specific and are shown when certain conditions exist in your tenant. These types of actions typically must be resolved and may require steps that must be done upstream or downstream from your Amperity workflow. Amperity provides a series of workflow actions that can help resolve specific issues that may arise with Meta Ads Manager, including: |
|
|
Select a workflow action from the list of actions, and then review the steps for resolving that error. 
After you have completed the steps in the workflow action, click Continue to rerun the workflow. |
Cannot create ads¶
The advertising account that is used by this workflow must have permission to create ads.
To resolve this error, update the user permissions in Meta Ads Manager to ensure that the advertising account can create ads.
Log into Meta Ads Manager and verify the user permissions for the account.
Update the user permissions to ensure that the Create and edit ads permission is assigned to the advertising account used by this workflow.
Return to the workflow action, and then click Resolve to retry this workflow.
EXTERN_ID is missing¶
An EXTERN_ID is a unique ID used within Meta Ads Manager, such as a loyalty ID, a customer ID, an external ID, or the Amperity ID.
Amperity will be unable to send orchestrations or campaigns when EXTERN_ID is not included within an audience that is sent to Meta Ads Manager.
For campaigns
To resolve this error, verify that EXTERN_ID is included in the list of attributes that are being sent to Meta Ads Manager.
Open the Campaigns page, and then open the segment used with this workflow.
Verify that EXTERN_ID is included in the list of attributes for each treatment group that sends audiences to Meta Ads Manager. Update the list of attributes for each treatment group if required.
Return to the workflow action, and then click Resolve to retry this workflow.
For orchestrations
To resolve this error, verify that EXTERN_ID is included in the query results.
Open the Queries page, and then open the query used with this workflow.
Verify that EXTERN_ID is included in the query results. Update the query if required.
Return to the workflow action, and then click Resolve to retry this workflow.
Invalid credentials¶
The credentials that are defined in Amperity are invalid.
To resolve this error, verify that the credentials required by this workflow are valid.
Open the Credentials page.
Review the details for the credentials used with this workflow. Update the credentials for Meta Ads Manager if required.
Return to the workflow action, and then click Resolve to retry this workflow.
Maximum custom audiences exceeded¶
Meta Ads Manager supports having up to 500 custom audiences in your account at any given time. Amperity will be unable to create custom audiences when this limit is exceeded.
To resolve this error, verify the number of custom-audiences associated with your Meta Ads Manager account.
Log into Meta Ads Manager and verify the number of custom audiences that are associated with your Meta Ads Manager account.
Remove custom audiences that are not in active use.
Return to the workflow action, and then click Resolve to retry this workflow.
Must agree to Facebook terms¶
The custom audience terms of service must be signed by each business user that is associated with your Facebook Ads account. If the terms of service are not signed, a permissions error will prevent Amperity from sending data to Facebook Ads.
When the business user has not agreed to Facebook terms, an error similar to the following is shown:
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=1234567890123456.
To resolve this error, log into Meta Ads Manager as the business user associated with this workflow and agree to the terms of service.
Follow the instructions in the error message, and then open the provided link in a new tab.
Log in as the business user associated with this workflow, and then agree to the Facebook terms of service.
Return to the workflow action, and then click Resolve to retry this workflow.
Must belong to business account¶
The advertising account used to enable workflows to be sent to Meta Ads Manager from Amperity requires the advertising account to also belong to a business account. When an advertising account does not also belong to a business account, Amperity workflows will be unable to create or edit a custom audience.
To resolve this error, verify that the advertising account also belongs to a business account.
Log into Meta Ads Manager and verify the configuration for the advertising account to ensure that it also belongs to a business account.
Return to the workflow action, and then click Resolve to retry this workflow.
Security challenge¶
Sometimes Meta Ads Manager will issue a security challenge to the advertising account and/or business account associated with this workflow.
To resolve this error, complete the steps that are required to resolve the security challenge.
Log into Meta Ads Manager using the link provided in the workflow action, and then follow the instructions to resolve the security challenge.
Return to the workflow action, and then click Resolve to retry this workflow.
Facebook Marketing API keys¶
The following Amperity columns should be mapped to the corresponding Facebook Marketing API keys when they are present in query data:
Amperity Column |
Facebook API Key |
Description |
|---|---|---|
Amperity ID |
EXTERN_ID |
This value is a unique ID used by the advertiser, such as a loyalty ID, a customer ID, an external cookie ID, or the Amperity ID. For this key, the connector trims leading and trailing whitespace. Tip A query can alias the Amperity ID directly in a query: SELECT amperity_id AS EXTERN_ID from custom_table. This approach can be helpful for queries that are dedicated to returning data to be sent only to Facebook Ads. |
Email Addresses |
For this key, the connector:
|
|
Phone Numbers |
PHONE |
Converts each phone number to E.164 format which represents a phone number as a number up to fifteen digits in length (without spaces) that starts with a + symbol. For example: +12061234567. For this key, the connector:
|
Gender |
GEN |
For this key, the connector:
|
Birth Date |
BIRTH |
The birth date in Amperity date format. For this key, the connector splits this value into three fields: birth year (DOBY), birth month (DOBM), and birth day (DOBD). |
Birth Year |
DOBY |
Warning Do not pass this column. For this key, the connector will use birthdate to split out the value for DOBY with a format of YYYY and a range from 1900 to the current year. |
Birth Month |
DOBM |
Warning Do not pass this column. For this key, the connector will use birthdate to split out the value for DOBM with a format of 01 to 12. |
Birth Day |
DOBD |
Warning Do not pass this column. For this key, the connector will use birthdate to split out the value for DOBD with a format of 01 to 31. |
Last Name |
LN |
This key supports special characters and non-Roman alphabet characters. For this key, the connector:
|
First Name |
FN |
This key supports special characters and non-Roman alphabet characters. For this key, the connector:
|
First Initial |
FI |
Warning Do not pass this column. The connector will use the first character of the normalized first name. |
US States |
ST |
A two-character ANSI abbreviation code for US states. For this key, the connector:
|
City |
CT |
For this key, the connector:
|
Zip Code |
ZIP |
Use only the first five digits for the United States. Use postcodes (area, district, sector) format for United Kingdom. For this key, the connector:
|
Country Code |
COUNTRY |
A two-letter country code in ISO 3166-1 alpha-2 format. For this key, the connector:
|
Mobile Advertiser ID |
MADID |
For this key, the connector:
|
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. |