Conversion pixels

Conversion pixels are used to signal events that happened while the user was browsing your website like viewing a product, registering or even adding a product to his cart. This pixel is best used in conjunction with oCPM to drive a particular event.

Create a conversion pixel

The first step is to create the pixel for the event that you want to track:

 curl "https://graph.facebook.com/act_<ad account id>/offsitepixels" \
 -F access_token=___ -F name="NAME" -F tag=CHECKOUT

You use your ads account id as the path to offsitepixels and you should give a name to your pixel. You can also tag this pixel with any of the tags below. If you don't specify one, the pixel will be created with 'OTHER' as its tag.

• CHECKOUT
• REGISTRATION
• LEAD
• KEY_PAGE_VIEW
• ADD_TO_CART
• OTHER

After making the call to create a pixel, you will have the id of the pixel as a return of that call.

Listing all conversion pixels

You can list all the conversion pixels that were created for your account with the following call:

 curl -G "https://graph.facebook.com/act_<ad account id>/offsitepixels" \
 -d access_token=___

This call will return an array of JSON objects that contains the id, name and tag of each pixel created for the account specified.

You can also retrieve the information of a given pixel:

 curl -G "https://graph.facebook.com/<offsite pixel id>" -d access_token=___

The response is a JSON object with the following information:

name	description
id	ID of the pixel
name	Name of the pixel
tag	Tag of the pixel
status	Unverified: no ping has been received. Inactive: no ping has been received in the past 24 hours. Active: at least one ping has been received in the last 24 hours.
creator	ID and name of the ad account that first created the pixel
js_pixel	JavaScript code for the pixel that you should place in the head of the conversion page.

Changing name and tag of a pixel

It's easy to edit the name and tag of a pixel if you want to:

 curl "https://graph.facebook.com/<offsite pixel id>" \
 -F access_token=___ -F name="NEWNAME" -F tag=OTHER

You can edit only the name by omitting the tag parameter and vice-versa. If the update succeeds then the call will return true, otherwise a JSON object with the error message.

Deleting a pixel

It's possible to delete a pixel:

 curl -XDELETE "https://graph.facebook.com/<offsite pixel id>" \
 -F access_token=___

It will return true if it successfully deleted the pixel or a JSON object with the error message.

Retrieving ad accounts authorized to use a pixel

You can check which ad accounts are authorized to use a given pixel:

 curl -G "https://graph.facebook.com/<offsite pixel id>/adaccounts" \
 -d access_token=___

The call above will return an array that has the offsite pixel id as the index and another array with the list of accounts authorized to use this pixel.

Authorizing and de-authorizing ad accounts to use a pixel

It's always possible to add more ad accounts to the authorized list of accounts that are able to use a given pixel.

 curl "https://graph.facebook.com/<offsite pixel id>/adaccounts" \
 -F access_token=___ -F adaccounts="[<another ad account id>]"

If you want to remove an account from the list of authorized accounts, just make the following call:

 curl -XDELETE "https://graph.facebook.com/<offsite piexel id>/adaccounts" \
 -F access_token=___ -F adaccounts="[<another ad account id>]"

You should expect true as a return of these calls if everything was ok or a JSON object in case there was any errors.

Getting the pixel snippet

After you setup a pixel you should get the code that you're going to use in your website:

 curl -G "https://graph.facebook.com/<offsite pixel id>" -d access_token=___

The method above is preferred. You can also get the pixel snippet by:

 curl -G "https://graph.facebook.com/<offsite pixel id>/snippets" \
 -d value=VALUE -d access_token=___

You can specify how much a pixel fire is worth to you using the value field, which should be specified in cents and it defaults to 1 cent if you don't specify it.

It will return an array of JSON objects containing the id of the ad account and one field:

• js: javascript code that represents this pixel

Note:

• The value parameter in the JS code takes dollars, not cents
• You need a pixel for each type of offsite event that you want to track. For example, if you want to track REGISTRATION and CHECKOUT follow the procedure above for each one of these events.
• If you want to piggy back the Facebook conversion tracking pixel off a tag manager and can only use an HTML version, please copy and use the HTML component of the JS code snippet which is found between <noscript> and </noscript>
• The pixel works on all webpages, including mobile web and canvas apps.

Pixel Tracking

You can track the performance of different pixels in an ad by specifying the tracking pixel in the ad's tracking_specs field. Let's say that you define:

 tracking_specs="[{'action.type':'offsite_conversion','offsite_pixel':1}, {'action.type':'offsite_conversion','offsite_pixel':2}, {'action.type':'offsite_conversion','offsite_pixel':3}]"

This will allow you to track the performance of pixels "1", "2" and "3". If you want to optimize for pixel "1" only you can define the conversion_specs for that. Learn more about conversion_specs here:

 conversion_specs="[{'action.type':'offsite_conversion','offsite_pixel':1}]"

If the conversion_specs and tracking_specs are used on the same adgroup you will be able to track pixels "1", "2" and "3" but we will optimize only for pixel "1".

As an example, this is useful when you want to optimize for CHECKOUT, but also want to track the number of REGISTRATION and ADD_TO_CART.

Note: Pixels that are optimized for by specifying the pixel ID in the conversion_specs are automatically tracked, so you do not need to specify the same pixel in tracking_specs.

Creating your ads

Now that you created your pixel, you are ready to create your ads.

In our first example we will create an offsite oCPM ad that tracks and optimizes the conversion pixel 6009125095680:

 curl "https://graph.facebook.com/act_<ad account id>/adgroups \
 -F campaign_id=<campaign id> -F bid_type=7 \
 -F bid_info="{'1':20,'38':10,'44':20,'55':500}" \
 -F targeting="{'countries':['US']}" -F creative="{creative_id:<creative_id>}" \
 -F name="offsite_ocpm" \
 -F conversion_specs="[{'action.type':'offsite_conversion','offsite_pixel':6009125095680}]" \
 -F access_token=___

Now, to create an offsite CPC ad that tracks the conversion pixel 6009125095680 but does not optimize:

 curl "https://graph.facebook.com/act_<ad account id>/adgroups \
 -F campaign_id=<campaign id> -F bid_type=1 -F max_bid=100 \
 -F targeting="{'countries':['US']}" -F creative="{creative_id:<creative_id>}" \
 -F name="offsite_cpc" \
 -F tracking_specs="[{'action.type':'offsite_conversion','offsite_pixel':6009125095680}]" \
 -F access_token=___

And as a last example, to create an oCPM ad that tracks both conversion pixels 6009125095680 and 434566956589050, but optimizes for 6009125095680:

 curl "https://graph.facebook.com/act_<ad account id>/adgroups \
 -F campaign_id=<campaign id> -F bid_type=7 \
 -F "bid_info={'1':0,'38':0,'44':0,'55':500}" \
 -F targeting="{'countries':['US']}" -F creative="{creative_id:<creative_id>}" \
 -F name="offsite_ocpm" \
 -F conversion_specs="[{'action.type':'offsite_conversion','offsite_pixel':6009125095680}]" \
 -F tracking_specs="[{'action.type':'offsite_conversion','offsite_pixel':434566956589050}]" \
 -F access_token=___