Create a custom conversion via POST /{ad_account_id}/customconversions with a name, pixel_id, and rule; the rule is a JSON filter object that matches pixel events by event name and optional URL or parameter conditions.
Set the custom_event_type to one of Meta's standard categories (e.g., PURCHASE, LEAD, ADD_TO_CART) to enable reporting in standard conversion columns; use OTHER if the event does not map to a standard type.
Optionally set a value_type to CONSTANT (and supply a custom_event_values array) or USE_VALUE if your pixel fires a currency value; this controls how conversion value is attributed.
Reference the custom conversion ID in the ad set's promoted_object.custom_conversion_id to optimize campaigns toward it; ensure the ad set's optimization_goal is OFFSITE_CONVERSIONS.
Verify the custom conversion is receiving data by checking its status via GET /{custom_conversion_id}; the last_fired_time field shows the most recent pixel event that matched the rule.
Test the rule logic using the Meta Pixel Helper browser extension before going live; incorrect URL match conditions are a common cause of zero-firing custom conversions.
Known gotchas
Custom conversions are limited per ad account; if you approach the limit, you must archive unused custom conversions before creating new ones — archived conversions cannot be targeted in active campaigns.
The rule JSON for a custom conversion must reference a pixel event name exactly as it is being fired; if the pixel fires 'lead' (lowercase) but the rule checks 'Lead' (title case), the rule will never match and the conversion will show zero fires.
Optimizing an ad set toward a custom conversion requires that the conversion has enough historical fires to pass Meta's learning phase; custom conversions with very few events per week will cause campaigns to remain in extended learning or under-deliver.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp