PostHog Pinterest Ads Integration: Conversion Tracking

Send PostHog purchases and leads to Pinterest, match catalog product IDs, and prevent duplicate Pixel events. Test the native destination before enabling it.

Part of Send PostHog conversions to Meta, Google Ads, TikTok and more.

A conversion ticket with the PostHog mark sends two lines toward a masonry grid of product pins under the Pinterest logo. The line tagged SKU-204 reaches the one pin labelled SKU-204, which is lit and outlined in blue; the line tagged id 98731 ends in an empty gap between pins.

PostHog can send purchases, leads, and product events to Pinterest through its native Ads Conversions destination. Start with one confirmed conversion and check its event name, matching identifiers, and — for purchases — order value and product IDs.

Pinterest needs conversion data in a form it can match and interpret. The steps below cover event mappings, matching fields, product IDs, deduplication, and test mode. (+)

Quick answer

Use Pinterest Ads Conversions, PostHog’s native destination. It hashes raw matching values, checks the minimum matching data, offers Test mode, and turns Pinterest’s per-event rejections into PostHog errors. (+) Map a confirmed purchase to checkout with a business ID the Pinterest tag shares, send one controlled request in Test mode, and verify it before adding more events.

The separate Pinterest Conversions API destination is Segment-compatible and maintained by Segment. (+)

The shared prerequisites and differences between platforms are in our overview of PostHog’s ad destinations.

What you need before you start

  • A Pinterest advertiser account and access to configure PostHog destinations.
  • A confirmed purchase or lead event, with matching data and the fields you want to send.
  • Permission to share those fields for advertising, recorded by your consent tool.
  • Access to update the Pinterest tag if it already reports the same conversions.

The examples below use illustrative event and property names. Replace them with the fields your application actually sends.

Step 1: Choose the PostHog events worth sending

Start with one high-value event, usually purchase or lead. Do not configure every event at once. One tested mapping is better than six half-tested mappings.

Map the event that records the completed business action, not a page view that merely suggests the action happened.

For example, use an Order Completed event that fires after payment is confirmed. Reloading a checkout success page should not create another purchase. Define the trigger in your event tracking plan.

The native destination’s selector offers 22 event names, all of which Pinterest’s API accepts. These are useful mappings for ecommerce, SaaS and lead generation: (+ / +)

PostHog business eventPinterest API event
Product Viewedview_content
Product Searchedsearch
Product Added To Cartadd_to_cart
Checkout Startedinitiate_checkout
Order Completedcheckout
Signup Completedsignup
Lead Submitted or Demo Requestedlead
Trial Startedstart_trial
Application Submittedsubmit_application
Newsletter or Updates Subscribedsubscribe
Paid Subscription Startedcheckout, for the payment

An accepted event name is not a promise that you can optimize a campaign for it. Pinterest lists start_trial and submit_application for audience creation, while subscribe supports conversion reporting. Check the event’s use before choosing the campaign goal. (+)

PostHog event names are your internal taxonomy. Pinterest event names are Pinterest’s taxonomy. Map them intentionally.

Use a standard event when it fits. Named custom events must be mapped in Pinterest before they can be used for reporting or optimization. (+)

Pinterest’s Tag event table uses names such as AddToCart and Checkout; the API values are add_to_cart and checkout. The Tag’s JavaScript examples also use lowercase checkout, so do not assume every browser event must be PascalCase. (+)

Step 2: Prepare the matching data

Enter raw matching values in the native destination. It trims and lowercases supported fields, hashes them with SHA-256, and sends arrays of hashes. A value that is already a 64-character hexadecimal SHA-256 hash is kept rather than hashed again. (+ / +)

User data keyDefault input
em{person.properties.email}
ph{person.properties.phone}
external_id{person.id}
client_ip_address{event.properties.$ip}
client_user_agent{event.properties.$raw_user_agent}

Each event needs em, or hashed_maids, or both client_ip_address and client_user_agent. An external ID or click ID by itself does not satisfy that gate. Without a supported combination, the native template skips the event, sends no request, and writes a Skipping event info line; the invocation does not fail. The defaults above and this check are built into the template. (+ / +)

The template does not fully convert every input into Pinterest’s required format. Normalize these values upstream before passing them to the destination:

FieldPrepare this value
Phone (ph)International digits including the country code, without a national leading zero. The template removes common punctuation; it does not add a country code.
Gender (ge)f, m or n, rather than words such as “male”.
Birth date (db)YYYYMMDD, rather than a date with separators.
ZIP (zp)Digits only. The template removes spaces, but leaves a hyphen.

These are the input formats Pinterest requires before hashing. Add optional demographic fields only when you already collect them and have permission to share them. (+)

