Pinterest Conversions API
Overview
Section titled “Overview”Signals sends website events from your server to Pinterest, alongside or instead of the Pinterest tag. Because the event does not depend on the browser, it survives ad blockers, cookie restrictions and dropped page loads that would otherwise lose the conversion.
Use this destination to report web conversions such as purchases, checkouts, sign-ups and add-to-carts against your Pinterest campaigns, and to feed the conversion data Pinterest needs for optimization, targeting and reporting.
Pinterest is a planning-led platform, so the gap between someone seeing a Pin and converting is often long. That makes server-side delivery worth more here than on channels with a short click-to-conversion window, because the browser signals Pinterest would otherwise rely on are frequently gone by the time the conversion happens.
Supported sources
Section titled “Supported sources”Prerequisites
Section titled “Prerequisites”Before connecting, make sure you have:
- A Pinterest business account with an advertiser account.
- The Advertiser Account ID of the account you intend to report to.
- A conversion access token generated for that account. See Authentication for where to find both.
- An account with sufficient access to generate the token. Pinterest requires the account behind it to own the advertiser account, or to hold admin, analyst, audience or campaign access to it.
- A Datahash Studio account with the target project selected.
- A website or e-commerce source connected in the same project. Events reach Pinterest through the source, so a connected destination on its own sends nothing.
The Conversions API does not require a Pinterest developer application or an app review. A business account and a token generated in Ads Manager are enough.
Authentication
Section titled “Authentication”In Studio, open Destinations, find Pinterest, and click the Conversion API tile. This connector authenticates with an account ID and a token rather than a sign-in, so there is no consent screen.
- Enter your Advertiser Account ID and Access Token.
- Click Validate Credentials.
- Click Finish.
| Field | What it is | Where to find it |
|---|---|---|
| Advertiser Account ID | The identifier of the Pinterest advertiser account events are reported to. Pinterest also refers to this as the ad account ID. | ads.pinterest.com, then Conversions under the business menu, then Set up API. It is shown alongside the token, and also appears in the Ads Manager URL. |
| Access Token | A credential authorizing Datahash to send events to that advertiser account on your behalf. Pinterest calls it a conversion access token. | The same Set up API screen. Choose Conversion access token, then Generate new token. |
Validate Credentials checks the token against the advertiser account before anything is saved. A token that is simply wrong and a token belonging to an account without sufficient access to the advertiser account both fail here, and they look the same from Studio, so confirm the role as well as the value.
Configuration
Section titled “Configuration”The advertiser account you entered during authentication is where events are written. Signals reports to one advertiser account per connection, so if you report to more than one, create a connection for each.
The events themselves come from the connected source. Event names, the identifiers used for matching and the deduplication key are all set by the source mapping, not here. There is no event mapping on this connector.
Pinterest accepts its own standard event names, such as page_visit, view_category, search, add_to_cart, initiate_checkout, checkout, lead, signup and subscribe. It also accepts custom names, but with a condition worth knowing before you use one: a custom event has to be registered in Ads Manager and mapped to a standard event type first. An unregistered custom event is accepted by the API and then not tracked, so it never appears in reporting and cannot be optimized against.
Manage instance
Section titled “Manage instance”One connection reports to one advertiser account. To add another, open Manage Connections and click Add Instance, then work through the same steps.
To change one, click the instance name and then the edit icon in the top right. Update the fields and click Finish. Clicking Cancel keeps the previous configuration active; updates apply only after you finish.
Deduplication
Section titled “Deduplication”When both the Pinterest tag and the server report the same conversion, Pinterest needs to recognize them as one. It does that on the event ID, so deduplication depends on both paths carrying the same event ID, with the event name present on both.
Where Pinterest differs from Meta is which copy it keeps. Pinterest retains the first event it captured, whichever path that arrived on, rather than preferring the browser event. Pinterest states that duplicates are removed within 48 hours.
If the IDs differ, or the event ID is missing, Pinterest treats them as two conversions and your reported numbers inflate for any event sent on both paths. Nothing is rejected, which is what makes this worth checking rather than waiting for it to surface as an error.
Events with an action source of offline cannot be deduplicated at all. This matters more than it first appears, because Pinterest asks for events within an hour of the conversion and reclassifies later arrivals as offline. A source on a long batch schedule can therefore lose deduplication eligibility even though the event ID was correct throughout.
Check it in Ads Manager under Conversions, then Events overview, then the Deduplication tab for an event. Pinterest reports event ID coverage per event type, and the rate of duplicate events removed per source.
Consent parameters
Section titled “Consent parameters”Pinterest accepts two privacy controls on a conversion event. An opt-out flag, which signals that the person has opted out of tracking or has ad tracking limited on their device. And a limited data processing flag, whose only accepted value is LDP, sent alongside the hashed state and country so Pinterest knows which regime applies.
Limited data processing exists for United States state privacy laws only. It has no effect outside the US, and within the US only for the states covered by Pinterest’s state-specific data terms. Where it is honored, Pinterest acts as a processor for that data rather than for its own purposes.
There is no GDPR consent field. Pinterest accepts no consent string, no consent object and nothing equivalent to Meta’s data processing options for Europe. For EEA and UK traffic the only way to honor a refusal is not to send the event, which means consent has to be enforced at the source rather than passed to the platform.
Pinterest’s advertising terms put the disclosure and consent obligation on the advertiser, and say so specifically for data sent through an API endpoint as well as through the tag. Delivering server-side does not change what you need consent for.
Data & identifiers
Section titled “Data & identifiers”Signals sends the fields your source captures. Send identifiers already hashed where you can. Plain text also works: they are normalized and SHA-256 hashed before they reach Pinterest.
Required
Section titled “Required”| Field | When it is required |
|---|---|
| Event time | Always. UNIX timestamp. Pinterest asks for events within an hour of the conversion and treats later arrivals as offline conversions. |
| Event name | Always. A Pinterest standard event, or a custom name already registered in Ads Manager. Must match the tag event name, or deduplication will not work. |
| Action source | Always. Where the conversion happened. Web, for events from a website or e-commerce source. |
| Event ID | Always. The deduplication key. See Deduplication. |
| One attribution signal | Always. Pinterest accepts the event only if it carries a hashed email, a hashed mobile advertiser ID, or an IP address and user agent together. |
| Currency | Purchase and checkout events. The three-letter currency code. Without it Pinterest falls back to the account default. |
| Value | Purchase and checkout events. |
Recommended
Section titled “Recommended”All of these raise the share of conversions Pinterest can match to a person who saw your Pins.
| Field | Notes |
|---|---|
| IP address and user agent | Pinterest’s highest priority web signals. Sent raw. The user agent has to be a real one, carrying at least two of operating system, browser and device family; a placeholder counts as absent. |
| External ID | Your own identifier for the person: session, visitor, membership or loyalty ID. Pinterest rates it high priority and says it holds its matching value as other signals get restricted. |
| Email address | Pinterest’s strongest identifier on lower-funnel events such as add to cart, checkout, sign-up and lead. |
| Pinterest click ID | Captured when a visitor arrives from a Pinterest ad, as the epik value. Pinterest prefers the first-party cookie the tag writes over the URL parameter, because the parameter is often stripped in transit. |
| Phone number | Useful on lower-funnel events. Pinterest rates it below email and external ID. |
| Order ID | Not an identifier, but Pinterest grades it as event metadata, and it is the natural value to use as the event ID on a purchase. |
| Product ID | Graded as event metadata, and matched against the catalog you uploaded to Pinterest. |
Optional
Section titled “Optional”Further identifiers, all rated low priority by Pinterest: first name, last name, city, state, country, postcode, date of birth and gender. State and country stop being optional if you are sending the limited data processing flag, since Pinterest needs both to apply it.
Further detail about the conversion: order value, product name, category, brand and quantity, number of items, search query, and the page URL the event happened on.
Verify in platform and match quality
Section titled “Verify in platform and match quality”Confirm events are arriving in Ads Manager under Conversions, then Events overview. Select the event to see per-event detail, and the Deduplication tab for event ID coverage and duplicates removed.
Pinterest asks for events within an hour of the conversion so that optimization and attribution can use them. Signals delivers server-side as events arrive from the source, so this is normally satisfied. A source running on a long batch schedule is the case to watch, because a late event is reclassified as offline and stops being eligible for deduplication.
Match quality has a published score. Pinterest calls it Event Quality Score, and it is the equivalent of Meta’s Event Match Quality. Find it under Conversions, then Event Quality. It combines three things: the customer information you send, the event metadata you send, and how cleanly duplicates are being identified across the tag and the API.
The bands are Good, Fair and Needs improvement. Good requires three strong customer identifiers, the applicable event metadata, and an overlap score above 90 percent across all events, which is another way of saying the event ID has to be working. The score is reported as a 14-day average with a one-day toggle, and the two can disagree.
Drill into any parameter to see coverage per event type, the specific issue Pinterest has identified, and a downloadable sample of the affected events. That sample is the fastest route to finding which events are missing an identifier, rather than inferring it from the score.
Best practices
Section titled “Best practices”- Send the same event ID from the tag and the server for any conversion reported on both paths. This is the single thing that prevents double counting, and it is also what lifts the overlap component of the Event Quality Score.
- Capture the Pinterest click ID from the first-party cookie rather than relying on the URL parameter, which is frequently stripped before the page loads.
- Map an external ID. Pinterest rates it a high priority signal and it keeps its value as browser-based signals continue to be restricted.
- Check that IP address and user agent are being captured on web events. They are Pinterest’s highest priority web signals, and a placeholder or missing user agent counts as no signal at all.
- Keep formatting clean at source: lowercase email, phone with the country code, no stray whitespace. Hashing a badly formatted value produces a hash that will never match.
- Always send currency alongside value. Without it Pinterest uses the account default, which quietly corrupts reporting on a multi-currency store.
- Register any custom event name in Ads Manager before you send it, and map it to a standard event type. An unregistered custom event is accepted and then never tracked.
- Prioritize the lower-funnel events. Pinterest weights checkout, add to cart, sign-up and lead most heavily for both optimization and Event Quality Score.
- Use NeoTag rather than dhPixel if you send to more than one marketing platform, so one tag serves them all.
- Re-validate the connection whenever the access token is regenerated in Ads Manager.
Troubleshooting & FAQ
Section titled “Troubleshooting & FAQ”Validate Credentials fails. Re-check the Advertiser Account ID, and confirm the token was generated for that account rather than a different one. Then check the role: Pinterest refuses the request when the account behind the token neither owns the advertiser account nor holds admin, analyst, audience or campaign access to it. That is the more common of the two causes and looks identical from Studio.
No events appearing in Events overview. Confirm a website or e-commerce source is connected in the same project and that the tag is published in your tag manager. A connected destination on its own produces nothing.
Events are delivered but one event type never appears in reporting. Almost always a custom event name that was never registered in Ads Manager. Pinterest accepts it and then does not track it. It shows up in Ads Manager under custom events not tracked.
Conversions counted twice. The tag and the server are not sharing an event ID, or the event names differ between the two paths. See Deduplication.
Event Quality Score is Fair or Needs improvement. Open the parameter breakdown under Conversions, then Event Quality, and download the sample of affected events. Missing IP address, user agent or external ID coverage accounts for most of it; the rest is usually event ID coverage, which shows up as a low overlap score.
Conversions reported in the wrong currency. Value is being sent without currency, so Pinterest is applying the advertiser account default. Map currency at the source.
Web events are showing as offline conversions. They are arriving more than an hour after the conversion happened. Check the schedule on the connected source. Offline events also stop being eligible for deduplication, so this usually appears alongside duplicate counting.
Delivery stopped. The access token has been regenerated or revoked, or the account it belongs to has lost access to the advertiser account. Generate a new token in Ads Manager and re-validate the connection.