Pinterest Tag Cloud Mode Integration Beta

Send events to Pinterest Tag using cloud mode.

RudderStack lets you send your event data to Pinterest Conversions API via cloud mode. It sends the event calls in a batch, where each batch can contain upto 1000 events.

warning
  • To use Pinterest Tag’s cloud mode (Pinterest conversions API), contact Pinterest Support to enable the beta access.
  • Pinterest is migrating to API v5 and will deprecate support for API v3 on June 30, 2023. Hence, it is recommended to configure Pinterest Tag as a destination in RudderStack using API v5.

Find the open source code for this destination in the GitHub repository.

Track

The track call allows you to capture the users’ conversion events.

RudderStack maps the track events as specified in the Map Your Events To Pinterest Events connection setting in the dashboard.

A sample track call is shown below:

rudderanalytics.track("Order Completed", {
  event_id: 'eventIDordercompleted',
  order_id: "transactionId",
  value: 35.00,
  revenue: 31.98,
  currency: 'USD',
  products: [{
    product_id: '123454387',
    price: 3.00,
    quantity: 2,
    currency: 'USD',
    position: 1,
    value: 6.00,
  }]
}, {
  traits: {
    email: "alex@example.com",
    lastname: "Keener",
    firstname: "Alex",
    action_source: "offline" // or app_ios / app_android / web
  }
});

Ecommerce conversion tracking

warning
This destination does not strictly adhere to the RudderStack Ecommerce Event Spec.

You can use the Ecommerce Events Specification for sending the events while instrumenting your site with the RudderStack SDK.

The following table mentions how the specific RudderStack track Ecommerce events are mapped to standard Pinterest Conversion Events:

RudderStack eventPinterest event
Order Completedcheckout
Product Addedadd_to_cart
Products Searchedsearch
Product List Filteredsearch

You can also track a custom event that you want to include in the conversion reporting. It will be mapped to a custom Pinterest event, for example:

rudderanalytics.track("custom event")

Standard Pinterest events

Pinterest supports the following nine standard events that can be mapped and tracked for reporting. Any event apart from these is treated as a user-defined event.

  • checkout
  • add_to_cart
  • page_visit
  • signup
  • watch_video
  • lead
  • search
  • view_category
  • custom

Page

The page call lets you record your website’s page views with any additional relevant information about the viewed page.

  • view_category: RudderStack sends this event if both the name and category fields are present. The below sample event contains both the fields and is mapped to the Pinterest’s view_category event:
rudderanalytics.page("Best Seller", "Games", {
  path: "/best-seller/games/1",
  url: "https://www.estore.com/best-seller/games/1",
  title: "Best selling games offered by EStore",
  search: "estore bestseller games",
  referrer: "https://www.google.com/search?q=estore+bestseller",
  testDimension: "true",
})
  • page_visit: RudderStack sends this event if only name field is present and drops any additional properties. The below sample event contains only name and is mapped to the Pinterest’s page_visit event:
rudderanalytics.page("Best Seller", {
  path: "/best-seller/1",
})

Common field mappings

The following table lists the mappings specific for Pinterest Conversion API and are relevant for both the track and page calls:

RudderStack propertyPinterest Tag propertyDescription
message.event
Required
event_nameType of the user event.
context.traits.action_source
properties.action_source
message.channel
Required
action_source
Source indicating the occurence of conversion event.
timestamp
Required
event_timeUnix timestamp (in UTC) in seconds indicating when the user conversion event occurred.
destination.Config.advertiserId
Required
advertiser_idPinterest Advertiser ID.
Integrations Object messageIdevent_idDeduplication key from the dashboard setting or messageId. The dashboard setting is given higher priority.
pageUrlevent_source_urlURL of the web conversion event.
context.device.adTrackingEnabledopt_out
  • When action_source is web or offline, it defines whether the user has opted out of tracking for web conversion events.
  • 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.
destination.Config.appIdapp_idApp store’s App ID.
context.app.name
properties.appName
app_nameName of the app.
context.app.version
properties.appVersion
app_versionVersion of the app.
context.device.manufacturer
properties.manufacturer
device_brandBrand of the user device.
context.device.model
properties.deviceModel
device_modelModel of the user device.
context.device.type
properties.deviceType
device_typeType of the user device.
context.os.versionos_versionVersion of the device’s operating system.
context.localelanguageTwo-character ISO-639-1 language code indicating the user’s language.
properties.partnerNamepartner_nameThird party partner’s name responsible for sending the event to Conversions API on behalf of the advertiser.

