Send offline conversion events to Pinterest

Pinterest is a visual discovery engine on which your brand can engage with your customers. Send a list of products that are in your product catalog to Pinterest to enable pins, and then send a list of customers with whom your brand wants to engage.

Send events to Pinterest Ads Manager to help your brand track offline conversions that result from your marketing campaigns and improve return on ad spend (ROAS) and cost per acquisition (CPA) reporting performance within Pinterest Ads Manager.

Only events that occurred within the previous seven days may be sent to Pinterest Ads Manager using the Send conversions endpoint in the Pinterest Ads Manager Conversions API.

Note

Offline conversion events require up to 48 hours for deduplication of events within Pinterest Ads Manager.

Build a query

Use a query to build a combination of data from the Unified Transactions and Customer 360 tables to send offline conversion events to Pinterest Ads Manager.

Review the Conversions API parameters section for detailed information about the columns returned by your query.

A query must return the following parameters: currency, email, timestamp, and value. When value cannot be returned, both price and quantity must be returned.

The query should return the following parameters to improve return on ad spend (ROAS) and cost per acquisition (CPA) reporting performance within Pinterest Ads Manager: currency, extern_id, given_name, surname, and phone.

Important

Amperity adds the following parameters and applies values automatically:

• action_source is automatically set to offline

• event_id is an automatically generated SHA-256 hash of order_id, event_name, and timestamp

• event_name is automatically set to checkout

• partner_name is automatically set to ss-amperity

Order-level events

A query that returns a collection of order-level events for use in Pinterest Ads Manager is similar to:

SELECT
  c360.customer_id AS extern_id
  ,c360.given_name AS given_name
  ,c360.surname AS surname
  ,c360.phone AS phone
  ,c360.email AS email
  ,c360.city AS city
  ,c360.state AS state
  ,c360.postal AS postal
  ,c360.country AS country
  ,c360.birthdate AS birthdate
  ,ut.currency AS currency
  ,ut.order_id AS order_id
  ,ut.order_quantity AS quantity
  ,ut.order_datetime AS timestamp
  ,ut.order_revenue AS price
FROM Unified_Transactions ut
LEFT JOIN Customer_360 c360 ON ut.amperity_id = c360.amperity_id
WHERE ut.order_datetime > (CURRENT_DATE - interval '7' day)

Item-level events

A query that returns a collection of item-level events for use in Pinterest Ads Manager is more complex. Review the tables available in your tenant and review the available parameters in the parameters in the Send conversions to determine which combinations of attributes in your tenant can be mapped to properties in the Send conversions endpoint.

The following example uses the Customer 360, Unified Itemized Transactions, and Unified Transactions tables.

WITH customers AS (
  SELECT
    amperity_id
    ,c360.email AS email
    ,c360.phone AS phone
    ,c360.given_name AS given_name
    ,c360.surname AS surname
    ,c360.city AS city
    ,c360.state AS state
    ,c360.postal AS postal
    ,c360.country AS country
    ,c360.birthdate AS birthdate
    ,c360.customer_id AS extern_id
  FROM Customer_360 c360
  WHERE email IS NOT NULL
  OR phone IS NOT NULL
),

items AS (
  SELECT
    order_id
    ,item_quantity AS quantity
    ,item_revenue AS price
    ,product_id AS item_name
  FROM Unified_Itemized_Transactions
  WHERE is_return IS NULL
  AND is_cancellation IS NULL
  AND item_revenue >= 0
  GROUP BY order_id
),

orders AS (
  SELECT
    ut.amperity_id
    ,ut.order_id
    ,ut.order_datetime AS timestamp
    ,'USD' AS currency
  FROM Unified_Transactions ut
  WHERE ut.amperity_id IS NOT NULL
),

pinterest_events AS (
  SELECT
    ,or.timestamp
    ,c.email
    ,c.phone
    ,c.given_name
    ,c.surname
    ,c.birthdate
    ,c.city
    ,c.state
    ,c.postal
    ,c.country
    ,c.extern_id
    ,or.currency
    ,or.value
    ,it.quantity
  FROM orders or
  JOIN customers c  ON or.amperity_id = c.amperity_id
  LEFT JOIN items it ON or.order_id = it.order_id
)

SELECT *
FROM pinterest_events
ORDER BY timestamp DESC

Add orchestration

An orchestration defines the relationship between query results and a destination, including the destination and the frequency at which an orchestration runs.

What is a dataset ID?

Datasets connect and manage event data from different sources–such as from websites, mobile apps, physical store locations or business chats–from one location.

A dataset ID configured in Pinterest Ads Manager supports sending send events from Amperity.

