Skip to content

Developer Platform

Search docs & API
Log in
Sign up

Define custom events

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

POST
Create advertiser defined events

Request parameters

Advertiser event mapping request parameters
ParameterDescription
name

string
Required
Give the event type a unique name of up to 100 characters.
Use any upper- or lower-case letters (treated as case insensitive), numerals
0
through
9
, underscores
_
, and hyphens
-
.
Example:
add_shipping_info
mapped_conversion_type

enum
Required
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:
SIGNUP

ADD_TO_CART

LEAD

CHECKOUT

SUBSCRIBE

ADD_TO_WISHLIST

ADD_PAYMENT_INFO

INITIATE_CHECKOUT

CONTACT

CUSTOMIZE_PRODUCT

FIND_LOCATION

SCHEDULE

SUBMIT_APPLICATION

START_TRIAL

PAGE_VISIT

VIEW_CATEGORY

VIEW_CONTENT

SEARCH

WATCH_VIDEO

Example request

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
FieldDescription
items.status

string
Either
success
or
failure
.
items.exceptions

array of strings
For names that failed in the submitted request, the reason for the failure.
See also the endpoint reference page for a list of error codes and messages.

Example response

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"
    }
  ]
}

Update a custom event

PATCH
Update advertiser defined events
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 has the same schema as the create endpoint. Refer to that section of this guide for data types and examples.

See mapped custom events

GET
Get advertiser 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.

Untrack custom events

DELETE
Delete advertiser defined events
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.
Was this page helpful?