Supermetrics Support Forum

How to Query for Facebook Ads Custom Conversions

Facebook Ads custom conversions are a powerful tool to extend the usability of pixel events past the standard offerings Facebook provides. But because they are customized actions, they are not handled the exact same way in the API and require some special setup with the Supermetrics data connectors to work properly. This guide will walk you through the basic fields needed to get the custom conversions, the core query required to fetch the data, and some additional tips and tricks to get around the limitations these conversions have in reporting.

Quick links to each section:

Basic Information

Facebook custom conversions are a special type of Facebook Pixel event you will add to your external websites. These are similar to the standard pixel events, but you get to define some custom parameters for what counts as a conversion. Note these are different from "Offsite Conversions" which are handled differently. For more information about custom conversions and how they work, see this Facebook Business help article.

The Marketing API treats these as actions. In fact, all conversions, standard, pixel and custom, are a type of action. Because the standard pixel events as a known configuration, the API give specific fields for these that we can use in the Supermetrics integrations. However, because the custom conversions can be configured differently and have their own custom event names, we don't have specific fields just for those. Instead, you have to pull them as a type of action to get access to them.

Fields and Core Basic Query

As we now know that conversions (custom or pixel or standard) are really actions, we use the available actions-related fields to get data on them. Here are the fields that are currently available in Supermetrics:

  • Actions - A metric that counts the number of times users completed that specific action. It is essentially the conversion count.
  • Action type - A dimension that reports the display names of the different conversions. It will show the standard conversions, the pixel conversions, and custom conversions. Custom conversions will be reported as their display name in the Events Manager.
  • Action type (with custom conv. ID) - A dimension that reports the names of the different conversions, including the custom conversion ID. As with "Action Type" it will show all conversion types. Custom conversions will look like this: offsite_conversion.custom.<customID#>
  • Action device - A dimension that reports what device type the action (aka conversion) took place on. Supported values are preset by Facebook.
  • Action target ID - A dimension that reports the ID of the destination users will go to after clicking your ad. This is not the conversion ID.

Now that we have the field definitions, the most basic query required to even see custom conversions is:
Metrics: Actions
Dimensions: Action type

Here's an example output using this query:

Output of a query looking at actions in an Ad account, with blue arrow pointing to custom conversion

Here's what is looks like with the "Action type (with custom conv. ID)" field instead:

Example query with the conversion ID version of "Action type", with blue box highlighting the custom conversion

Note that this shows all conversion types from this period, including the standard and pixel conversions. So if you are interested in just the custom conversion, you can use filtering on the name (or the conversion ID, if using "Action type (with custom conv. ID)").

To crosscheck the values - you can setup your Ads Manager table to show the custom conversion total - the value it shows should match the "Actions" field for the same time period as the query. For the above example query, Facebook shows the same 1 action/conversion for that conversion type.

Blue box around conversion count for the "Sidebar query success" custom conversion.

Limitations and Common 'Gotchas'

Incompatible Metrics

We can now get the custom conversions via the "Action Type" dimension, but there's a very big problem with this! Those action-based dimensions are only compatible with the "Actions" metric.

Example error text for IllegalDimensionMetricCombination when trying to run "Action Type" and "Impressions" together.

This is pretty horrible if you needed to get the custom conversion counts along with other metrics like "Impressions" and "Amount spent" for the campaigns.

Fear not - there's workarounds to this. Essentially, you need two queries with a common field between them to join the data into one complete table - like the "Campaign ID" or the "Ad ID". See the Example Query Setup with Google Sheets Add-on/Excel and Example Query Setup with Data Studio sections for specific walkthroughs on addressing this in those products.

Action Count Doesn't Match Activity

A common error is that users try to check this value for the "Conversions received" to the "Actions" value.

Blue arrow points to conversions received value for the custom conversion

These are not equal! "Conversions received" is the raw number of times that pixel code fired on your site - it could be for users that never have seen your Facebook Ad. So you must compare it to the Conversion count in the Ad Manager table as this has the proper attribution calculation done on it, like shown at the bottom of the last section about Fields and Core Basic Query. If you are checking the actions to the conversion count but it's still wrong, see the Troubleshooting section near the bottom for more things to check.

"Website Custom Conversions" Returns No Data

This field is not what you think it is, despite the name. This is a separate standard pixel event that has nothing to do with actual custom conversions. You need to use the "Action type" method to get custom conversion data. 

Example Query Setup with Google Sheets Add-on/Excel