The default external_id is PostHog’s person ID, lowercased and hashed. If your business IDs are case-sensitive, hash the canonical ID upstream and use that identical hash on both the Tag and API paths. Map the prepared hash instead of the raw ID. (+)

Person properties are read as they exist when PostHog processes the conversion. An identify() call afterwards does not add data to that destination run. Identify before the conversion, or put matching data on the conversion event and map it from there. (+)

For web conversions, client_ip_address and client_user_agent should describe the user, not your server, payment processor, or backend integration.

If you are missing IP address in PostHog person properties, check whether it exists on browser events as $ip. A transformation can copy it to a person profile for later events; follow our visitor-IP guide for the profile and privacy conditions. For a billing webhook, join the permitted visitor IP and browser user agent to the conversion and change these mappings to read those fields. The default $ip can be the sending server’s IP, and the default user-agent field may be absent. (+)

Step 3: Connect the native Pinterest destination

In Pinterest Ads Manager, open Ad Account Overview → Conversions → Conversions API → Set up API. Select Conversion access token, then Generate new token. Copy the token and the ad account ID shown beside it. (+)

  1. In PostHog, open Destinations, click New destination, search for Pinterest Ads Conversions and click + Create.
  2. Enter Ad account ID and Conversion token; the token input is secret.
  3. Keep the destination disabled while you configure the fields. Turn Test mode on before sending any test request.

The native template is alpha and appears as Experimental. Expect possible changes and unexpected issues; PostHog does not offer official customer support for those cases. Verify delivery yourself before sending ordinary traffic. (+ / +)

These inputs apply to the whole native destination; each mapping sets its own Event name and Custom data. For the first purchase mapping, use: (+)

Destination inputSetting
Action sourceweb (the default).
Event IDChange {event.uuid} to {event.properties.order_id}, shared with the Tag.
Event timeKeep {toInt(toUnixTimestamp(event.timestamp))}, the native default in Unix seconds.
Event source URLKeep {event.properties.$current_url} only when it describes the conversion page. For a webhook, map the stored conversion-page URL.
User dataUse the matching fields from Step 2.
Test modeOn for validation; off for real traffic.

The Event time expression only converts the PostHog event’s timestamp. For a payment-provider webhook, capture the PostHog event with the payment’s original time as its timestamp, or Pinterest receives the time your server processed it. (+)

Other Action source values are app_android, app_ios and offline. Choose where the action happened. Offline events cannot be deduplicated. (+)

For live ad optimization, send events as close to real time as possible. Pinterest recommends a maximum lag of one hour. (+)

Step 4: Configure one mapping and its filters

A new native destination includes 11 mappings, including Page viewed → page_visit. Remove the ones you will not send. Open Order completed and change its source-event filter to your confirmed purchase event; its Pinterest Event name is checkout. (+)

Use Global filters for rules that apply before every mapping, and the mapping’s filter for the specific business event. Turn on Filter out internal and test users after configuring your internal-user filters. (+ / +)

Require an event property such as ads_consent = true and environment = production. These are illustrative fields: your application must supply them from the actual permission and environment state. A missing consent value should not pass. Also require the property your Event ID reads, such as order_id, to be set: without it, Pinterest cannot deduplicate the event against the tag.

Browser opt-out stops browser SDK capture, but a webhook or backend SDK has its own capture path. Gate server-side events with the permission your consent tool records; a browser choice does not automatically filter them out of this destination. (+ / +)

Later events can use additional mappings in the same destination. Because Event ID is shared across mappings, first put each action’s stable business ID in a common event property and map that field. Use separate destinations when credentials, permission rules or ownership differ.

Step 5: Share event IDs with the Pinterest tag

If you already use the Pinterest tag, keep it alongside the API for additional coverage. When both report the same conversion, send the corresponding event type and the same event_id. Pinterest keeps the first event and removes duplicates within 48 hours. (+)

The native default {event.uuid} is PostHog’s event ID; it is not automatically passed to the Tag. Use one business ID that both senders know, and keep it when either path retries. (+)

Good event IDs:

  • Order ID for purchases.
  • Transaction ID from your payment provider.
  • Booking ID for appointments.
  • Lead ID for lead submissions.
  • Subscription ID for subscription starts.

Weak event IDs:

  • A random value generated separately in browser and server contexts.
  • A timestamp by itself.
  • A user ID by itself.
  • A session ID by itself.

For leads, generate one lead ID when the lead is created and use that same ID everywhere.

If your Pinterest tag currently fires a checkout event on the confirmation page, update the tag event data to include the same event_id that PostHog sends through the destination. (+)

Give separate purchases separate IDs, including repeat purchases from the same customer. A subscription ID suits the initial subscription action; each renewal payment needs its own transaction ID. Check any commerce-platform Pinterest integration too: it may be a third sender.

Step 6: Map product IDs and value

