Graph API Version

Custom Conversions

Optimize ads delivery based online and offline conversion events that you define. Track activity without adding new events Facebook pixel. Custom conversions objects are associated with an Ad Account. Use them to describe events you want to measure and events you want to track to optimize ads delivery.

Specify actions that are different from the nine standard events. See also Facebook Pixel, Conversion Tracking with Facebook Pixel and Promoted Object.

You need standard API access for this endpoint. See Marketing API, Access Levels.

For example, define a PURCHASE conversion as an event occuring when someone visits certain pages such as thankyou.html or confirmation.html:

curl \
-F 'name=URL based Custom Conversion' \
-F 'event_source_id=<FB_PIXEL_ID>' \
-F 'rule={"or":[{"url":{"i_contains": "thankyou.html"}},{"url":{"i_contains":"confirmation.html"}}]}' \
-F 'custom_event_type=PURCHASE' \
-F 'access_token=<ACCESS_TOKEN>' \
'https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customconversions'

In this example, events occur if someone visits those two .html pages, case-insensitive of the page name and extention.

Limitations

Note that the maximum number of custom conversions you can have per ad account is 40.

If you use the Ads Insights API to get metrics on custom conversions, be aware of these limitations:

  • Getting product ID breakdowns are not supported.
  • Getting unique action counts are not supported.

Reading

Custom conversions on Facebook allows you to optimize and track actions without having to add anything to your Facebook pixel base code. They also allow you to optimize for and track actions that are different from the 9 standard events that come with the Facebook pixel.

List of custom conversions for an account:

curl -G \
-d 'fields=["pixel","rule","custom_event_type"]' \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customconversions

Example

Graph API Explorer
GET /v5.0/{custom-conversion-id} HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{custom-conversion-id}',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/{custom-conversion-id}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{custom-conversion-id}",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{custom-conversion-id}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

This endpoint doesn't have any parameters.

Fields

FieldDescription
id
numeric string

ID of the custom conversion

account_id
string

Ad Account ID assoicated to this custom conversion

aggregation_rule
string

Advanced aggregation custom conversion rule

business

Business that owns the custom conversion

creation_time
datetime

Time at which the conversion was created

custom_event_type
enum {ADD_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, COMPLETE_REGISTRATION, CONTENT_VIEW, INITIATED_CHECKOUT, LEAD, PURCHASE, SEARCH, CONTACT, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, SCHEDULE, START_TRIAL, SUBMIT_APPLICATION, SUBSCRIBE, LISTING_INTERACTION, OTHER}

The type of the conversion event, e.g. PURCHASE

data_sources
list<ExternalEventSource>

Event sources of the custom conversion

default_conversion_value
integer

When conversion is URL based, the default conversion value associated to each conversion

description
string

Description of the custom conversion

event_source_type
enum

Event source type of the custom conversion, e.g. pixel, app, etc.

first_fired_time
datetime

Time at which the pixel was first fired

is_archived
bool

Whether this conversion is archived. Archived conversions are no longer tracked in the system

is_unavailable
bool

Whether this conversion is unavailable

last_fired_time
datetime

Time at which the pixel was last fired

name
string

Name of the custom conversion

offline_conversion_data_set

The offline event set that contains events

pixel

The pixel that will send events

retention_days
unsigned int32

Retention period for advanced rule

rule
string

Rule of the custom conversion

Edges

EdgeDescription

Stats data for this conversion

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
270This Ads API request is not allowed for apps with development access level (Development access is by default for all apps, please request for upgrade). Make sure that the access token belongs to a user that is both admin of the app and admin of the ad account

Creating

When you create a custom conversion, provide rule with these operators and data:

Name Description

Operators

The type of filter.

i_contains

Contains substring (case insensitive)

i_not_contains

Does not contain substring (case insensitive)

contains

Contains substring (case sensitive)

not_contains

Does not contain substring (case sensitive)

eq

Equal to (case sensitive)

neq

Not equal to (case sensitive)

lt

Less than (numeric fields only)

lte

Less than or equal to (numeric fields only)

gt

Greater than (numeric fields only)

gte

Greater than or equal to (numeric fields only)

regex_match

Matches a regular expression (eg: "example\.com.*purchase$"). The full PCRE grammar is supported

Data

The data being filtered.

url

The full escaped URL of the site visited

event

