Optimize ads delivery based on online and offline conversion events that you define. Track activity without adding new events Meta 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.
Note that the maximum number of custom conversions you can have per ad account is 100.
If you use the Ads Insights API to get metrics on custom conversions, be aware of these limitations:
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.
Starting September 14, 2021, the following fields will throw an error for version 12.0+ calls made by apps that lack the endpoint's required permissions. This change will apply to all versions on December 13, 2021.
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
Field | Description |
---|---|
id numeric string | ID of the custom conversion |
account_id string | Ad Account ID assoicated to this custom conversion |
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, FACEBOOK_SELECTED, 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 |
pixel | The pixel that will send events |
retention_days unsigned int32 | Retention period for advanced rule |
rule string | Rule of the custom conversion |
Edge | Description |
---|---|
Edge<CustomConversionStatsResult> | Stats data for this conversion |
Error | Description |
---|---|
100 | Invalid parameter |
368 | The action attempted has been deemed abusive or is otherwise disallowed |
200 | Permissions error |
When you create a custom conversion, provide rule
with these operators and data:
Name | Description |
---|---|
Operators | The type of filter. |
Data | The data being filtered. |
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'
claim_custom_conversions
edge from the following paths: Parameter | Description |
---|---|
custom_conversion_id numeric string or integer | Custom conversion ID the business claims. Required |
success
: bool, Error | Description |
---|---|
100 | Invalid parameter |
customconversions
edge from the following paths: Parameter | Description |
---|---|
action_source_type enum{app, chat, email, other, phone_call, physical_store, system_generated, website, business_messaging} | action source type the custom conversion is created from |
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, FACEBOOK_SELECTED, 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. |
id
in the return type.id
: numeric string, is_custom_event_type_predicted
: numeric string, Error | Description |
---|---|
100 | Invalid parameter |
200 | Permissions error |
190 | Invalid OAuth 2.0 Access Token |
/{custom_conversion_id}
.Parameter | Description |
---|---|
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 |
success
: bool, Error | Description |
---|---|
100 | Invalid parameter |
/{custom_conversion_id}
.success
: bool, Error | Description |
---|---|
200 | Permissions error |
100 | Invalid parameter |