Use custom_data.contents for products, content_ids for their IDs, num_items for total quantity, and order_id for the order. Each contents item can contain id, item_price as a string, integer quantity, item_name, item_brand and item_category. The item price is the original unit price before discount. (+)

The browser Tag’s line_items and order_quantity are different fields. Do not put them in the API product mapping. (+)

If your store sends internal database IDs to PostHog but Pinterest’s catalog uses SKUs, map the SKU instead. The native Order completed mapping already takes x.sku and falls back to x.product_id for both contents[].id and content_ids. Verify that this choice matches your catalog. The value fallback checks value, then revenue, then price. (+)

Map value to the actual order total before tax and shipping, sent as a string, and currency to the order’s ISO-4217 code. If currency is absent, Pinterest uses the ad account’s currency. Replace the fallback with your confirmed order-total field if price is a unit price. Leave value unmapped for events without monetary value rather than inserting zero. (+)

This illustrative Custom data output describes two units of one product. IDs, amounts and product details are invented. The destination nests these fields under custom_data.

{
  "value": "89.90",
  "currency": "EUR",
  "order_id": "order-example",
  "num_items": 2,
  "content_ids": [
    "SKU-204"
  ],
  "contents": [
    {
      "id": "SKU-204",
      "item_price": "44.95",
      "quantity": 2,
      "item_name": "Example product",
      "item_brand": "Example brand",
      "item_category": "Example category"
    }
  ]
}

In PostHog’s Custom data, keep the native contents, content_ids and num_items mappings if your event has the expected products array. Map value to your validated total, currency to {event.properties.currency}, and order_id to {event.properties.order_id}. Check quantities and discounts against the order record.

Step 7: Preserve the Pinterest click ID

With campaign capture enabled, posthog-js captures the landing URL’s epik parameter. It does not read the _epik cookie. Personal-data masking changes captured epik to the literal <masked>, which is not a usable click ID. (+)

The native click_id default is {person.properties.epik ?? person.properties.$initial_epik}: the person’s latest Pinterest click, then the first recorded one. A later visit without a click ID clears the latest value, so a person who clicked ad A and later ad B can end up sending A. (+) Those person properties need an event that processes a person profile; do not assume they exist for an anonymous conversion. (+ / +)

Pinterest accepts the URL parameter or cookie as click_id and prefers the cookie when available. (+) To carry it through checkout:

  1. Preserve epik on the landing URL. After advertising consent, read the _epik entry from document.cookie when present, otherwise use the landing epik value.
  2. Save that value with the checkout or lead record as an event property such as pinterest_click_id, and include it on the PostHog conversion. For a separate checkout domain or billing webhook, transfer it with the order or join it on the backend.
  3. Change User data → click_id to {event.properties.pinterest_click_id}. Send the permitted value as a plain string, without hashing. Omit it when unavailable, masked, or no longer permitted.

If you only rely on event_source_url, you may lose the click ID when the user converts later, especially after checkout redirects or multi-step funnels.

Keep the conversion page’s real URL in event_source_url; do not replace it with a landing URL to recover a lost parameter. Use our ad URL-parameters guide for capture and storage choices. Apply the same permission and masking policy to custom cookie capture.

Step 8: Send a controlled test

Turn Test mode on. It appends ?test=true; Pinterest validates the events and shows them under Conversions → Test events, without recording them for reporting or optimization. The native destination sends one event per request. (+ / +)

PostHog’s built-in tester can send real requests. Clicking Test is not a substitute for switching on Pinterest Test mode. (+)

  1. Use a narrow filter that admits only your controlled test and permitted matching data. Keep other mappings out of the test.
  2. Inspect the source event and resolved destination inputs: business ID, original time, consent, visitor context, value, currency and products.
  3. Send the test through the destination tester, or enable the destination with that narrow filter and trigger the source event.
  4. Open Pinterest Ads Manager → Conversions → Test events, then read PostHog’s logs for skips, errors and warnings.

Debug logging is separate: it exposes configuration or execution details and does not put requests into Pinterest’s test environment. The Segment-compatible destination’s Debug Mode only adds logging. (+)

How to verify the setup

HTTP 200 can contain an event with status: failed. Read status, error_message and warning_message; the native destination raises a PostHog error beginning Pinterest rejected the event: for a rejection and logs accepted events’ warnings. (+ / +)

Check three separate outcomes:

  • Delivered: the test appears in Pinterest Test events and the API reports processed. A PostHog invocation that only logged Skipping event did not deliver anything.
  • Matching coverage: check Conversions Health in Ads Manager and Pinterest’s event-quality diagnostics for matching fields, event IDs and deduplication. Field coverage is not proof that an individual conversion matched a person.
  • Attributed: after release, check campaign conversion reporting in Ads Manager. Attribution depends on the person’s ad interaction and your reporting window; an accepted event need not receive ad credit.

