Pinterest Conversions API

The Pinterest Conversions API destination is a server-to-server integration with The Pinterest API for Conversions that allows advertisers to send conversions directly to Pinterest without requiring a Pinterest Tag. These conversions map to Pinterest campaigns for conversion reporting to improve conversion visibility. When you pass events to Pinterest, advertisers can use Pinterest’s insights to evaluate an ad’s effectiveness to improve content, targeting, and placement of future ads.

Advertisers can send web, in-app, or offline conversions to Pinterest’s server to server endpoint in real-time. Events received in real time or within an hour of the event occurring are reported as web or app events. Events received outside of this window, as well as delayed batch events are considered as offline events.

The API for Conversions helps Pinterest provide a more comprehensive view of your campaign performance. All advertisers who currently use the Pinterest Tag will benefit from using it in tandem with the API for Conversions.

Benefits of Pinterest Conversions API (Actions)

The Pinterest Conversions API destination provides the following benefits:

  • Fewer settings. Data mapping for actions-based destinations happens during configuration, which eliminates the need for most settings.
  • Clearer mapping of data. Actions-based destinations enable you to define the mapping between the data Segment receives from your source, and the data Segment sends to the Pinterest Conversions API.
  • Prebuilt mappings. Mappings for standard Pinterest Conversions API events, like Add to Cart, are prebuilt with the prescribed parameters and available for customization.
  • Support Deduplication. Deduplication removes duplicates events which improves the accuracy of your conversions
  • Support for page calls. Page calls can be sent to Pinterest as a standard Page View.
  • Support for multi-user arrays. User data nested within arrays, like the User Data array in the Order Completed event, can be sent to Pinterest.
  • Data normalization. Data is normalized before it’s hashed to send to Pinterest Conversions.

Getting started

Before connecting to the Pinterest Conversions destination, you must have a Pinterest account and an Ad Account ID.

To connect the Pinterest Conversions API Destination:

  1. From the Segment web app, navigate to Connections > Catalog.
  2. Search for Pinterest Conversions API in the Destinations Catalog, and select the destination.
  3. Click Configure Pinterest Conversions API.
  4. Select the source that will send data to Pinterest Conversions API and follow the steps to name your destination.
  5. On the Basic Settings page, configure the following fields:
  6. Navigate to the Mappings tab, there are already Prebuilt mapping like Checkout,Search,Add to Cart defined with prescribed parameter . All required ,recommended and optional fields are listed here
  7. If you want to create New Mapping, and select Report Conversions Event ,configure and enable it.
  8. Follow the steps in the Destinations Actions documentation on Customizing mappings.
  9. Enable the destination using the Enable Destination toggle switch and click Save Changes.

Destination Settings

Setting Description
Ad Account ID Required.

Unique identifier of an ad account. This can be found in the Pinterest UI by following the steps mentioned here.

Conversion Token Required.

The conversion token for your Pinterest account. This can be found in the Pinterest UI by following the steps mentioned here.

Available Presets

Pinterest Conversions API has the following presets:

Preset Name Trigger Default Action
View Category Event type = "track" AND event = "Product Category Viewed"
Report Conversion Event
Add to Cart Event type = "track" AND event = "Product Added"
Report Conversion Event
Page Visit Event type = "page"
Report Conversion Event
Checkout Event type = "track" AND event = "Checkout"
Report Conversion Event
Lead Event type = "track" AND event = "Generate Lead"
Report Conversion Event
Watch Video Event type = "track" AND event = "Product Video Watched"
Report Conversion Event
Sign Up Event type = "track" AND event = "Signed Up"
Report Conversion Event
Search Event type = "track" AND event = "Products Searched"
Report Conversion Event

Available Actions

Build your own Mappings. Combine supported triggers with the following Pinterest Conversions API-supported actions:

Mapping limits per destination

Individual destination instances have support a maximum of 50 mappings.

Report Conversion Event

Report events directly to Pinterest. Data shared can power Pinterest solutions that will help evaluate ads effectiveness and improve content, targeting, and placement of future ads.

Report Conversion Event is a Cloud action.

Click to show / hide fields

Field Description
Event Name* Type: STRING

The conversion event type. For custom events, you must use the predefined event name “custom”. Please refer to the possible event types in Pinterest API docs.

Action Source* Type: STRING

The source indicating where the conversion event occurred. This must be app_android, app_ios , web or offline.

Event Timestamp* Type: STRING

Device IDs can be used to add and remove only anonymous users to/from a cohort. However, users with an assigned User ID cannot use Device ID to sync to a cohort.

Event ID* Type: STRING

A unique id string that identifies this event and can be used for deduping between events ingested via both the conversion API and Pinterest tracking.

Event Source URL Type: STRING

URL of the web conversion event.

Opt Out Type: BOOLEAN

When action_source is web or offline, it defines whether the user has opted out of tracking for web conversion events. While when action_source is app_android or app_ios, it defines whether the user has enabled Limit Ad Tracking on their iOS device, or opted out of Ads Personalization on their Android device.

User Data Type: OBJECT

Object containing customer information data. Note, It is required at least one of 1) em, 2) hashed_maids or 3) pair client_ip_address + client_user_agent..

Custom Data Type: OBJECT

Object containing customer information data.

App ID Type: STRING

The app store app ID.

App Name* Type: STRING

Name of the app.

App Version Type: STRING

