When tracking conversion events, you can define your own custom event types that reflect customer interactions unique to your business more closely than Pinterest standard events. As with standard conversion events, you can use your own defined events in Pinterest's reporting and campaign optimization.
Defining a custom event type involves naming the event and mapping it to a similar Pinterest standard event, so that Pinterest can track it for campaign optimization.
Using the endpoints documented in this guide, you can define and manage up to 15 events for every advertiser ID.
If you first passed custom events using the Conversions API, Pinterest Tag, or other ingestion methods, make sure to also map them to Pinterest standard events using the advertiser-defined event endpoints in this guide or in Ads Manager. Otherwise, those events are untracked and cannot be used for reporting or optimization. Also, make sure the event names that you pass match the names you define and map exactly. You can either pass your custom events to Pinterest and then map them to standard events, or you
can create and map the events first and then pass them.
You can either pass your custom events to Pinterest and then map them to standard events, or you
can create and map the events first and then pass them.
Map your defined event to a standard event
Advertiser event mapping request parameters| Parameter | Description |
|---|
| Give the event type a unique name of up to 100 characters. Use any upper- or lower-case letters (treated as case insensitive), numerals through , underscores , and hyphens . |
| Map your custom event to a similar, optimizable Pinterest standard event, so that Pinterest handles your event as the standard event for campaign optimization purposes. Set to one of the following: |
In this example, two advertiser-defined events are created:
curl --request POST \
--url https://api.pinterest.com/v5/ad_accounts/123456789012/advertiser_defined_events \
--header 'authorization: Bearer pina_ABCD1234...' \
--header 'content-type: application/json' \
--data '{
"items": [
{
"name": "custom_add_to_cart",
"mapped_conversion_type": "ADD_TO_CART"
},
{
"name": "custom_checkout",
"mapped_conversion_type": "CHECKOUT"
}
]
}'
Response fields to keep in mind
The endpoint returns an array for each custom name in the request, along with the following fields:
Advertiser event mapping response fields| Field | Description |
|---|
| Either or . |
| For names that failed in the submitted request, the reason for the failure. |
This response shows one failure and one successful submission:
{
"items": [
{
"name": "custom_add_to_cart",
"status": "failure",
"exceptions": ["duplicate_event_name"]
},
{
"name": "custom_checkout",
"status": "success"
}
]
}
Change any event name or mapping associated with your ad account.
If your ad account is cloned, so that conversion events are inherited from a parent account, you
cannot update or delete custom-defined events.
If your ad account is cloned, so that conversion events are inherited from a parent account, you
cannot update or delete custom-defined events.
This endpoint is useful for keeping track of all mapped custom events associated with your ad account. If any custom events are not listed in the endpoint's response, they are untracked, and you should map them.
You can also see untracked custom events in Ads Manager by clicking Conversions, and viewing the table titled Custom events not tracked in the Events overview section. Pass the names of custom events to this endpoint to stop Pinterest from tracking them. You do not delete the events.
If your ad account is cloned, so that conversion events are inherited from a parent account, you
cannot update or delete custom-defined events.
If your ad account is cloned, so that conversion events are inherited from a parent account, you
cannot update or delete custom-defined events.