Track conversion events in the API

Tracking conversion events, actions that your customers take in person or online, helps you measure the success of your ad campaigns, optimize marketing strategies, and understand customer behavior.

You can use the Conversions API to track events on websites, apps, or offline sources, such as store locations. You also can use the API with Pinterest Tag for additional coverage.

What are conversion events?

See the following table to understand what happens in each event and which operations it is used for.

Conversion event types
Name in API	Name in Tag	Purpose	Usable for
`add_payment_info`	`AddPaymentInfo`	Track people who enter payment information, such as a credit card number.	Conversion reporting
`add_to_cart`	`AddToCart`	Track people who add items to shopping carts.	Audience creation Conversion reporting
`add_to_wishlist`	`AddToWishList`	Track people who add a viewed item to a wish list.	Conversion reporting
`app_install`	N/A	Track people who install your app for the first time, or the first time an app starts on a device.	Audience creation Conversion reporting
`app_open`	N/A	Track people each time they open your app after they access it for the first time.	Audience creation Conversion reporting
`checkout`	`Checkout`	Track people who complete transactions.	Audience creation Conversion reporting
`contact`	`Contact`	Track people who contact you through phone, email, chat or other methods.	Audience creation
`customize_product`	`CustomizeProduct`	Track people who customize a product using a tool on your website or app.	Audience creation
`find_location`	`FindLocation`	Track people who find your business location through web or app.	Audience creation
`initiate_checkout`	`InitiateCheckout`	Track people who start the process of checking out an item for purchase but do not complete it.	Conversion reporting
`lead`	`Lead`	Track people who show interest in your product or service.	Audience creation Conversion reporting
`page_visit`	`PageVisit`	Track people who view primary pages, such as product pages and article pages.	Audience creation Conversion reporting
`schedule`	`Schedule`	Track people who schedule an appointment at one of your business locations.	Audience creation
`search`	`Search`	Track people who search for products or services you offer.	Audience creation Conversion reporting
`signup`	`SignUp`	Track people who sign up for your product or service.	Audience creation Conversion reporting
`start_trial`	`StartTrial`	Track people who start a free trial of a product or service.	Audience creation
`submit_application`	`SubmitApplication`	Track people who complete and submit an application for a product, service, or program.	Audience creation
`subscribe`	`Subscribe`	Track people who subscribe to receive information and updates related to products or services.	Conversion reporting
`view_category`	`ViewCategory`	Track people who view category pages.	Audience creation Conversion reporting
`view_content`	`ViewContent`	Track people who view site content.	Conversion reporting
`watch_video`	`WatchVideo`	Track people who watch videos.	Audience creation Conversion reporting
Custom event that you name	Custom event that you name	Track an event that does not conform to any of the Pinterest-defined types. You give this event a unique name that is meaningful to your business. Create the name with any upper- or lower-case letters (treated as case insensitive), numerals 0 through 9, underscores `_` , and hyphens `-` . Limit the name to 100 characters. Example: `TookSurvey` Make sure to map any custom event to a Pinterest standard event.	Audience creation

Before you start sending conversion events

Make sure you have the following prerequisites in place.

Conversion API prerequisites
What you need	Why you need it	How to get it
Pinterest advertiser account	The Conversions API endpoint requires a unique identifier associated with the ad account that is sending events.	Learn how to create an advertiser account.
Conversion token if you only want to access the Conversions API endpoint or OAuth token with at least `ads:write` scopes if you want to access other API endpoints	You need a token to authenticate against the Conversions API endpoint.	For conversion token: See Generate a conversion token. For OAuth token: Set up your OAuth token and learn about scopes.
Pinterest advertiser account	For you to interact with any tools/endpoints related to campaigns, ad groups, and ads, your OAuth token must be related to a Pinterest advertiser ID.	Learn how to create an advertiser account.

Generate a conversion token

If you plan to only use the Conversion API and no other endpoints, use the following steps to get a conversion token:

Go to Ads Manager, and select Ad Account Overview > Conversions > Conversions API > Set up API.
Select Conversion access token, and click Generate new token.
Copy your newly generated token, which is displayed with your ad account ID.

Send conversion events

See this section to learn how to send events to the Conversions API.

Send the request

POST

Send conversions

For best-quality conversion data, it is important to include the right parameters for each platform and event type and to format the parameters correctly. See the parameter tables below for guidance.

To check the quality of your conversion data, go to the Conversions Health page in Ads Manager.

Note some terminology items for the following tables:

When we tag parameters as recommended for certain platforms or conversion events, we mean that including them in the request helps ensure higher-quality, more accurate conversion data.
When we tag parameters as optional for certain platforms or conversion events, we mean that including them in the request provides additional useful context.
These parameter tables do not indicate whether parameters are required for the API request to be successful. See
POST
Send conversions
to find out which parameters are required.
The user in these parameter descriptions is the person who took the action that initiated the conversion event, such as a customer visiting your website or store.

Format server event parameters

See this section for parameters that contain information about the conversion event.

