Marketing API Version

Offsite Pixel

Reading

This feature can be accessible before v2.9. You could also use the Facebook Pixel instead.

After you create a pixel you should get the code that you're going to use in your website by making an HTTP GET call to

https://graph.facebook.com/<API_VERSION>/<PIXEL_ID>

Considerations

  • The value parameter in the JS code returned in the response from Facebook is set to the standard denomination format for that currency. For instance, for USD this field is defined in dollars, not cents. The currency defaults to the currency of your ad account, or you can specify your own currency by following the instructions here.
  • 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.
  • If you are using a Doubleclick container tag, use the HTML version of the Facebook pixel
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

NameDescription
value
int64

The value, in minimum currency unit, of the transaction that the pixel is tracking. Defaults to the currency of the ad account

Fields

FieldDescription

id

numeric string

ID of the conversion pixel

creator

string

ID and name of the ad account that first created the pixel

js_pixel

string

JavaScript code for the pixel that you should place in the head of the conversion page

last_firing_time

datetime

Last time the pixel was fired

name

string

Name of the conversion pixel

tag

string

One of: checkout, registration, lead, key_page_view, add_to_cart, other

Edges

EdgeDescription

adaccounts

Accounts associated with the pixel

Validation Rules

ErrorDescription
100Invalid parameter

Creating

Examples

Create a pixel

curl \
-F "name=NAME" \
-F "tag=CHECKOUT" \
-F "access_token=___" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/offsitepixels"
You can make a POST request to offsitepixels edge from the following paths:
When posting to this edge, an OffsitePixel will be created.

Parameters

NameDescription
name
string

Name of the conversion pixel

Required
tag
enum {CHECKOUT, REGISTRATION, LEAD, KEY_PAGE_VIEW, ADD_TO_CART, OTHER}
Default value: other

Event this pixel is tracking

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
}
You may perform a POST request to the following edge from this node:

Validation Rules

ErrorDescription
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.

Updating

You may edit the metadata of a pixel one field at a time.

Examples

Modify the value field of the pixel code to $1.50 for a USD account.

curl \
-F "value=150" \
-F "access_token=_____" \
"https://graph.facebook.com/<API_VERSION>/<PIXEL_ID>"
You can update an OffsitePixel by making a POST request to /{offsite_pixel_id}.

Parameters

NameDescription
app_event
string

Type of event being fired by the pixel

app_id_for_app_event_firing
int

App id associated with the pixel

name
string

Name of the conversion pixel

tag
enum {CHECKOUT, REGISTRATION, LEAD, KEY_PAGE_VIEW, ADD_TO_CART, OTHER}

Event this pixel is tracking

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
success: bool,
}

Validation Rules

ErrorDescription
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.

Deleting

You can delete an OffsitePixel by making a DELETE request to /{offsite_pixel_id}.

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {
success: bool,
}
You can dissociate an OffsitePixel from an OffsitePixel by making a DELETE request to /{offsite_pixel_id}/adaccounts.

Parameters

NameDescription
adaccounts
list<string>

List of ad account IDs to remove from authorized accounts

Required

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.