This example will walk through how to setup a custom conversion query in the Google Sheets Add-on (Excel is functionally similar and can use basically the same steps). It will also show the workaround for the common problem of incompatible metrics with "Action type".

  1. In the Event Manager in Facebook, collect the names and/or IDs of the custom conversions you wish to gather data on.

    In the Custom Conversion section of the Event manager, you can get the display name and the conversion ID

  2. In Google Sheets, create a fresh tab to work with.
  3. Click Add-ons->Supermetrics->Launch sidebar to start the query creation process.
  4. Set up the following query for Facebook Ads and run it in A1:
    • Metrics: Actions
    • Dimensions: Campaign ID, Action type (with custom conv. ID)
    • Filter: Action type (with custom conv. ID) CONTAINS yourconversionID
  5. You should get just the custom conversion and the conversion count (aka actions). If the custom conversion is run in multiple campaigns, there may be multiple rows.

    Example base query to get the custom conversion ID and action count

  6. Click Exit to stop editing that query.
  7. In the same tab, create a new query in E1 that will be the other metrics to be included in your data that you cannot fetch with "Action Type" present.
    • Metrics: Impressions, Reach, Amount, Spent, other standard conversions, etc.
    • Dimensions: Campaign ID
    • Filter: Optionally, filter for the Campaign ID that applies to your custom conversion
    • Example of the second query configuration to gather the rest of the data not compatible with "Action Type"

  8. You should now have two tables of data in the tab, one for the custom conversion and one for the rest of the campaign data.
  9. Now to combine them! You will need to use a formula that looks up the data from the custom conversion query and adds it to the end of the other query with the rest of the metrics to make a complete data set.

    This is one example way to do this - you could do it other ways:

    =vlookup(<CampaignID>,<cell range of custom conversion>,<index of action value from campaignID>,)

    Example of the formula at work

Example Query Setup with Data Studio

This example will walk through how to setup a custom conversion query in the Supermetrics for Data Studio product. It will also show the workaround for the common problem of incompatible metrics with "Action type" using the new Data Blending feature.

  1. In the Event Manager in Facebook, collect the names and/or IDs of the custom conversions you wish to gather data on.

    In the Custom Conversion section of the Event manager, you can get the display name and the conversion ID

  2. Set up the Facebook Ads connector for Data Studio for the ad account you wish to fetch custom conversion data from.
  3. Set up this basic query as a table to see the custom conversion and action count:
    • Metrics: Actions
    • Dimensions: Campaign ID, Action type (with custom conv. ID)
    • Filter: Action type (with custom conv. ID) CONTAINS yourconversionID
    • Example filter setup in Data Studio to show only the custom conversion based in ID

  4. WARNING - This requires filtering on the conversion ID to work, but there's some known discrepancy issues with using filters in Data Studio. Please be aware that this can affect the accuracy of the values.

  5. You should see results like this - if the custom conversion is used in multiple campaigns, you may see multiple rows:

    Example query configuration for data studio to get "Action Type" for custom conversions

  6. Now to combine this information with another query with the other metrics that are normally not compatible, we will make another table to use as part of a data blend. If you are unfamiliar with this new feature in Data Studio, please see this for more information: Using DS Data Blending Feature With Supermetrics
  7. Create another table with the following configuration:
    • Metrics: Impressions, Reach, Amount, Spent, other standard conversions, etc.
    • Dimensions: Campaign ID
    • Filter: Optionally, filter for the Campaign ID that applies to your custom conversion
  8. Select the initial table with the "Action Type" and then shift-click the second table with the rest of the data. Right-click and select Blend data from the drop-down menu.
  9. This will create a third table that is a combination of the other two. But it's not ready quite yet and you will probably see an error.
  10. Click the edit icon for the third table's data source to edit the blend.

    Blue arrow points to pencil icon to edit the blended data

  11. Modify the blend so it looks basically like this:

    Example of properly configured data blend

    • Only the campaign ID should be the key. Any other fields you want to use have to be listed in the below sections and not the key field.
    • Make sure the date ranges for both data sources are the same.
    • Make sure any filters you want to use are applied here.
  12. Click SAVE.
  13. In the table you can remove the field for the "Action Type (with custom conv. ID) and have a beautiful, complete data set!

    Example of complete data set using the data blend feature

  14. The original tables can be used to cross check the accuracy of the data, but can be deleted after the blend is made. They are not needed in the final report.

Troubleshooting

Discrepancies

If you see discrepancies in the "Actions" field versus the conversion count in the Ads Manager, check to see if one of these issues is a factor:

IllegalDimensionMetricCombinationException

You cannot use the "Action"-related dimensions with any metric except "Actions" in the same query. You will need to split the query up into two parts and recombine it with spreadsheet formulas or data blending (if using Data Studio). See the Example Query Setup with Google Sheets Add-on/Excel and Example Query Setup with Data Studio sections for examples of how to set this up!

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.