Server event parameters
Parameter	Recommended for these platforms	Recommended for or optional for events?	Formatting guidelines and examples
`action_source` string Required The platform from which the event was ingested into the API. This is different from the `device_type` parameter, which indicates the actual device on which the event occurred. See Format app information.	All platforms	Recommended for all events.	Use any of these enum values: `app_android` `app_ios` `web` `offline`
`event_id` string Required Unique identifier for event, used also for deduplicating events ingested through the conversion API and Pinterest tracking.	All platforms	Recommended for all events.	Any unique string associated with the purchase, such as an order number or transaction ID. See best practices for using event IDs.
`event_name` string Required	All platforms	Recommended for all events.	Use any of these enum values: `add_payment_info` `add_to_cart` `add_to_wishlist` `app_install` `app_open` `checkout` `contact` `customize_product` `find_location` `initiate_checkout` `lead` `page_visit` `schedule` `search` `signup` `start_trial` `submit_application` `subscribe` `view_category` `view_content` `watch_video` You also can define an event that does not conform to any of the Pinterest-defined types. You can name it with any upper- or lower-case letters (treated as case insensitive), numerals 0 through 9, underscores `_` , and hyphens `-` . Limit the name to 100 characters. Example: `TookSurvey` You can custom-define up to 15 types of events for every advertiser ID.
`event_source_url` string, nullable Optional	Web	Recommended for all events.	Include the full URL path for the conversion event. `https://www.myshop.org/` For Pinterest click events, include `&epik` query string, a unique click identifier, in the URL. The epik (External Pinterest ID Key) value is a unique identifier that Pinterest uses to help track users across devices and sessions. It is typically passed as a query parameter in your URLs, for example, after a click on a Pinterest ad. `https://www.myshop.org/checkout?epik=123abc456def789ghi`
`event_time` integer Required	All platforms	Recommended for all events.	Enter as Unix timestamp in seconds.
`opt_out` boolean Optional Whether the user has opted out of web or offline conversion events. Or Whether the user has enabled Limit Ad Tracking on iOS, or opted out of Ads Personalization on Android for app platform events.	Web App	Recommended for all events.	Boolean: `true` `false`
`partner_name` string, nullable Optional Third-party responsible for sending the event to API on behalf of the advertiser.	All platforms	Recommended for all events.	Syntax: `ss-companyname` For direct integration, use value `direct` .

Format user data parameters

See this section for parameters related to information about the user who is taking the action to trigger the conversion event.

These parameters--all optional and all strings--are nested within the required

user_data

object, which must include at least one of the following:

em
hashed_maids
Pairing of
client_ip_address
and
client_user_agent

User data parameters
Parameter	Recommended for these platforms	Recommended for or optional for events?	Formatting guidelines and examples
`external_id` Unique string that you use to identify a customer, such as user ID or loyalty id. Learn more about using external IDs.	All platforms	Recommended for all events.	SHA-256 hash `6a7a73766627eb611720883d5a11cc62b5bfee237b00a6658d78c50032ec4aee`
`click_id` Cookie generated when a user clicks an ad.	Web App	`add_to_cart` `checkout` `lead` `page_visit` `search` `signup` `view_category` `watch_video`	Use the `_epik` cookie instead of the `&epik=` query parameter. While both are accepted, passing `_epik` cookie values is necessary when a URL parameter is missing or removed and ensures greater coverage. `dj0yJnU9b2JDcFFHekV4SHJNcmVrbFBkUEdqakh0akdUT1VjVVUmcD0y Jm49cnNBQ3F2Q2dOVDBXWWhkWklrUGxBUSZ0PUFBQUFBR1BaY3Bv`
`client_ip_address` User's IP address	Web	Recommended for all events	Valid IPv4 or IPv6. No pure zero ( `0.0.0.0` ) addresses. `216.3.128.12`
`client_user_agent` User agent string for user's browser.	Web App	Recommended for all events.	Include at least two of each of these information categories: `OSfamily` `browserfamily` `devicefamily` Do not send "Other" or `null` . Do not send user agents produced by bot. `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36 Edge/12.246`
`country` User's country.	All platforms	Recommended for all events.	SHA-256 hash of two-character ISO-3166 country code in lower case and UTF format.
`ct` User's city.	All platforms	Recommended for all events.	SHA-256 hash in lowercase, and without spaces or punctuation.
`db` User's date of birth.	All platforms	Recommended for all events.	SHA-256 hash of YYYYMMDD.
`em` User's email address.	All platforms	Recommended for all events.	SHA-256 hash of email addresses in lower case.
`ge` User's gender.	All platforms	Recommended for all events.	SHA-256 hash: `f` (female) `m` (male) `n` (non-binary)
`ln` User's last name.	All platforms	Recommended for all events.	SHA-256 hash of last name in lower case.
`ph` User's phone number.	All platforms	Recommended for all events.	SHA-256 hash of phone numbers. Only digits with country code, area code, and number. Remove symbols, letters, spaces, and leading zeros.
`st` User's state.	All platforms	Recommended for all events.	SHA-256 hash of two-letter code in lower case.
`zp` User's zip code.	All platforms	Recommended for all events.	SHA-256 hash of zip code. Only digits.
`hashed_maids` User's Google Advertising IDs (GAIDs) or Apple's Identifier for Advertisers (IDFAs)	App	Recommended for all events.	SHA-256 hash\ `0192518eb84137ccfe82c8b6322d29631dae7e28ed9d0f6dd5f245d73a58c5f1`
`partner_id` Unique identifier for user information, such as RampID, only used by integration partners.	All platforms	Optional for all events.	Use only if you are a Pinterest integration partner.