A dataset ID may need to be configured for the orchestration.

To add an orchestration

1. Open the Activations page, select the Orchestrations tab, and then click the Add orchestration button. This opens the Add orchestration dialog box.

2. From the Object type dropdown, select Query.

3. From the Object dropdown, select the query for which results is sent to Pinterest Ads Manager.

4. From the Destination dropdown, select a destination that is configured for sending data to Pinterest Ads Manager.

5. Verify all settings.

6. Set the workflow to Manual. You can change this to automatic later, after verifying the end-to-end workflow.

7. Click Save.

Run orchestration

Run the orchestration manually to validate that it works.

Important

Amperity requires access to Pinterest Ads Manager. This access may expire or be removed periodically, depending on how OAuth is managed at Pinterest Ads Manager. If Amperity is unable to send data to Pinterest Ads Manager ask your DataGrid Operator to reauthorize access to Pinterest Ads Manager.

To run the orchestration

1. Open the Activations page, select the Orchestrations tab, and then open the    menu for the Pinterest Ads Manager orchestration. Select Run.

2. The Status column for the orchestration updates to say “Waiting to start”, after which the notifications pane updates to include a notification that shows the current status.

3. When the orchestration has run successfully, the status is updated to “Completed”.

Offline events parameters

The following table describes each of the parameters that are required by Pinterest Ads Manager for offline events. Refer to the Send conversions endpoint documentation for more information about parameters, making requests, and ensuring that the shape of the data sent to Pinterest Ads Manager from Amperity matches what Pinterest Ads Manager expects to be in the request.

Important

A query must return columns with the same name as listed in the “Amperity name” column in the following table. Amperity converts column names to match the parameter names required by the Send conversions endpoint automatically, as long as the name of field returned by the query matches the expected name.

The fields are listed alphabetically, but may be returned by a query in any order.

Amperity name	Pinterest parameter	Description
None.	action_source	Automatic The location at which the conversion event occurred. The value for action_source is assigned automatically and is set to offline.
birthdate	db	Optional A birthdate, in YYYYMMDD format. Note db is part of the user_data object in the Send conversions endpoint. Amperity automatically applies SHA-256 hashing to db before sending to Pinterest Ads Manager.
city	ct	Optional A city name, in lowercase with punctuation and spaces removed. Note ct is part of the user_data object in the Send conversions endpoint. Amperity automatically applies SHA-256 hashing to ct before sending to Pinterest Ads Manager.
country	country	Optional A two-character ISO 3166-1 alpha-2 country code, in lowercase. Note country is part of the user_data object in the Send conversions endpoint. Amperity automatically applies SHA-256 hashing to country before sending to Pinterest Ads Manager.
currency	currency	Required Pinterest Ads Manager requires the value for currency to be a three character alphabetic ISO 4217 currency code. For example: “USD”. Use the Currency field in the Unified Transactions table when its values are three character alphabetic ISO 4217 currency codes. Note currency is part of the custom_data object in the Send conversions endpoint.
email	em	Required An email address, in lowercase. Note em is part of the user_data object in the Send conversions endpoint. Amperity automatically applies SHA-256 hashing to em before sending to Pinterest Ads Manager.
None.	event_id	Optional A deterministic idenfier created by Amperity that uniquely identifies an offline event. Note The value for event_id helps Pinterest Ads Manager deduplicate events sent from Amperity using the Conversion API with other events captured by Pinterest tracking. Deduplication occurs within 48 hours of receiving events sent to the Conversions API. When an order ID exists, event_id is generated as SHA256(order_id | event_name | event_time) When an order ID does not exist, event_id is an empty string. Note Amperity automatically applies SHA-256 hashing to event_id before sending to Pinterest Ads Manager.
None.	event_name	Automatic The type of user event. The value for event_name is assigned automatically and is set to checkout. Only checkout event types are supported.
extern_id.	external_id	Required An SHA-256 hashed string that uniquely identifies a user within your customer data. For example: a user ID, a loyalty ID, or a customer ID. Note external_id is part of the user_data object in the Send conversions endpoint. Amperity automatically applies SHA-256 hashing to external_id before sending to Pinterest Ads Manager.
gender	ge	Optional A gender identifier, in lowercase. Must be one of “f”, “m”, or “n” for non-binary gender. Note ge is part of the user_data object in the Send conversions endpoint. Amperity automatically applies SHA-256 hashing to gender.
given_name	fn	Optional A first name, in lowercase. Note fn is part of the user_data object in the Send conversions endpoint. Amperity automatically applies SHA-256 hashing to fn before sending to Pinterest Ads Manager.
Varies.	opt_out	Optional Indicates when a user has opted out of tracking for web conversion events or ad personalization in Pinterest Ads Manager. Note Opt out data is available from data sources that capture when users Disable personalized advertising on iOS or Android mobile devices Configure web browsers to “not track” Opt of web or offline conversion events
None.	opt_out_type	Required when opt_out is “true”. Use opt_out_type for situations where a customer’s opt_out preference is known. When the opt_out parameter is “true” the value of opt_out_type must be “ldp”. When opt_out_type is “ldp” Pinterest Ads Manager enforces limited data processing .
order_id	order_id	Recommended The unique identifier for an order. Pinterest Ads Manager uses order IDs, when available, for deduplicating events. Note When an order_id is available Amperity will: Group offline transaction events by unique order ID Use order_id to build the SHA-256 hash for event_id
order_revenue	value	Required when price and quantity are unavailable. The total price for the offline conversion event, not including tax or shipping costs. You may configure the SQL query to use item-level details to calculate order revenue. Use the Unified Itemized Transactions table and calculate order revenue using Item Price and Item Quantity for all units of items associated with a unique Order ID. Note value is part of the custom_data object in the Send conversions endpoint.
None.	partner_name	Automatic The identifier for the third-party partner responsible for sending events to the Pinterest Ads Manager Conversions AI. The value for partner_name is assigned automatically and is set to ss-amperity.
phone	ph	Recommended. A phone number with only digits, country code, area code, and number. Note ph is part of the user_data object in the Send conversions endpoint. Amperity automatically applies SHA-256 hashing to ph before sending to Pinterest Ads Manager.
postal	zp	Optional A postal code with only digits. Note zp is part of the user_data object in the Send conversions endpoint. Amperity automatically applies SHA-256 hashing to zp before sending to Pinterest Ads Manager.
price	Rolled up to value	Optional unless value is not provided. The individual price for each item in the order.
quantity	Rolled up to value	Optional unless value is not provided. The quentity of items in the order.
state	st	Optional A two-letter code for a state or province, in lowercase. Note st is part of the user_data object in the Send conversions endpoint. Amperity automatically applies SHA-256 hashing to st before sending to Pinterest Ads Manager.
surname	ln	Optional A last name, in lowercase. Note ln is part of the user_data object in the Send conversions endpoint. Amperity automatically applies SHA-256 hashing to ln before sending to Pinterest Ads Manager.
timestamp	timestamp	Required An ISO 8601 timestamp for the date and time at which the offline conversion event occurred. For example: “2025-01-12T14:21:56.000Z”. Important All timestamps sent to Pinterest Ads Manager must have occurred within the previous seven days. Events that occurred outside of the seven day window are not sent.

