Pinterest Conversion Export Integration

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Pinterest is a popular social media platform designed for discovering and sharing ideas through images and videos, which are generally called Pins. For various marketing goals, businesses can pay Pinterest Ads to place their promoted Pins in prominent positions where users are most likely to see them.

Using the Pinterest Conversions API, this integration helps advertisers send conversion events directly to Pinterest for campaign optimization, targeting, and conversion reporting for improved conversion visibility. This integration supports the following conversion types:

• Web
• In-App
• Offline conversions

User attributes are exported together for matching purposes, and the export also includes custom attributes (like product attributes).

Prerequisites

• Basic knowledge of Treasure Data
• Basic knowledge of Pinterest Ads Manager
• A Pinterest business account
• An access token for the Pinterest Conversion API. See Generate an access token for Pinterest Conversion API.

Limitations

• The Conversion API has a rate limit of 5000 calls per minute per ad account. See Pinterest API Rate Limits.
• Deduplication of event, when used, is only effective within a 48-hour window.
• The integration supports sending test events to Pinterest but does not limit the number of uploaded events. Treasure Data recommends that you do not send a large number of test events.

Using the TD Console to Create a Connection

In Treasure Data, you must create and configure the data connection before running your query. As part of the data connection, you provide authentication to access the integration.

Create a New Connection

1. Open TD Console.

2. Navigate to Integrations Hub > Catalog.

3. Search for Pinterest Conversion.

4. Select Create Authentication.

   

5. Enter your access token for the Pinterest Conversion Ads Manager.

6. Select Continue.

7. Enter a name for the Authentication, and select Done.

Configure a Query Result for Export

The TD Console supports multiple ways to export data. Here are the steps to export data from the Data Workbench.

1. Navigate to Data Workbench > Queries.
2. Select New Query, and define your query.
3. Select Export Results.
4. Select an existing Pinterest Conversion authentication or create a new one (see Create a New Connection).
5. Configure the exporting parameters, and select Done.

• Export Results Parameters

Define your query to upload conversion events

• Hashing—Fields marked as Yes in the Hashing column below need to be in lowercase, and hashed using Sha256. If they are provided as plain texts, the integration will hash them.

• Array of string—Fields of the type Array of string type accept multiple values in flattened column names. For example, em, em_1, em_2 could form an array of user email strings.

• Array of item objects—Pinterest allows uploading multiple order items which have many attributes such as ID, name, quantity, and price. Here are examples of item object:

  • item_id, item_price,item_quantity
  • item_id_1, item_price_1, item_name_1
  • item_id_2, item_brand_2, item_category_2

Sample queries

Minimum required fields

SELECT
  'add_to_cart' AS event_name
  ,'app_android' AS action_source
  ,now() AS event_time
  ,'801470028' AS event_id
  ,'some_one@mail.com' AS em
FROM
  your_table

Array of strings

SELECT 'add_to_cart' AS event_name  ,'app_android' AS action_source  ,now() AS event_time  ,'59930360' AS event_id    ,'some_one@mail.com' AS em  ,'another_one@gmail.com' AS em_1    ,'or123' AS order_id  ,'cook' AS search_string    ,'item 1' AS item_id_1  ,'10.4' AS item_price_1  ,20 AS item_quantity_1    ,'basket' AS item_name_2  ,'cat ' AS item_category_2  ,'tiny' AS item_brand_2 FROM your_table

Activate a Segment in Audience Studio

You can also send segment data to the target platform by creating an activation in the Audience Studio.

1. Navigate to Audience Studio.
2. Select a parent segment.
3. Open the target segment, right-mouse click, and then select Create Activation.
4. In the Details panel, enter an Activation name and configure the activation according to the previous section on Configuration Parameters.
5. Customize the activation output in the Output Mapping panel.

• Attribute Columns
  • Select Export All Columns to export all columns without making any changes.
  • Select + Add Columns to add specific columns for the export. The Output Column Name pre-populates with the same Source column name. You can update the Output Column Name. Continue to select + Add Columnsto add new columns for your activation output.
• String Builder
  • + Add string to create strings for export. Select from the following values:
    • String: Choose any value; use text to create a custom value.
    • Timestamp: The date and time of the export.
    • Segment Id: The segment ID number.
    • Segment Name: The segment name.
    • Audience Id: The parent segment number.

1. Set a Schedule.

• Select the values to define your schedule and optionally include email notifications.

1. Select Create.

(Optional) Export Integration Using the CLI

The TD Toolbelt can trigger a query result export from the CLI. You need to specify the parameters for the export job with the --result option of the td query command. For more information, refer to Querying and Importing Data to Treasure Data from the Command Line.

Here is an example of the general structure and JSON format of the option:

{    "type": "pinterest_conversion",    "access_token": "pina_AIA2RFAxxx",    "ad_account_id": 549764609761,    "test_event": false,    "skip_invalid_record": true}

CLI Parameters

Example Usage for Sending Real and Test Events

1. Send test conversion events

td --database test_db \
--wait "SELECT event_name, action_source, event_time, event_id, event_source_url, opt_out, partner_name, app_id, app_name, app_version, device_brand, device_carrier, device_type, os_version, wifi, language, em, hashed_maids, client_ip_address, client_user_agent, ph, ge, db, ln, fn, ct, st, zp, country, external_id, click_id, partner_id, currency, value, content_ids, content_name, content_category, content_brand, item_id, item_id_1, item_id_2, item_price, item_price_1, item_price_2, item_name, item_name_1, item_name_2, item_category, item_category_1, item_category_2, item_brand, item_brand_1, item_brand_2, item_quantity, item_quantity_1, item_quantity_2, num_items, order_id, search_string, opt_out_type from test_table" \
--type presto \
--result '{"type":"pinterest_conversion","td_authentication_id": 12345, "access_token":"pina_AIA2RFAWACYNMAQA...", "ad_account_id": 5497xxx, "test_event": true, "skip_invalid_record":true}'

2. Send real events

td --database test_db \
--wait "SELECT event_name, action_source, event_time, event_id, event_source_url, opt_out, partner_name, app_id, app_name, app_version, device_brand, device_carrier, device_type, os_version, wifi, language, em, hashed_maids, client_ip_address, client_user_agent, ph, ge, db, ln, fn, ct, st, zp, country, external_id, click_id, partner_id, currency, value, content_ids, content_name, content_category, content_brand, item_id, item_id_1, item_id_2, item_price, item_price_1, item_price_2, item_name, item_name_1, item_name_2, item_category, item_category_1, item_category_2, item_brand, item_brand_1, item_brand_2, item_quantity, item_quantity_1, item_quantity_2, num_items, order_id, search_string, opt_out_type from test_table" \
--type presto \
--result '{"type":"pinterest_conversion","td_authentication_id": 12345, "access_token":"pina_AIA2RFAWACYNMAQA...", "ad_account_id": 5497xxx, "test_event": false, "skip_invalid_record":true}' 

Other configurations

• The result export can be scheduled to upload data to a target destination periodically.
• All import and export integrations can be added to a TD Workflow. The td>: data operator can be used to export query results to a specified connector. For more information, see the Reference for Treasure Data Operators.

(Reference) Generate an access token for Conversion API

This section provides a high-level overview of how to generate an access token for the Conversion API. Please note that Pinterest may change the detailed steps without prior notice.

1. From the Pinterest Ad Manager, navigate to the main menu, and select Conversions.

2. On the Conversions page, select Set up API, and select Generate new token.

   A never-expired access token ``` pina_xxxxxxx will be generated

See Also

• Pinterest Send Conversion API