Format app information

See this table for information about the advertiser's app involved in the event and the user's device connecting to the app.

App data parameters
Parameter	Recommended for these platforms	Recommended for or optional for events?	Formatting guidelines and examples
`app_id` App store app ID.	App	Optional for all events.	See best practices for strings.
`app_name` App store app name.	App	Optional for all events.	See best practices for strings.
`app_version` App store app version.	App	Optional for all events.	See best practices for strings.
`device_brand` Brand name of user'mobile device.	App	Optional for all events.	See best practices for strings.
`device_carrier` Carrier for user'mobile device.	App	Optional for all events.	See best practices for strings.
`device_model` Model name for user'mobile device.	App	Optional for all events.	See best practices for strings.
`device_type` Type of user's device on which the event occurred.	App	Optional for all events.	This is a free-form string. Consider using values that best describe the device, such as `"desktop web"` , `"mobile web"` , or `"iPhone app"` or `"Android app"` (to indicate the native Pinterest mobile app). Note that you can provide additional specific information about the device by using other parameters such as `app_name` , `app_version` , `device_brand` , `device_carrier` , `device_model` , and `os_version` . See best practices for strings. This parameter is different from `action_source` , which indicates the platform from which the event is being ingested. See Format server event parameters.
`language` Language set on user'mobile device.	App	Optional for all events.	Two-character ISO-639-1 language code in lower case and UTF format.
`os_version` Operating system version number for user'mobile device.	App	Optional for all events.	See best practices for strings.
`wifi` Whether the event occurred when the user device was connected to a wireless network.	Web App	Optional for all events.	Boolean: `true` `false`

Format product event information

See this table for parameters events related to products.

Note the nesting structure for these parameters:

The optional
custom_data
object contains information at the level of the event, such as any money that was spent in the conversion.
The optional
custom_data.contents
object contains information about specific merchandise items involved in the event.

These parameters are all strings, except as noted. They are all optional, as in not required by the API for the request to succeed.

We suggest that you use

custom_data.contents

object, especially if your event involves multiple products.

We suggest that you use

custom_data.contents

object, especially if your event involves multiple products.

Product event parameters
Parameter	Recommended for these platforms	Recommended for or optional for events?	Formatting guidelines and examples
`custom_data.currency` The type of currency used in a purchase event.	All platforms	Recommended for: `add_payment_info` `add_to_cart` `add_to_wishlist` `checkout` `initiate_checkout` `search` `subscribe` `view_content` (if the user is on a product page) Optional for all other events.	ISO-4217 currency code. If you do not pass the currency with the value, we use the currency that the advertiser set when creating an account.
`custom_data.value` Total monetary value for purchased items. Use pre-tax, pre-shipping total.	All platforms	Recommended for: `add_payment_info` `add_to_wishlist` (if the user is on a product page) `custom` `checkout` `initiate_checkout` `search` `subscribe` `view_content` (if the user is on a product page) Optional for all other events.	Accepted as a string in the request and parsed into a double. For example, with two items in a checkout event, the value should be the total price. Always send currency when sending value. Should not contain unusually high values or contain invalid values such as negative number or zero.
`custom.data.content_ids` Array of product IDs related to the event. Each listed ID is listed in the `custom.data.contents` array of objects.	All platforms	Recommended for: `add_payment_info` `add_to_cart` `add_to_wishlist` `checkout` `custom` `initiate_checkout` `page_visit` `search` `view_content` (if the user is on a product page) Optional for all other events.	See best practices for strings.
`custom.data.content_name` Name of the page or product associated with the event	All platforms	Recommended for: `add_payment_info` `add_to_cart` `add_to_wishlist` `custom` `initiate_checkout` `page_visit` `view_content` (if the user is on a product page) Optional for all other events.	See best practices for strings.
`custom.data.content_category` Type of merchandise.	All platforms	Recommended for: `add_to_cart` `checkout` `custom` Optional for all other events.	See best practices for strings.
`custom.data.content_brand` Brand of merchandise.	All platforms	Recommended for: `add_to_cart` `checkout` `custom` Optional for all other events.	See best practices for strings.
`custom_data.num_items` Total number of products involved, for example, products purchased in a checkout event.	All platforms	Recommended for: `add_payment_info` `checkout` `custom` `intiate_checkout` `search` Optional for all other events.	See best practices for strings.
`custom_data.order_id` Identifier for the order in a purchase-related event.	All platforms	Recommended for: `add_to_cart` `checkout` Optional for all other events.	See best practices for strings.
`custom_data.search_string` String entered in a search event.	All platforms	Recommended for: `search` Optional for all other events.	See best practices for strings.
`custom_data.opt_out_type` Opt-out type for privacy. If user has opted out of tracking for web conversion events, this parameter indicates whether the user has enabled Limited Ads Tracking (if `action_source` is set to `app_ios` ) or opted out of Ads Personalization (if `action_source` is set to `app_android` ). Learn about limited data processing.	All platforms	Optional for all events.	The only accepted value is `ldp` .
`np` Third-party partner sending the event to the API on behalf of the advertiser. Only send this field if Pinterest has worked directly with you to define a value for partner_name.	All platforms	Recommended for all events.	See best practices for strings.
`custom_data.contents.item_brand` Brand of an individual merchandise item.	All platforms	Recommended for: `add_to_cart` `add_to_wishlist` `checkout` `custom` `page_visit` `search` `view_content` (if the user is on a product page) Optional for all other events.	See best practices for strings.
`custom_data.contents.item_category` Product category of an individual merchandise item.	All platforms	Recommended for: `add_to_cart` `add_payment_info` `add_to_wishlist` `checkout` `custom` `initiate_checkout` `page_visit` `search` `view_content` (if the user is on a product page) Optional for all other events.	See best practices for strings.
`custom_data.contents.item_name` Product name of an individual merchandise item.	All platforms	Recommended for: `add_to_cart` `add_payment_info` `add_to_wishlist` `checkout` `custom` `initiate_checkout` `page_visit` `search` `view_content` (if the user is on a product page) Optional for all other events.	See best practices for strings.
`custom_data.contents.item_price` Price of an individual merchandise item (single quantity).	All platforms	Recommended for: `add_to_cart` `add_payment_info` `add_to_wishlist` `checkout` `custom` `initiate_checkout` `page_visit` `search` `view_content` (if the user is on a product page) Optional for all other events.	See best practices for strings.
`custom_data.contents.quantity` Quantity of individual merchandise item selected by user.	All platforms	Recommended for: `add_payment_info` `checkout` `custom` `initiate_checkout` `search` `view_content` (if the user is on a product page) Optional for all other events.	See best practices for strings.
`custom_data.contents.id` Product ID of an individual merchandise item.	All platforms	Recommended for: `add_to_cart` `add_to_wishlist` `add_payment_info` `checkout` `custom` `initiate_checkout` `page_visit` `search` `view_content` (if the user is on a product page) Optional for all other events.	See best practices for strings.

