Marketing API Version

Custom Conversion

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.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
No data
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

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, 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

last_fired_time

datetime

Time at which the pixel was last fired

name

string

Name of the custom conversion

offline_conversion_data_set

OfflineConversionDataSet

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

activities

Modification history for this conversion

adaccounts

Shared ad accounts data under business

stats

Stats data for this conversion

Validation Rules

ErrorDescription
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.
100Invalid parameter
294Managing advertisements requires an access token with the extended permission for ads_management

Creating

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

Parameters

NameDescription
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, 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,
}
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

NameDescription
custom_conversion_id
numeric string or integer

Custom conversion ID the business claims

Required

Return Type

Struct {
success: bool,
}
You can make a POST request to customconversions edge from the following paths:
When posting to this edge, a CustomConversion will be created.

Parameters

NameDescription
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, OTHER}

The custom event type of the conversion being created

Required
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,
}

Validation Rules

ErrorDescription
100Invalid parameter

Updating

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

Parameters

NameDescription
account_id
numeric string or integer

the adaccount one custom conversion is shared with

Required
business
numeric string or integer

the business which owns the custom conversion

Required

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
success: bool,
}
You can update a CustomConversion by making a POST request to /{custom_conversion_id}/shared_agencies.

Parameters

NameDescription
business
numeric string or integer

ID of agency business

Required

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
success: bool,
}
You can update a CustomConversion by making a POST request to /{custom_conversion_id}.

Parameters

NameDescription
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 dissociate a CustomConversion from a CustomConversion by making a DELETE request to /{custom_conversion_id}/adaccounts.

Parameters

NameDescription
account_id
numeric string or integer

the adaccount one custom conversion is unshared with

Required
business
numeric string or integer

the business which owns the custom conversion

Required

Return Type

Struct {
success: bool,
}
You can dissociate a CustomConversion from a CustomConversion by making a DELETE request to /{custom_conversion_id}/shared_agencies.

Parameters

NameDescription
business
numeric string or integer

ID of agency business

Required

Return Type

Struct {
success: bool,
}
You can delete a CustomConversion by making a DELETE request to /{custom_conversion_id}.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
No data

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
200Permissions error
100Invalid parameter