Appearance
Fresh 2026
Custom Conversions
Beginning September 2, 2025, we will start to roll out more proactive restrictions on custom conversions that may suggest information not permitted under our terms. For example, any custom conversion suggesting specific health conditions (e.g., "arthritis", "diabetes") or financial status (e.g., "credit score", "high income") will be flagged and prevented from being used to run ad campaigns.
What these restrictions mean for your campaigns:
- You won’t be able to use flagged custom conversions when creating new campaigns.
- If you have an active campaign using flagged custom conversions, you should either create a new campaign or duplicate your campaign and use a non-impacted custom conversion to avoid performance and optimization issues.
For API developers:
- Beginning September 2, 2025, the field
is_unavailablewill returntrueto signal if your custom conversions have been flagged.
More information on this update and how to resolve flagged custom conversions can be found here.
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 Meta Pixel, Conversion Tracking with Meta 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:
json
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 100.
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:
bash
curl -G \
-d 'fields=["pixel","rule","custom_event_type"]' \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customconversionsFlagged custom conversions
If a custom conversion is flagged, the is_unavailable field will be set to true.
html
{
"is_unavailable": true,
"id": "30141209892193360"
}Attempting to modify the flagged custom conversion will result in an error:
html
{
"error": {
"message": "Your custom audience is currently blocked",
"code": 2700000,
"error_subcode": 2460004,
"error_user_title": "Your custom conversion is currently blocked",
"error_user_msg": "This custom conversion is blocked because it may contain information (e.g., health, financial) not allowed under Meta’s terms. Visit the events manager to appeal this decision, edit your custom conversion and remove prohibited information, or choose a different custom conversion.",
},
}To resolve flagged custom conversions
If any of your custom conversions are flagged for suggesting information that is not allowed under our terms, you may want to consider the following options:
To resolve a flagged custom conversion in a new campaign creation:
Create new custom conversion: Use a new custom conversion and make sure that it does not include information that is not allowed under our terms.
Choose a different custom conversion: Select a different existing custom conversion and make sure it does not include information that is not allowed under our terms
To resolve a flagged custom conversion in an existing campaign:
- Duplicate your campaign and select an existing custom conversion: If you have a running campaign that is flagged due to a flagged custom conversion, consider duplicating the campaign and selecting a different custom conversion that is not flagged before publishing the new duplicated campaign. Note: Once the campaign is published, you cannot remove or select a different custom conversion.
Request a review
If you believe your custom conversion has been flagged in error and doesn't include non-permitted information, you can request a review via Ads Manager under the campaigns table, or in Events Manager under the custom conversions page.
Parameters
This endpoint doesn't have any parameters.
Fields
| Field | Description |
|---|---|
id<br>numeric string | ID of the custom conversion |
account_id<br>string | Ad Account ID assoicated to this custom conversion |
business<br>Business | Business that owns the custom conversion |
creation_time<br>datetime | Time at which the conversion was created |
custom_event_type<br>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<br>list<ExternalEventSource> | Event sources of the custom conversion |
default_conversion_value<br>integer | When conversion is URL based, the default conversion value associated to each conversion |
description<br>string | Description of the custom conversion |
event_source_type<br>enum | Event source type of the custom conversion, e.g. pixel, app, etc. |
first_fired_time<br>datetime | Time at which the pixel was first fired |
is_archived<br>bool | Whether this conversion is archived. Archived conversions are no longer tracked in the system |
is_unavailable<br>bool | Whether this conversion is unavailable |
last_fired_time<br>datetime | Time at which the pixel was last fired |
name<br>string | Name of the custom conversion |
pixel<br>AdsPixel | The pixel that will send events |
retention_days<br>unsigned int32 | Retention period for advanced rule |
rule<br>string | Rule of the custom conversion |
Edges
| Edge | Description |
|---|---|
stats<br>Edge<CustomConversionStatsResult> | Stats data for this conversion |
Error Codes
| Error | Description |
|---|---|
| 100 | Invalid parameter |
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:
json
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:
js
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:
json
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:
/{business_id}/claim_custom_conversions
When posting to this edge, a CustomConversion will be created.
Parameters
| Parameter | Description |
|---|---|
custom_conversion_id<br>numeric string | Custom conversion ID the business claims.<br>Required |
Return Type
Struct {
success: bool,
}
Error Codes
| Error | Description |
|---|---|
| 100 | Invalid parameter |
You can make a POST request to customconversions edge from the following paths:
/act_{ad_account_id}/customconversions
When posting to this edge, a CustomConversion will be created.
Parameters
| Parameter | Description |
|---|---|
action_source_type<br>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<br>string | Advanced ruleset for the custom conversion being created allowing multiple sources. |
custom_event_type<br>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<br>float | Default value: 0<br>The default conversion value of the conversion being created. |
description<br>string | The description of the conversion being created. |
event_source_id<br>numeric string or integer | Event source ID, where event sources are a Pixel, offline event sets and so on. Aggregate custom conversion data from these sources. |
name<br>string | The name of the conversion being created.<br>Required |
rule<br>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,
}
Error Codes
| Error | Description |
|---|---|
| 200 | Permissions error |
| 100 | Invalid parameter |
Updating
You can update a CustomConversion by making a POST request to /{custom_conversion_id}.
Parameters
| Parameter | Description |
|---|---|
default_conversion_value<br>float | The default conversion value of the conversion being created |
description<br>string | Description of the custom conversion |
name<br>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,
}
Error Codes
| Error | Description |
|---|---|
| 100 | Invalid 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,
}
Error Codes
| Error | Description |
|---|---|
| 200 | Permissions error |
| 100 | Invalid parameter |