Example request

The following example shows two events being sent. One of them

subscription

is incorrectly named to illusrate how the reponse shows mixed results.

Note that the

ad_account

ID is required for the request path.


curl --request POST \
  --url 'https://api.pinterest.com/v5/ad_accounts/549768257474/events' \
  --header 'Authorization: Bearer pina_ABCD1234...' \
  --header 'Content-Type: application/json' \
  --data '{
  "data": [
    {
      "event_name": "subscription",
      "action_source": "web",
      "event_time": 1769818893,
      "event_id": "evt-subscription-001",
      "event_source_url": "https://www.example.com/subscribe",
      "opt_out": false,
      "user_data": {
        "em": [
          "411e44ce1261728ffd2c0686e44e3fffe413c0e2c5adc498bc7da883d476b9c8"
        ],
        "client_ip_address": "216.3.128.12",
        "client_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
      },
      "custom_data": {
        "currency": "USD",
        "value": "9.99"
      }
    },
    {
      "event_name": "checkout",
      "action_source": "web",
      "event_time": 1769818901,
      "event_id": "evt-checkout-002",
      "event_source_url": "https://www.example.com/checkout/complete",
      "opt_out": false,
      "user_data": {
        "em": [
          "411e44ce1261728ffd2c0686e44e3fffe413c0e2c5adc498bc7da883d476b9c8"
        ],
        "client_ip_address": "216.3.128.12",
        "client_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
      },
      "custom_data": {
        "currency": "USD",
        "value": "66.95",
        "order_id": "order-12345",
        "num_items": 2
      }
    }
  ]
}'

Example response

The response indicates that one event was not sent because it was incorrectly named.


{
  "num_events_received": 2,
  "num_events_processed": 1,
  "events": [
    {
      "status": "failed",
      "error_message": "Invalid event_name: subscription. Use a supported conversion event_name (for example subscribe, checkout).",
      "warning_message": null
    },
    {
      "status": "processed",
      "error_message": null,
      "warning_message": null
    }
  ]
}

Send test events

You can send test events to make sure your event payload is constructed correctly for accurate and comprehensive conversion tracking.

Test event data is sent to a sandbox environment. Unlike "production data", test data is not processed for reporting or optimization.

If you send multiple test events in a request, limit the batch to 20 events. We only process the first 20 events in a batch.

To send a test event:

Send an event with the query parameter

test

set to

true

. Example:


https://api.pinterest.com/v5/ad_accounts/{AD-ACCOUNT-ID}/events?test=true

Go to Ads Manager and select Campaign manager > Conversions > Test events to verify that the test event was sent successfully.

Best practices for sending events

To get the most out of your event data, use the following best practices:

Include all recommended parameters and format them correctly

Include in your request all parameters that are recommended for specific platforms and events. Learn more about improving event quality. Follow formatting guidelines for all parameters.

Learn how to track event quality in the API.