Upload a CSV file

Note

This is an alternate way to upload offline conversion events to Pinterest Ads Manager.

Upload a CSV file that contains offline conversion events to Pinterest Ads Manager, after which Pinterest Ads Manager will match campaigns to these conversions so your brand can review total conversions in Pinterest Ads Manager as they relate to all active campaigns.

Tip

Upload this CSV file at least once a month and send conversion data within 30 days of each conversion occurrence to Pinterest Ads Manager. Keep the size of the CSV file under 5 GB with fewer than 10 million rows.

Caution

This destination is available for sending query results to Pinterest Ads Manager after it is configured by a Datagrid Operator or your Amperity representative.

If this destination cannot be selected for orchestrations ask your Datagrid Operator or Amperity representative to configure a destination for sending query results to Pinterest Ads Manager.

Build a query for CSV file uploads

Use a query to return the fields that align to the customer and event data fields supported by Pinterest Ads Manager for use with offline conversions .

For example:

SELECT
  TO_HEX(SHA256(TO_UTF8(LOWER(TRIM(mc.email))))) AS email
  ,ut.order_datetime AS event_time
  ,'checkout' AS event_type
  ,'offline' AS event_source
  ,ut.order_revenue AS value
  ,ut.order_id AS order_id
  ,ut.order_quantity AS quantity
FROM Merged_Customers mc
INNER JOIN Unified_Transactions ut
ON mc.amperity_id = ut.amperity_id
WHERE mc.email IS NOT NULL

You can download the results of this query directly from the Query Editor in Amperity or you can use an orchestration to send the CSV file to cloud storage or any SFTP site.

Important

Test the connection with Pinterest Ads Manager by using an audience with a very small membership. For example: 10 or 100 members or the minimum audience size recommended by Pinterest Ads Manager. Send the test audience to Pinterest Ads Manager and verify the audience is correct in Pinterest Ads Manager. Make adjustments if necessary. Only send full audiences after validation is complete.