Pinterest’s event-quality diagnostics expose matching and deduplication coverage; campaign reporting uses a selected conversion window. (+ / +)

Before admitting ordinary traffic, use Test mode to test a missing matching combination, denied advertising consent and a purchase without its order ID. Expect a logged skip for the first and no destination send for the other two. Then turn Test mode off, restore the production and internal-user filters, and make a controlled real purchase. Send the same business ID through the Tag and API; keep that ID if you retry the event.

In Test events, the request should show the right event name, timestamp, value, currency, order ID, user data coverage and product data. After release, verify deduplication in production reporting: check that each real purchase counts once. Compare the resolved payload with the order record for fields the report does not expose.

Ad blockers, privacy extensions, internal traffic filters, and staging domains can hide whether the production setup works. Test in a controlled but realistic path.

For discrepancies between purchases and platform counts, use our conversion tracking audit; for missing identity or source-event data, use our PostHog audit.

Already using the Segment-compatible destination?

Look at the settings, even if you renamed the destination. The native version has Test mode, em/ph user-data keys and an Experimental banner. The Segment-compatible version has Debug Mode and an Opt Out field on each mapping. PostHog labels it stable in the catalogue, but its behavior differs from the native template. (+)

Every Segment mapping defaults Opt Out to on, and the action sends that value on every event. For web events, opt_out: true tells Pinterest the user opted out of tracking. (+ / +)

Move to the native destination, or at least map Opt Out to a real consent signal. Do not switch it off for everyone just to make events pass. Treat Opt Out as consent data, and investigate delivery failures and missing ad credit separately.

With its default email mapping, the Segment version fails when neither the event nor the person has an email, and sends a missing monetary value as the string "null" or "undefined" instead of leaving it out. (+ / +)

Configure the native replacement with Test mode on and a narrow test filter. Once it passes, disable the old destination before enabling ordinary traffic through the new one. Preserve the IDs already shared with the Tag.

If a conversion is missing or counted twice

SymptomCheck next
No Pinterest event and no PostHog errorLook for Skipping event; verify the matching combination and the consent/event filters.
HTTP 200 but a PostHog errorRead Pinterest’s per-event rejection message; HTTP success does not mean the event was accepted.
One purchase appears twiceCompare the Tag and API event type and event_id; check for an old destination or commerce integration still sending.
Products are missing or unfamiliarCheck contents, content_ids and the SKU against the catalog.
Tests arrive, but production counts do notConfirm Test mode is off, the destination is enabled, and production filters admit the intended event.
Accepted events have no ad creditCheck matching diagnostics and the reporting window separately from delivery.

Frequently asked questions

Do I need to hash email addresses first?

No, not with the native destination. Map the raw email to em; it trims, lowercases and SHA-256 hashes it into an array. It recognizes an existing 64-character hexadecimal SHA-256 hash. (+)

Can I send a conversion without an email address?

Yes, with a mobile advertising ID in hashed_maids, or both the visitor’s client_ip_address and client_user_agent. Phone, external ID and click ID alone do not meet the requirement. (+)

Should I send line_items through the API?

No. Use custom_data.contents, content_ids and num_items. line_items and order_quantity belong to the browser Tag. (+ / +)

Which Pinterest event name represents a purchase?

Use checkout, triggered by the confirmed purchase. initiate_checkout represents starting checkout. For trials and applications, the native destination also offers start_trial and submit_application; check their supported uses before selecting a campaign goal. (+)

Can I leave Event ID as event.uuid when I use the Tag?

Only if you explicitly pass that same UUID to the corresponding Tag event. The native default is not shared automatically. An order or transaction ID available to both senders is usually simpler. (+ / +)

Is Test mode the same as debug logging?

No. Native Test mode sends ?test=true, so Pinterest validates events without recording them for reporting or optimization. Logging only exposes execution details; it does not change the API request into a test. (+ / +)

Can Pinterest reject an event inside HTTP 200?

Yes. Check each event’s status, error_message and warning_message. The native destination raises an error when Pinterest returns status: failed. (+ / +)

Do I still need the Pinterest tag?

No, the API can receive conversions without it. Using both can add coverage; when both report the same action, share its event ID and corresponding event type so Pinterest can deduplicate it. (+ / +)

About the author

Moein Heshmati

Moein Heshmati

Moein Heshmati leads data systems and engineering at 99Ways, specializing in analytics engineering, tracking, and experimentation systems. He writes about data quality, measurement, technical implementation, and reliable experimentation.

More articles

Where is growth getting stuck?

Book a free 45-minute call with Iman. Show him your site and, if you can, your analytics. You’ll leave knowing what to fix or test first.

Book a free call