Use general best practices for strings

Avoid passing excessively long strings.
Properly escape any special characters using JSON standard guidelines.
Separate multiple strings with commas.

Batch events

Batching event data up to the limit of 1000 per request helps make data transfer more efficient and reduces the likelihood of running into rate limits.

Provide data to clients in real time

Send event data in real time or with a maximum lag time of one hour for better user experience.

Keep parameter values dynamic

Pass actual, real-time values associated with each conversion event, rather than static or predetermined values. This will ensure data accuracy and integrity for reporting and optimization. For example make currency for checkouts reflect the user's currency instead of a universal hardcoded value.

Use event IDs effectively

An event ID can be any unique string associated with the purchase, such as an order number or transaction ID.

If a user makes multiple purchases, each with its own order number, each corresponding API call must include the respective order number for

event_id

to distinguish these two purchase events as distinct orders.

The two corresponding browser pixel purchase events would also need to send the same order numbers in the eventID parameter to make it clear that there were only two unique purchase events, not four.

For other events without a purchase-related ID, use any random number as long as it is the same sent for both browser and server events.

For deduplication, the

eventID

from a browser or app event must match the

event_id

in the corresponding server event.

Prevent event duplication

If you use multiple ingestion sources, prevent redundant events from being counted more than once.

Pass the

event_id

and

event_name

parameter in all the sources you use, making sure that the

event_id

is identical for each redundant event.

For example, if both the API and Pinterest Tag ingest the event of a specific person visiting your website that

event_id

must be the same in both instances for Pinterest to regard them as duplicates.

In the case of redundant events, Pinterest retains the first event captured and removes duplicates within 48 hours.

Use external IDs

An external ID is a string that represents a user or a browser on your system, such as a user ID or a loyalty ID. Adding more identifiers improves your event quality and helps improve your performance.

With

external_id

, you can send: Multiple

external_id

strings for events in one payload Standard

external_id

strings for all events, such as session ID/Visit ID, Client ID/Visitor ID Conditional

external_id

strings for sign in users such as membership ID or loyalty id

Pinterest uses

external_id

with other customer information parameters to form an external_id+other-customer-information mapping when a given event is matched using customer information parameters

In future events where more customer information will be restricted from being shared, having (external_id, or other customer information) will help you minimize the impact of matched event data loss.

See the following examples of external IDs you can use and how to find them:

External IDs table
ID type	Descriptions	Example	Location
External cookie	First-party cookie identifier for a single visit or visitor to your site. It is set server-side on your own domain. Structure is based on your own logic, such as browser and device combinations.	Session ID Visit ID Unique visitor ID Client ID Cookie value	Depends on how you assign unique identifiers to user cookies through server-side programming.
Your own identifier	Identifier that you generate to manage the engagement, performance, and orders for customers.	User ID Membership ID Loyalty ID Subscription ID	Usually stored in your CRM system and updated when a user signs logs in on your site.

Was this page helpful?

Conversion event types

Name in API

Name in Tag

Purpose

Usable for

add_payment_info

AddPaymentInfo

Track people who enter payment information, such as a credit card number.

Conversion reporting

add_to_cart

AddToCart

Track people who add items to shopping carts.

Audience creation

Conversion reporting

add_to_wishlist

AddToWishList

Track people who add a viewed item to a wish list.

Conversion reporting

app_install

N/A

Track people who install your app for the first time, or the first time an app starts on a device.

Audience creation

Conversion reporting

app_open

N/A

Track people each time they open your app after they access it for the first time.

Audience creation

Conversion reporting

checkout

Checkout

Track people who complete transactions.

Audience creation

Conversion reporting

contact

Contact

Track people who contact you through phone, email, chat or other methods.

Audience creation

customize_product

CustomizeProduct

Track people who customize a product using a tool on your website or app.

Audience creation

find_location

FindLocation

Track people who find your business location through web or app.

Audience creation

initiate_checkout

InitiateCheckout

Track people who start the process of checking out an item for purchase but do not complete it.

Conversion reporting

lead

Lead

Track people who show interest in your product or service.

Audience creation

Conversion reporting

page_visit

PageVisit

Track people who view primary pages, such as product pages and article pages.

Audience creation

Conversion reporting

schedule

Schedule

Track people who schedule an appointment at one of your business locations.

Audience creation

search

Search

Track people who search for products or services you offer.

Audience creation

Conversion reporting

signup

SignUp

Track people who sign up for your product or service.

Audience creation

Conversion reporting

start_trial

StartTrial

Track people who start a free trial of a product or service.

Audience creation

submit_application

SubmitApplication

Track people who complete and submit an application for a product, service, or program.

Audience creation

subscribe

Subscribe

Track people who subscribe to receive information and updates related to products or services.

Conversion reporting

view_category

ViewCategory

Track people who view category pages.

Audience creation

Conversion reporting

view_content

ViewContent

Track people who view site content.

Conversion reporting

watch_video

WatchVideo

Track people who watch videos.

Audience creation

Conversion reporting

Custom event that you name

Track an event that does not conform to any of the Pinterest-defined types.

You give this event a unique name that is meaningful to your business.

