The Pinterest Conversions API Progam for Online Conversions (Beta)

The Pinterest Conversions API Program offers an easy way to send both conversion event data paired with an envelope. We recommend that you implement the Pinterest CAPI as part of ATS.js through the LiveRamp Console for the most streamlined process, but you can also send events directly to LiveRamp with an HTTP POST request. The adapter then parses the data and sends it to Pinterest.

📘

The Pinterest API for Conversions Adapter is currently in Beta. Talk to a LiveRamp representative to get this feature enabled for you.

🚧

Not Available for Mobile

The CAPI programs only support the sending of online web events and cannot be used for mobile app events.

Requirements

To implement Pinterest Conversions API, you must have the following:

• ATS Configuration ID: To retrieve this ID, log in to Console and go to ATS > Web. Select a configuration, and select the Admin tab. You can find the Configuration ID in the Placement Details area.
  
• Pinterest account ID​​: You must have a Pinterest account ID (Pinterest Ad ID) to use the Conversions API. If you’ve already set up a Pinterest Ads Manager account for your website, we recommend that you use the same account ID for your browser and server events.
• Pinterest access token​​: To use the Conversions API, you need an access token. There are two ways of getting your access token: via Ads Manager (recommended) or using your own app.

Set Up Pinterest CAPI Integration in Console

Before you begin, you must first set up Pinterest integration in Console. Log in to Console and follow the steps to Set Up Pinterest CAPI Integration in Console.​

Store the Identity Envelope With a Timestamp

Once you start calling the ATS envelope API as you normally would with conversions API enabled, you must store the identity envelope in a first-party cookie or local storage. See Store the Envelope With a Timestamp to learn how to do this.

Create the Request

If you have a Pinterest tag / pixel installed on your website, a cookie should appear: \_epik​​​​. This cookie should be passed to the API in the ​user_data​ section. If cookies are not enabled, ​\_epik​ value can be found in the URL by searching for &epik= URL parameter.

Be sure to pass the ATS envelope value (without base64 encoding) in partner_id.

The request command is:

https://pinterest-capi.analytics.rlcdn.com/send-events/{ats-configuration-id}

❗️

While the CAPI endpoint supports collecting and sending batch events, all events must belong to the same user session. Sending large batches (e.g., 1000 events) or combining events across multiple user sessions may result in unexpected behavior.

Example of body:

{ "events": [{ "event_name": <event_name>, "event_time": <date_in_timestamp_format>, "event_id": <event_id>, "event_source_url": <event_source_url>, "user_data": { "partner_id": <envelope_data> }, "custom_data": { "currency": <value>, "value": <value>, "content_ids": [ <value>, <value> ], "content_name": <value>, "content_category": <value>, "content_brand": <value>, "contents": [{ "id": <value>, "item_price": <value>, "quantity": <value> }], "num_items": <value>, "order_id": <value>, "search_string": <value> } }] } 

Examples of the most common use cases with data:

{ "events": [{ "event_name": "checkout", "event_time": 1693216802, "event_id": "1696927774", "event_source_url": "https://www.my-clothing-shop.org/checkout", "partner_name": "ss-liveramp-ats", "user_data": { "partner_id": "Adsogthdhfqzjjfgttojrgkuqignabexgeorndpcgxcxwuehgvtccffzoecbcxwdtfpldast", "click_id": "abcdef1234567890" }, "custom_data": { "currency": "USD", "value": "72.39", "content_ids": [ "red-pinterest-shirt-logo-1", "purple-pinterest-shirt-logo-3" ], "content_name": "pinterest-themed-clothing", "content_category": "shirts", "content_brand": "pinterest-brand", "contents": [{ "id": "red-pinterest-shirt-logo-1", "item_price": "1325.12", "quantity": 5 }], "num_items": 2, "order_id": "my_order_id", "search_string": "sample string" } }] } 

{ "events": [{ "event_name": "page_visit", "event_time": 1713129800, "event_source_url": "https://www.my-clothing-shop.org/product/new-arrivals", "partner_name": "ss-liveramp-ats", "user_data": { "partner_id": "Adsogthdhfqzjjfgttojrgkuqignabexgeorndpcgxcxwuehgvtccffzoecbcxwdtfpldast" }, "custom_data": {} } ] } 

{ "events": [{ "event_name": "add_to_cart", "event_time": 1713129800, "event_source_url": "https://www.my-clothing-shop.org/product/striped-shirt", "partner_name": "ss-liveramp-ats", "user_data": { "partner_id": "Adsogthdhfqzjjfgttojrgkuqignabexgeorndpcgxcxwuehgvtccffzoecbcxwdtfpldast" }, "custom_data": { "content_ids": [ "striped-shirt-456" ], "contents": [ { "id": "striped-shirt-456", "item_price": "29.99", "quantity": 1 } ] } } 

{ "events": [{ "event_name": "page_visit", "event_time": 1713129800, "event_source_url": "https://www.my-clothing-shop.org/signup/success", "partner_name": "ss-liveramp-ats", "user_data": { "partner_id": "Adsogthdhfqzjjfgttojrgkuqignabexgeorndpcgxcxwuehgvtccffzoecbcxwdtfpldast" }, "custom_data": {} } ] } 

See list of supported keys for examples of supported events.

Refresh the ATS Envelopes

You can refresh existing Pinterest-scoped envelopes by calling:

https://api.rlcdn.com/api/identity/v2/envelope/refresh?pid=[placement id]&it=[envelope type]&iv=[envelope value]&ct=[consent type]&cv=[consent string] 

You must populate the it parameter with 19 to correspond to the Pinterest-scoped envelope type. This will reset the envelope expiration to the maximum allowed value.

To learn more about refreshing envelopes, see Implement the ATS Envelope Refresh API.