Version of the app.

Device Brand Type: STRING

Brand of the user device.

Device Carrier Type: STRING

User device’s mobile carrier.

Device Model Type: STRING

Model of the user device.

Device Type Type: STRING

Type of the user device.

OS Version Type: STRING

Version of the device operating system.

Wifi Type: BOOLEAN

Whether the event occurred when the user device was connected to wifi.

Language Type: STRING

Two-character ISO-639-1 language code indicating the user’s language.

By default, all mappings send as web conversions. If you want to send events as mobile or offline conversions, update the Action Source in each mapping to be app_android, app_ios, offline.

FAQ & Troubleshooting

Deduplication with Pinterest Tag

Pinterest cannot know if a conversion reported by the Tag and another reported by the API for Conversions are the same.

Because Pinterest recommends using both the API for Conversions and the Pinterest Tag, deduplication is an essential part of the implementation process. It helps to avoid double-counting of a single event when it’s sent through multiple sources, such as the Pinterest Tag and the Pinterest API for Conversions.

For example, if a user triggers an add to cart event and the tag reports the data using 123 as the event ID. Later, their web server reports the conversion to the API and uses 123 as the event ID. When Pinterest receives the events, Segment looks at the event IDs to confirm they correspond to the same event.

By using deduplication advertisers can report conversions using both the tag and the API without having to worry about over-counting conversions. This will result in more conversions being attributed than either alone, because if the tag doesn’t match an event, but the API does (or vice versa), the event can still be linked.

Advertisers should use deduplication for any events they expect to be reported by multiple sources across the API and the Pinterest Tag.

Conversion Events must meet the following requirements to be considered for deduplication:

  1. The event has non-empty and non-null values for event_id and event_name
  2. The action_source of the event is not offline (for example, events that occurred in the physical world, like in a local store) The action_source parameter is an enum that gives the source of the event – app_android, app_ios, web, or offline.
  3. The duplicate events arrived within 24 hours of the time of receipt of the first unique event.

Segment offers a client-side destination specifically designed for the Pinterest Tag. You can find detailed documentation and further information on how to implement this integration by following this link.

Events fail to send due to no App Name set

App Name is a mandatory field for many of the Pinterest Conversion API destination’s mappings. Segment’s mobile libraries automatically collect and map the App Name to the correct field. However, Segment’s web or server-based libraries do not automatically collect this field, which can cause mappings to fail. Segment recommends adding the App Name to the Segment event, or hardcoding a static string in the mapping as the App Name.

Limited Data Processing

Starting from Jan 1, 2023, Pinterest introduced the Limited Data Processing flag as per California Consumer Privacy Act (CCPA). With this flag set Pinterest will allow advertisers to comply with CCPA.

Advertisers are responsible for complying with user opt-outs, as well as identifying the user’s state of residency when implementing the Limited Data Processing flag.

Keep in mind that the Limited Data Processing flag could impact campaign performance and targeting use cases. Pinterest recommends using the Limited Data Processing flag on a per-user basis for best results.

LDP relies on 3 fields and is enabled only when all 3 combinations are met, if one of them is not met then LDP is disabled / ignored.

Field Name Field Description Required Value for LDP
opt_out_type Opt Out Type based on User’s privacy preference “LDP”
st State of Residence “CA”
country Country of Residence “US”

PII Hashing

Segment creates a SHA-256 hash of the following fields before sending to Pinterest:

  • External ID
  • Mobile Ad Identifier
  • Email
  • Phone
  • Gender
  • Date of Birth
  • Last Name
  • First Name
  • City
  • State
  • Zip Code
  • Country

User Data Parameters

Segment automatically maps User Data fields to their corresponding parameters as expected by the Conversions API before sending to Pinterest Conversions:

User Data Field Conversions API User Data Parameter
External ID external_id
Mobile Ad Id hashed_maids
Client IP Address client_ip_address
Client User Agent client_user_agent
Email em
Phone ph
Gender ge
Date of Birth db
Last Name ln
First Name fn
City ct
State st
Zip Code zp
Country country

Custom Data Parameters

Segment automatically maps Custom Data fields (excluding content_ids, contents, num_items, opt_out_type) to their corresponding parameters as expected by the Conversions API before sending to Pinterest Conversions:

User Data Field Conversions API Custom Data Parameter
Currency currency
Value value
Content IDs content_ids
Contents contents
Number of Items num_items
Order ID order_id
Search String search_string
Opt Out Type opt_out_type

Server Event Parameter Requirements

Pinterest requires the action_source server event parameter for all events sent to the Pinterest Conversions API. This parameter specifies where the conversions occur.

Verify Events in Pinterest Conversions Dashboard

After you start sending events, you should start seeing them in dashboard. You can confirm that Pinterest received them:

  1. Go to the Events Overview.
  2. Click on the Event History to see all the events sent to Pinterest conversions.

Settings

Segment lets you change these destination settings from the Segment app without having to touch any code.

Setting Description
Ad Account ID
(required)
string. Unique identifier of an ad account. This can be found in the Pinterest UI by following the steps mentioned here.
Conversion Token
(required)
password. The conversion token for your Pinterest account. This can be found in the Pinterest UI by following the steps mentioned here.

This page was last modified: 03 Jun 2024



Get started with Segment

Segment is the easiest way to integrate your websites & mobile apps data to over 300 analytics and growth tools.
or
Create free account