Create the name with any upper- or lower-case letters (treated as case insensitive), numerals 0 through 9, underscores

_

, and hyphens

-

Limit the name to 100 characters.

Example:

TookSurvey

Make sure to map any custom event to a Pinterest standard event.

Audience creation

Conversion API prerequisites
What you need	Why you need it	How to get it
Pinterest advertiser account	The Conversions API endpoint requires a unique identifier associated with the ad account that is sending events.	Learn how to create an advertiser account.
Conversion token if you only want to access the Conversions API endpoint or OAuth token with at least `ads:write` scopes if you want to access other API endpoints	You need a token to authenticate against the Conversions API endpoint.	For conversion token: See Generate a conversion token. For OAuth token: Set up your OAuth token and learn about scopes.
Pinterest advertiser account	For you to interact with any tools/endpoints related to campaigns, ad groups, and ads, your OAuth token must be related to a Pinterest advertiser ID.	Learn how to create an advertiser account.

Conversion API prerequisites

What you need

Why you need it

How to get it

Pinterest advertiser account

The Conversions API endpoint requires a unique identifier associated with the ad account that is sending events.

Learn how to create an advertiser account.

Conversion token if you only want to access the Conversions API endpoint
or
OAuth token with at least

ads:write

scopes if you want to access other API endpoints

You need a token to authenticate against the Conversions API endpoint.

For conversion token:
See Generate a conversion token.

For OAuth token:
Set up your OAuth token and learn about scopes.

Pinterest advertiser account

For you to interact with any tools/endpoints related to campaigns, ad groups, and ads, your OAuth token must be related to a Pinterest advertiser ID.

Learn how to create an advertiser account.

Server event parameters

Parameter

Recommended for these platforms

Recommended for or optional for events?

Formatting guidelines and examples

action_source

string
Required

The platform from which the event was ingested into the API.

This is different from the

device_type

parameter, which indicates the actual device on which the event occurred. See Format app information.

All platforms

Recommended for all events.

Use any of these enum values:

app_android
app_ios
web
offline

event_id

string
Required

Unique identifier for event, used also for deduplicating events ingested through the conversion API and Pinterest tracking.

All platforms

Recommended for all events.

Any unique string associated with the purchase, such as an order number or transaction ID.

See best practices for using event IDs.

event_name

string
Required

All platforms

Recommended for all events.

Use any of these enum values:

add_payment_info
add_to_cart
add_to_wishlist
app_install
app_open
checkout
contact
customize_product
find_location
initiate_checkout
lead
page_visit
schedule
search
signup
start_trial
submit_application
subscribe
view_category
view_content
watch_video

You also can define an event that does not conform to any of the Pinterest-defined types.

You can name it with any upper- or lower-case letters (treated as case insensitive), numerals 0 through 9, underscores

_

, and hyphens

-

Limit the name to 100 characters.

Example:

TookSurvey

You can custom-define up to 15 types of events for every advertiser ID.

event_source_url

string, nullable
Optional

Web

Recommended for all events.

Include the full URL path for the conversion event.

https://www.myshop.org/

For Pinterest click events, include

&epik

query string, a unique click identifier, in the URL.

The epik (External Pinterest ID Key) value is a unique identifier that Pinterest uses to help track users across devices and sessions. It is typically passed as a query parameter in your URLs, for example, after a click on a Pinterest ad.

https://www.myshop.org/checkout?epik=123abc456def789ghi

event_time

integer
Required

All platforms

Recommended for all events.

Enter as Unix timestamp in seconds.

opt_out

boolean
Optional

Whether the user has opted out of web or offline conversion events.

Whether the user has enabled Limit Ad Tracking on iOS, or opted out of Ads Personalization on Android for app platform events.

Recommended for all events.

Boolean:

true
false

partner_name

string, nullable
Optional

Third-party responsible for sending the event to API on behalf of the advertiser.

All platforms

Recommended for all events.

Syntax:

ss-companyname

For direct integration, use value

direct

User data parameters

Parameter

Recommended for these platforms

Recommended for or optional for events?

Formatting guidelines and examples

external_id

Unique string that you use to identify a customer, such as user ID or loyalty id.

Learn more about using external IDs.

All platforms

Recommended for all events.

SHA-256 hash


6a7a73766627eb611720883d5a11cc62b5bfee237b00a6658d78c50032ec4aee

click_id

Cookie generated when a user clicks an ad.

Web

App

add_to_cart
checkout
lead
page_visit
search
signup
view_category
watch_video

Use the

_epik

cookie instead of the

&epik=

query parameter. While both are accepted, passing

_epik

cookie values is necessary when a URL parameter is missing or removed and ensures greater coverage.


dj0yJnU9b2JDcFFHekV4SHJNcmVrbFBkUEdqakh0akdUT1VjVVUmcD0y Jm49cnNBQ3F2Q2dOVDBXWWhkWklrUGxBUSZ0PUFBQUFBR1BaY3Bv

client_ip_address

User's IP address

Web

Recommended for all events

Valid IPv4 or IPv6.

No pure zero (

0.0.0.0

) addresses.

216.3.128.12

client_user_agent