The name of the pixel event fired from your website. Example: Purchase

Examples

Defines a high-value PURCHASE when someone triggers the Purchase standard event and purchase value is greater than 100:

curl \
-F 'name=High value Purchase Custom Conversion' \
-F 'event_source_id=<FB_PIXEL_ID>' \
-F 'rule={"and":[{"event":{"eq": "Purchase"}},{"value":{"gt":100}}]}' \
-F 'custom_event_type=PURCHASE' \
-F 'access_token=<ACCESS_TOKEN>' \
'https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customconversions'

Define a custom event then build a custom conversion for it. Specify a PURCHASE conversion that to track when a user-defined, item-sold custom event occurs. Track when someone purchases an item in a certain color.

Step 1: Define item-sold custom event in Facebook pixel on your website:

fbq('trackCustom', 'item-sold', {
   color: 'black',
   value: 1.00,
   currency: 'USD'
});

Step 2: Provide a PURCHASE conversion for the item-sold custom event for a given color by specifying it as a custom parameter:

curl \
-F 'name=Item Sold Custom Conversion' \
-F 'event_source_id=<FB_PIXEL_ID>' \
-F 'rule={"and":[{"event":{"eq": "item-sold"}},{"color":{"i_contains":"black"}}]}' \
-F 'custom_event_type=PURCHASE' \
-F 'access_token=<ACCESS_TOKEN>' \
'https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customconversions'

You can make a POST request to claim_custom_conversions edge from the following paths:
When posting to this edge, a CustomConversion will be created.

Parameters

ParameterDescription
custom_conversion_id
numeric string or integer

Custom conversion ID the business claims.

Required

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
You can make a POST request to customconversions edge from the following paths:
When posting to this edge, a CustomConversion will be created.

Parameters

ParameterDescription
advanced_rule
string

Advanced ruleset for the custom conversion being created allowing multiple sources.

custom_event_type
enum {ADD_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, COMPLETE_REGISTRATION, CONTENT_VIEW, INITIATED_CHECKOUT, LEAD, PURCHASE, SEARCH, CONTACT, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, SCHEDULE, START_TRIAL, SUBMIT_APPLICATION, SUBSCRIBE, LISTING_INTERACTION, OTHER}

The custom event type of the conversion being created

default_conversion_value
float
Default value: 0

The default conversion value of the conversion being created

description
string

The description of the conversion being created

event_source_id
numeric string or integer

Event source ID, where event sources are pixel, offline event sets and so on. Aggregate custom conversion data from these sources.

name
string

The name of the conversion being created

Required
rule
string

Only count an event as a custom conversion if it fulfills this rule.

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
is_custom_event_type_predicted: numeric string,
}

Validation Rules

ErrorDescription
200Permissions error
100Invalid parameter
294Managing advertisements requires an access token with the extended permission for ads_management
You can make a POST request to customconversions edge from the following paths:
When posting to this edge, a CustomConversion will be created.

Parameters

ParameterDescription
advanced_rule
string

Advanced ruleset for the custom conversion being created allowing multiple sources.

custom_event_type
enum {ADD_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, COMPLETE_REGISTRATION, CONTENT_VIEW, INITIATED_CHECKOUT, LEAD, PURCHASE, SEARCH, CONTACT, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, SCHEDULE, START_TRIAL, SUBMIT_APPLICATION, SUBSCRIBE, LISTING_INTERACTION, OTHER}

The custom event type of the business custom conversion being created.

Required
default_conversion_value
float
Default value: 0

The default conversion value of the business custom conversion being created.

description
string

The description of the business custom conversion being created.

event_source_id
numeric string or integer

Event source ID, where event sources are pixel, offline event sets and so on. Aggregate custom conversion data from these sources.

name
string

The name of the business custom conversion being created.

Required
rule
string

Only count an event as a custom conversion if it fulfills this rule.

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
}

Validation Rules

ErrorDescription
100Invalid parameter

Updating

You can update a CustomConversion by making a POST request to /{custom_conversion_id}.

Parameters

ParameterDescription
default_conversion_value
float

The default conversion value of the conversion being created

description
string

Description of the custom conversion

name
string

Name of the custom conversion

Return Type

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

Validation Rules

ErrorDescription
100Invalid parameter

Deleting

You can delete a CustomConversion by making a DELETE request to /{custom_conversion_id}.

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
200Permissions error