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.

How tracking tools map to ingestion sources

Because your ads engage your customers in different ways, Pinterest provides conversion tracking tools for different platforms and ingestion sources:

Conversion platforms
Platform	Ingestion source
App	Conversions API
App	Mobile measurement partner (MMP) integrations. See a list of MMPs in this help article on third-party integrations.
Offline	Conversion API
Offline	Upload
Web	Conversions API (With Pinterest Tag or independently)
Web	Pinterest Tag (With Conversions API or independently)

Use this guide to track conversion events using the Conversions API.

Understand conversion events

See the following table to understand what happens in each event. The event name appear as they are formatted in API requests.

Conversion events
Event	Purpose
`add_to_cart`	Track people who add items to shopping carts.
`add_to_wishlist`	Track people who add items to wishlists.
`add_payment_info`	Track people who save their billing information.
`app_install`	Track people who install your app for the first time or the first time an app starts on a device.
`app_open`	Track people each time they open your app after they access it for the first time.
`checkout`	Track people who complete transactions.
`contact`	Track people who contact you through phone, email, chat or other methods.
`customize_product`	Track people who customize a product using a tool on your website or app.
`find_location`	Track people who find your business location through web or app.
`initiate_checkout`	Track people who start the checkout process but do not complete it.
`lead`	Track people who show an interest in your product or service.
`page_visit`	Track people who view primary pages, such as product pages and article pages.
`schedule`	Track people who schedule an appointment at one of your business locations.
`search`	Track people who search for products or services you offer.
`signup`	Track people who sign up for your product or service.
`start_trial`	Track people who start a free trial of a product or service.
`subscribe`	Track people who start a paid subscription for a product or service.
`submit_application`	Track people who complete and submit an application for a product, service or program.
`view_category`	Track people who view category pages.
`view_content`	Track people who view a page for a product or service.
`watch_video`	Track people who watch a video related to a product or service.
Custom event that you name	Pass your own defined event name for an event that does not conform to any other Pinterest type. See Format server event parameters.

Send conversion events to the API

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

Prerequisites

Make sure to do the following before you send the request:

Set up a business account, also known as an advertiser account.
Generate a token.
- If you plan to use the Pinterest API for multiple operations in addition to sending conversion events, create a token using the OAuth flow.
- Install Pinterest Tag if you want to use it with the Conversions API.
- If you plan to only use the Conversion API and no other endpoints, use the following steps to get a conversion token:
  1. Go to Ads Manager, and select Ad Account Overview > Conversions > Conversions API > Set up API.
  2. Select Conversion access token, and click Generate new token.
  3. Copy your newly generated token, which is displayed with your ad account ID.

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` The platform where the event occurred.	All platforms	Recommended for all events.	Use any of these enum values: `app_android` `app_ios` `web` `offline`
`event_id` 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`	All platforms	Recommended for all events.	Use any of these enum values: `add_to_cart` `add_payment_info` `add_to_wishlist` `app_install` `initiate_checkout` `checkout` `lead` `page_visit` `search` `signup` `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`	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`	All platforms	Recommended for all events.	Unix timestamp in seconds.
`opt_out` 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` 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.

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'mobile device, such as `iPhone` .	App	Optional for all events.	See best practices for strings.
`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
custom_data
object contains information at the level of the event, such as any money that was spent in the conversion.
The
custom_data.contents
object contains information about specific merchandise items involved in the event.

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.

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 Ad reporting > Conversions > Test events to verify that the test event was sent successfully.

Best practices

To ensure the most , do the following:

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 platforms

Platform

Ingestion source

App

Conversions API

App

Mobile measurement partner (MMP) integrations.

See a list of MMPs in this help article on third-party integrations.

Offline

Conversion API

Offline

Upload

Web

Conversions API

(With Pinterest Tag or independently)

Web

Pinterest Tag

(With Conversions API or independently)

Conversion events

Event

Purpose

add_to_cart

Track people who add items to shopping carts.

add_to_wishlist

Track people who add items to wishlists.

add_payment_info

Track people who save their billing information.

app_install

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

app_open

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

checkout

Track people who complete transactions.

contact

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

customize_product

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

find_location

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

initiate_checkout

Track people who start the checkout process but do not complete it.

lead

Track people who show an interest in your product or service.

page_visit

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

schedule

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

search

Track people who search for products or services you offer.

signup

Track people who sign up for your product or service.

start_trial

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

subscribe

Track people who start a paid subscription for a product or service.

submit_application

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

view_category

Track people who view category pages.

view_content

Track people who view a page for a product or service.

watch_video

Track people who watch a video related to a product or service.

Custom event that you name

Pass your own defined event name for an event that does not conform to any other Pinterest type. See Format server event parameters.

Server event parameters

Parameter

Recommended for these platforms

Recommended for or optional for events?

Formatting guidelines and examples

action_source

The platform where the event occurred.

All platforms

Recommended for all events.

Use any of these enum values:

app_android
app_ios
web
offline

event_id

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

All platforms

Recommended for all events.

Use any of these enum values:

add_to_cart
add_payment_info
add_to_wishlist
app_install
initiate_checkout
checkout
lead
page_visit
search
signup
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

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

All platforms

Recommended for all events.

Unix timestamp in seconds.

opt_out

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

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.

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'mobile device, such as

iPhone

App

Optional for all events.

See best practices for strings.

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.

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.