User agent string for user's browser.

Web

App

Recommended for all events.

Include at least two of each of these information categories:

OSfamily
browserfamily
devicefamily

Do not send "Other" or

null

Do not send user agents produced by bot.


Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36 Edge/12.246

country

User's country.

All platforms

Recommended for all events.

SHA-256 hash of two-character ISO-3166 country code in lower case and UTF format.

ct

User's city.

All platforms

Recommended for all events.

SHA-256 hash in lowercase, and without spaces or punctuation.

db

User's date of birth.

All platforms

Recommended for all events.

SHA-256 hash of YYYYMMDD.

em

User's email address.

All platforms

Recommended for all events.

SHA-256 hash of email addresses in lower case.

ge

User's gender.

All platforms

Recommended for all events.

SHA-256 hash:

f
(female)
m
(male)
n
(non-binary)

ln

User's last name.

All platforms

Recommended for all events.

SHA-256 hash of last name in lower case.

ph

User's phone number.

All platforms

Recommended for all events.

SHA-256 hash of phone numbers.

Only digits with country code, area code, and number. Remove symbols, letters, spaces, and leading zeros.

st

User's state.

All platforms

Recommended for all events.

SHA-256 hash of two-letter code in lower case.

zp

User's zip code.

All platforms

Recommended for all events.

SHA-256 hash of zip code.

Only digits.

hashed_maids

User's Google Advertising IDs (GAIDs)
or
Apple's Identifier for Advertisers (IDFAs)

App

Recommended for all events.

SHA-256 hash\

0192518eb84137ccfe82c8b6322d29631dae7e28ed9d0f6dd5f245d73a58c5f1

partner_id

Unique identifier for user information, such as RampID, only used by integration partners.

All platforms

Optional for all events.

Use only if you are a Pinterest integration partner.

App data parameters

Parameter

Recommended for these platforms

Recommended for or optional for events?

Formatting guidelines and examples

app_id

App store app ID.

App

Optional for all events.

See best practices for strings.

app_name

App store app name.

App

Optional for all events.

See best practices for strings.

app_version

App store app version.

App

Optional for all events.

See best practices for strings.

device_brand

Brand name of user'mobile device.

App

Optional for all events.

See best practices for strings.

device_carrier

Carrier for user'mobile device.

App

Optional for all events.

See best practices for strings.

device_model

Model name for user'mobile device.

App

Optional for all events.

See best practices for strings.

device_type

Type of user's device on which the event occurred.

App

Optional for all events.

This is a free-form string. Consider using values that best describe the device, such as

"desktop web"

"mobile web"

, or

"iPhone app"

"Android app"

(to indicate the native Pinterest mobile app).

Note that you can provide additional specific information about the device by using other parameters such as

app_name

app_version

device_brand

device_carrier

device_model

, and

os_version

See best practices for strings.

This parameter is different from

action_source

, which indicates the platform from which the event is being ingested. See Format server event parameters.

language

Language set on user'mobile device.

App

Optional for all events.

Two-character ISO-639-1 language code in lower case and UTF format.

os_version

Operating system version number for user'mobile device.

App

Optional for all events.

See best practices for strings.

wifi

Whether the event occurred when the user device was connected to a wireless network.

Optional for all events.

Boolean:

true
false

Product event parameters

Parameter

Recommended for these platforms

Recommended for or optional for events?

Formatting guidelines and examples

custom_data.currency

The type of currency used in a purchase event.

All platforms

Recommended for:

add_payment_info
add_to_cart
add_to_wishlist
checkout
initiate_checkout
search
subscribe
view_content
(if the user is on a product page)

Optional for all other events.

ISO-4217 currency code.

If you do not pass the currency with the value, we use the currency that the advertiser set when creating an account.

custom_data.value

Total monetary value for purchased items.

Use pre-tax, pre-shipping total.

All platforms

Recommended for:

add_payment_info
add_to_wishlist
(if the user is on a product page)
custom
checkout
initiate_checkout
search
subscribe
view_content
(if the user is on a product page)

Optional for all other events.

Accepted as a string in the request and parsed into a double.

For example, with two items in a checkout event, the value should be the total price.

Always send currency when sending value.

Should not contain unusually high values or contain invalid values such as negative number or zero.

custom.data.content_ids

Array of product IDs related to the event.

Each listed ID is listed in the

custom.data.contents

array of objects.

All platforms

Recommended for:

add_payment_info
add_to_cart
add_to_wishlist
checkout
custom
initiate_checkout
page_visit
search
view_content
(if the user is on a product page)

Optional for all other events.

See best practices for strings.

custom.data.content_name

Name of the page or product associated with the event

All platforms

Recommended for:

add_payment_info
add_to_cart
add_to_wishlist
custom
initiate_checkout
page_visit
view_content
(if the user is on a product page)

Optional for all other events.

See best practices for strings.

custom.data.content_category

Type of merchandise.

All platforms

Recommended for:

add_to_cart
checkout
custom

Optional for all other events.

See best practices for strings.

custom.data.content_brand

Brand of merchandise.

All platforms

Recommended for:

add_to_cart
checkout
custom