The naming convention is ss-<partnername> (in lowercase), for example, ss-shopify.
context.network.carrierdevice_carrierUser device’s mobile carrier.
context.network.wifiwifiWhether the event occurred when the user’s device was connected to Wi-Fi.
info
For mobile sources, if context.device.adTrackingEnabled is true, opt_out will be set as false and vice-versa.

User field mappings

The following table lists the mappings for fields carrying the user information for track and page calls:

RudderStack propertyPinterest Tag propertyData Type
properties.email
context.traits.email
emArray of strings with SHA-256 encoding
properties.phone
context.traits.phone
phArray of strings with SHA-256 encoding
properties.clickIdclick_idString
context.traits.gendergeArray of strings with SHA-256 encoding
context.traits.birthdaydb (YYYYMMDD format)Array of strings with SHA-256 encoding
context.traits.lastNamelnArray of strings with SHA-256 encoding
context.traits.firstNamefnArray of strings with SHA-256 encoding
traits.address.city
context.traits.address.city
ctArray of strings with SHA-256 encoding
traits.address.state
context.traits.address.state
st (Two-letter code)Array of strings with SHA-256 encoding
traits.address.zip
context.traits.address.zip
zpArray of strings with SHA-256 encoding
traits.address.country
context.traits.address.country
country (Two-character ISO-3166 country code)Array of strings with SHA-256 encoding
userId
traits.userId
traits.id
context.traits.userId
context.traits.id
anonymousId
external_idArray of strings with SHA-256 encoding
context.device.advertisingIdhashed_maidsArray of strings with SHA-256 encoding
context.ip
context.requestIP
properties.ip
properties.clientIpAddress
client_ip_addressString
context.userAgentclient_user_agentString
warning

To send the track or page events successfully, you need to include at least one of the following user properties:

  • em
  • hashed_maids
  • Combination of client_ip_address and client_user_agent

Custom field mappings

The following table lists the custom fields mappings for track and page calls:

RudderStack propertyPinterest Tag propertyData Type
properties.currencycurrencyString
properties.value
properties.total
properties.revenue
valueString
properties.product_id
properties.product_sku
properties.products[index].product_id
properties.products[index].product_sku
content_idsArray of strings
properties.price
properties.products[index].price
contents.[index].item_priceArray of strings
properties.quantity
properties.products[index].quantity
contents.[index].quantityInteger
properties.numOfItems (if not present, sum of quantity)num_itemsInteger
properties.order_idorder_idString
properties.querysearch_stringString
properties.contentNamecontent_nameString
properties.contentCategorycontent_categoryString
properties.npnpString
properties.product_id
properties.product_sku
properties.products[index].product_id
properties.products[index].sku
contents.[index].idString
properties.name
properties.products[index].name
contents.[index].item_nameString
properties.category
properties.products.[index].category
contents.[index].item_categoryString
properties.brand
properties.products.[index].brand
contents.[index].item_brandString

Limited Data Processing (LDP)

Starting January 1, 2023, you can use Pinterest’s Limited Data Processing (LDP) flag to limit how Pinterest uses certain data to help the advertisers comply with the users’ privacy settings in accordance with the CCPA (California Consumer Privacy Act).

The following table lists the event properties required to enable Limited Data Processing and their mappings with the Pinterest fields:

RudderStack propertyPinterest propertyData typeDescription
properties.optOutTypecustom_data.opt_out_typeStringSet this field to LDP.
traits.address.state
context.traits.address.state
stArray of strings with SHA-256 encodingShould be a two-letter code
traits.address.country
context.traits.address.country
countryArray of strings with SHA-256 encodingShould be a two-character ISO-3166 country code

FAQ

How can I verify if my events are being sent to Pinterest Conversions API?

Follow these steps to see your events in Pinterest Conversions API:

  1. Login to your Pinterest ads manager account.
  2. Click the Ads tab and select Conversions from the dropdown.
  3. Select API for conversions from the dropdown to see your events.
info
To see API for conversions option in the dropdown, you need to set up your Pinterest dashboard using the Pinterest Tag. For more information on using the Pinterest Tag, refer to the Pinterest Tag Device Mode documentation.

Questions? Contact us by email or on Slack