Optional for all other events.

See best practices for strings.

custom_data.num_items

Total number of products involved, for example, products purchased in a checkout event.

All platforms

Recommended for:

add_payment_info
checkout
custom
intiate_checkout
search

Optional for all other events.

See best practices for strings.

custom_data.order_id

Identifier for the order in a purchase-related event.

All platforms

Recommended for:

add_to_cart
checkout

Optional for all other events.

See best practices for strings.

custom_data.search_string

String entered in a search event.

All platforms

Recommended for:

search

Optional for all other events.

See best practices for strings.

custom_data.opt_out_type

Opt-out type for privacy.

If user has opted out of tracking for web conversion events, this parameter indicates whether the user has enabled Limited Ads Tracking (if

action_source

is set to

app_ios

) or opted out of Ads Personalization (if

action_source

is set to

app_android

Learn about limited data processing.

All platforms

Optional for all events.

The only accepted value is

ldp

np

Third-party partner sending the event to the API on behalf of the advertiser.

Only send this field if Pinterest has worked directly with you to define a value for partner_name.

All platforms

Recommended for all events.

See best practices for strings.

custom_data.contents.item_brand

Brand of an individual merchandise item.

All platforms

Recommended for:

add_to_cart
add_to_wishlist
checkout
custom
page_visit
search
view_content
(if the user is on a product page)

Optional for all other events.

See best practices for strings.

custom_data.contents.item_category

Product category of an individual merchandise item.

All platforms

Recommended for:

add_to_cart
add_payment_info
add_to_wishlist
checkout
custom
initiate_checkout
page_visit
search
view_content
(if the user is on a product page)

Optional for all other events.

See best practices for strings.

custom_data.contents.item_name

Product name of an individual merchandise item.

All platforms

Recommended for:

add_to_cart
add_payment_info
add_to_wishlist
checkout
custom
initiate_checkout
page_visit
search
view_content
(if the user is on a product page)

Optional for all other events.

See best practices for strings.

custom_data.contents.item_price

Price of an individual merchandise item (single quantity).

All platforms

Recommended for:

add_to_cart
add_payment_info
add_to_wishlist
checkout
custom
initiate_checkout
page_visit
search
view_content
(if the user is on a product page)

Optional for all other events.

See best practices for strings.

custom_data.contents.quantity

Quantity of individual merchandise item selected by user.

All platforms

Recommended for:

add_payment_info
checkout
custom
initiate_checkout
search
view_content
(if the user is on a product page)

Optional for all other events.

See best practices for strings.

custom_data.contents.id

Product ID of an individual merchandise item.

All platforms

Recommended for:

add_to_cart
add_to_wishlist
add_payment_info
checkout
custom
initiate_checkout
page_visit
search
view_content
(if the user is on a product page)

Optional for all other events.

See best practices for strings.

curl --request POST \
  --url 'https://api.pinterest.com/v5/ad_accounts/549768257474/events' \
  --header 'Authorization: Bearer pina_ABCD1234...' \
  --header 'Content-Type: application/json' \
  --data '{
  "data": [
    {
      "event_name": "subscription",
      "action_source": "web",
      "event_time": 1769818893,
      "event_id": "evt-subscription-001",
      "event_source_url": "https://www.example.com/subscribe",
      "opt_out": false,
      "user_data": {
        "em": [
          "411e44ce1261728ffd2c0686e44e3fffe413c0e2c5adc498bc7da883d476b9c8"
        ],
        "client_ip_address": "216.3.128.12",
        "client_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
      },
      "custom_data": {
        "currency": "USD",
        "value": "9.99"
      }
    },
    {
      "event_name": "checkout",
      "action_source": "web",
      "event_time": 1769818901,
      "event_id": "evt-checkout-002",
      "event_source_url": "https://www.example.com/checkout/complete",
      "opt_out": false,
      "user_data": {
        "em": [
          "411e44ce1261728ffd2c0686e44e3fffe413c0e2c5adc498bc7da883d476b9c8"
        ],
        "client_ip_address": "216.3.128.12",
        "client_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
      },
      "custom_data": {
        "currency": "USD",
        "value": "66.95",
        "order_id": "order-12345",
        "num_items": 2
      }
    }
  ]
}'

{
  "num_events_received": 2,
  "num_events_processed": 1,
  "events": [
    {
      "status": "failed",
      "error_message": "Invalid event_name: subscription. Use a supported conversion event_name (for example subscribe, checkout).",
      "warning_message": null
    },
    {
      "status": "processed",
      "error_message": null,
      "warning_message": null
    }
  ]
}

External IDs table

ID type

Descriptions

Example

Location

External cookie

First-party cookie identifier for a single visit or visitor to your site. It is set server-side on your own domain. Structure is based on your own logic, such as browser and device combinations.

Session ID
Visit ID
Unique visitor ID
Client ID
Cookie value

Depends on how you assign unique identifiers to user cookies through server-side programming.

Your own identifier

Identifier that you generate to manage the engagement, performance, and orders for customers.

User ID
Membership ID
Loyalty ID
Subscription ID

Usually stored in your CRM system and updated when a user signs logs in on your site.