If you are running Pinterest ads and relying solely on the Pinterest tag to track conversions, you are likely missing a meaningful portion of the data that drives your campaign decisions. Browser-based tracking has become increasingly unreliable due to ad blockers, browser privacy restrictions, and cookie limitations. The Pinterest Conversion API solves this by sending conversion data directly from your server to Pinterest, bypassing the browser entirely.
The result is more accurate conversion data, better ad optimization, and smarter bidding decisions from Pinterest's algorithm. Think of it like this: your browser-side tag is a spotter who sometimes gets blocked from the view, while your server-side API is a direct line that always gets through.
This guide walks you through every step of setting up the Pinterest Conversion API, from creating your access token to verifying that events are firing correctly. Whether you are part of a marketing team at a B2B SaaS company or a growth leader managing paid social campaigns, this setup will give you a more complete picture of what your Pinterest ads are actually driving.
By the end of this guide, you will have a working server-side integration that captures conversion events reliably and feeds Pinterest's ad platform the signal quality it needs to optimize toward your best customers. Let's get into it.
Step 1: Gather Your Prerequisites and Access Credentials
Before you write a single line of code, you need to make sure the right accounts, permissions, and credentials are in place. Skipping this step is the fastest way to hit a wall halfway through your implementation.
Start by logging into your Pinterest Business account. Confirm that you have admin access to Ads Manager. This matters because the Conversion API endpoints are only accessible through a Business account. Using a personal account will block you from the API entirely, which is one of the most common early mistakes teams make.
Next, navigate to Events Manager within Ads Manager. This is where you will find your Ad Account ID, which is a required parameter for every API call you make. Write it down or save it somewhere secure.
Now generate your Conversion Access Token. Go to Business Settings, then select Conversions, and create a new token with the appropriate permissions. This token acts as your authentication credential and is passed as a Bearer token in the Authorization header of every API request. Treat it like a password: store it securely and never expose it in client-side code.
At this point, confirm that you have access to the server environment or tag management system where you plan to implement the server-side code. This could be your application backend, a cloud function, a server-side Google Tag Manager container, or a middleware layer. The specifics depend on your tech stack, but you need write access to wherever your conversion logic will live.
Understanding the two-track approach: The Pinterest Tag fires in the browser when a user takes an action on your site. The Conversion API fires from your server. Pinterest recommends running both in parallel, not as replacements for each other. The browser tag captures signals that your server might not see, and the server confirms conversions that the browser tag might miss. Deduplication (covered in Step 4) ensures the same event is not counted twice.
Quick credential checklist before moving on: You have your Ad Account ID saved. You have generated and stored your Conversion Access Token. You have confirmed admin access to Pinterest Business Manager. You have identified the server environment where your implementation will live. Once all four are in place, you are ready for the next step.
Step 2: Define the Conversion Events You Want to Track
One of the most overlooked parts of a Pinterest CAPI setup is deciding what to track before you start building. Sending the wrong events, or too many low-signal events, dilutes the data quality that Pinterest's algorithm uses to optimize your campaigns.
Start by mapping out the key actions in your funnel that represent meaningful conversions. Pinterest CAPI supports a set of standard event types including Checkout, AddToCart, PageVisit, SignUp, Lead, and custom events for anything that does not fit a standard category.
For B2B SaaS companies, the most valuable events to prioritize are trial starts, demo requests, and free sign-ups. These are the moments where a Pinterest-driven visitor crosses from awareness into your pipeline. Tracking these events directly connects your ad spend to business outcomes rather than vanity metrics.
If your conversion events have associated revenue, always include a value parameter. This allows Pinterest to optimize toward higher-value conversions rather than treating all events equally. A trial start that converts at a higher rate than a newsletter sign-up should carry a different weight in Pinterest's optimization model.
Create a simple event mapping document before you build anything. For each event, list the event name, the trigger condition (what action causes it to fire), and any associated revenue value. This document becomes your reference point during implementation and helps you stay consistent across channels.
Keep your event list focused early on: It is tempting to track everything, but sending too many low-signal events early in your integration gives Pinterest's algorithm noisy data to work with. Start with your two or three most important conversion actions and expand from there once you have confirmed the integration is working correctly.
Cross-channel naming consistency matters: If you are running Meta CAPI or Google Enhanced Conversions alongside Pinterest, align your event naming conventions across all three platforms. Using Lead on Pinterest, lead on Meta, and generate_lead on Google creates attribution headaches when you try to reconcile data across platforms. Consistent naming makes cross-channel analysis significantly cleaner.
Once your event map is documented, you have a clear blueprint for what your API payloads need to contain. That is exactly what the next step covers.
Step 3: Structure Your API Payload Correctly
This is where the technical work begins. The Pinterest Conversion API uses a REST endpoint structured as follows:
Endpoint: https://api.pinterest.com/v5/ad_accounts/{ad_account_id}/events
You will replace {ad_account_id} with the Ad Account ID you saved in Step 1. Requests are authenticated using your Conversion Access Token passed as a Bearer token in the Authorization header.
Every event payload you send must include four required fields. The event_name field specifies the type of conversion (such as Lead or SignUp). The action_source field tells Pinterest where the conversion happened, with valid values being web, app, or offline. The event_time field is a Unix timestamp representing when the conversion occurred. And the event_id is a unique identifier used for deduplication, which is covered in detail in the next step.
Beyond the required fields, user data significantly improves your match rate. Match rate is Pinterest's ability to connect a conversion event back to a specific Pinterest user. The higher your match rate, the better Pinterest can optimize ad delivery toward users who are likely to convert. Understanding CAPI match rate and how it is calculated will help you prioritize which user data fields to include.
User data fields that drive match quality: Hashed email address is the most impactful field you can pass. Hashed phone number adds additional matching signal. The epik click ID, which is Pinterest's proprietary parameter appended to URLs when a user clicks a Pinterest ad, is one of the strongest match signals available because it directly links the conversion back to a specific ad click.
The epik parameter appears in the URL when someone arrives on your site from a Pinterest ad. You need to capture it from the URL and store it in a first-party cookie so your server can retrieve it when the conversion fires later in the session. If you are not capturing the epik parameter today, add that to your implementation plan now.
All user identifiable information must be hashed using SHA-256 before you send it to the API. This is not optional. Before hashing email addresses, normalize them by converting to lowercase and trimming any leading or trailing whitespace. Failing to normalize before hashing is a common mistake that breaks match rates because the same email address can produce different hashes depending on capitalization.
Include the event_source_url field for all web events. This gives Pinterest additional context about where on your site the conversion occurred and contributes to event quality scoring.
Once your payload structure is correct and your user data fields are hashed and included, you are ready to think about deduplication.
Step 4: Implement Deduplication Between Your Pinterest Tag and CAPI
Here is where many implementations stumble. When you run both the Pinterest Tag and the Conversion API simultaneously, the same conversion can be reported twice: once by the browser tag and once by your server. Without deduplication, your conversion counts will be inflated and your campaign data will be unreliable.
Pinterest solves this with the event_id field. The logic is straightforward: assign the same unique event_id to both the browser-fired tag event and the corresponding server-side API event for the same conversion. When Pinterest receives two events with matching IDs within its deduplication window, it merges them into a single conversion rather than counting them separately.
Generate the event_id on the client side. A UUID or a timestamp-based string both work well. The key requirement is that it is unique per conversion event and that the same value is passed to both the Pinterest Tag and the server-side API call for that specific conversion.
Practically, this means you need a way to pass the event_id from the browser to your server. Common approaches include storing it in a session variable, passing it as a hidden form field that gets submitted with the conversion action, or including it as a data attribute that your server-side code reads when processing the conversion. Following best practices for tracking conversions accurately at this stage will save you significant debugging time later.
Pinterest's deduplication window is typically a few minutes. Events with matching IDs received within that window are merged. This means your server-side event does not need to fire in the same millisecond as the browser tag, but it should fire reasonably close in time to the user action.
To verify that deduplication is working, trigger a test conversion and then check the Events Manager. You should see one event recorded, not two. If you see duplicate events, check whether the event_id values match between your tag implementation and your server payload.
Why running both channels in parallel is worth the extra complexity: Server-side events alone can miss browser signals that only exist in the client environment. Browser-only tracking misses server-confirmed conversions that ad blockers or privacy settings would otherwise suppress. Running both gives you the most complete signal possible, and deduplication ensures that completeness does not come at the cost of accuracy.
With deduplication in place, your integration is structurally sound. The next step is confirming it actually works before you go live.
Step 5: Send a Test Event and Validate in Events Manager
Never skip testing. A Pinterest CAPI integration that looks correct in code can still fail in subtle ways that only show up when you check the actual event data. Testing catches those issues before they contaminate your live campaign data.
Pinterest provides a test_event_code parameter that you include in your API payload during testing. Events sent with this parameter appear in a separate test environment and do not affect your live campaign reporting. This means you can test freely without worrying about skewing your conversion data.
To send a test event, use the Pinterest API Explorer or a tool like Postman. Build a sample payload that includes all your required fields, your hashed user data, and the test_event_code. Send it to the CAPI endpoint using your Conversion Access Token for authentication.
Pay close attention to the HTTP response code. A 200 response confirms that your request was received and the payload was valid. A 400 response indicates a malformed payload, which usually means a required field is missing or formatted incorrectly. A 401 response signals an authentication issue, which typically means your Conversion Access Token is wrong or has expired.
After sending a successful test event, navigate to Events Manager in Pinterest Ads and look for the Test Events tab. Here you can see real-time event validation, including whether the event name is recognized, whether the action source is correct, and whether your user data fields are contributing to a match rate. If you are seeing gaps in your event data, reviewing common conversion tracking gaps can help you diagnose the issue quickly.
Common validation issues to watch for: Missing required fields like event_time or action_source will return errors even if authentication succeeds. Incorrectly formatted Unix timestamps are another frequent culprit. If your match rate is showing as zero, check whether your hashed email is being normalized correctly before hashing.
The rule here is simple: Do not move to production until at least one test event has been validated end-to-end in the Events Manager. You want to see the event appear with the correct name, the correct action source, and a visible match rate contribution from your user data fields. Once you have that confirmation, you are ready to go live.
Step 6: Deploy to Production and Monitor Event Quality
Going live is straightforward once testing is complete. Remove the test_event_code parameter from your payloads. That single change is what switches your integration from test mode to production mode. Your events will now flow into your live Pinterest reporting.
For the first 24 to 48 hours after deployment, monitor the Events Manager dashboard closely. You are looking for events arriving at roughly the volume you would expect based on your site traffic and conversion rates. A sudden drop in event volume or a complete absence of events is a signal that something in your implementation broke during the transition to production.
One of the most important metrics to watch after going live is your event match quality score. Pinterest surfaces this score in Ads Manager, and it reflects how well your conversion events are being matched back to Pinterest users. A higher match quality score means Pinterest's algorithm has more signal to work with, which translates to better audience targeting and more efficient ad optimization.
If your match quality score is lower than you expect, look at which user data fields are contributing to matches and which are not. Often, adding one or two additional fields can meaningfully improve the score. City, state, or zip code alongside hashed email and phone can provide enough additional signal to lift match quality noticeably.
Set up monitoring on your server side as well. API errors or drops in event volume can happen silently if you are not watching for them. Configure alerts in your server environment or application monitoring tool to flag any sustained increase in API error rates or any unexpected drop in the number of events being sent.
After one full week of production data, compare your Pinterest CAPI event volume against what you see in your CRM or analytics platform. The numbers will not match exactly, but they should be in the same general range. A large discrepancy is worth investigating and usually points to either a configuration issue or a gap in which events are being captured on the server side. Using enterprise conversion tracking solutions can make this cross-platform reconciliation significantly easier to manage at scale.
With production monitoring in place, your Pinterest CAPI integration is fully operational. But the real value of this data goes beyond what Pinterest's native reporting can show you.
Connecting Pinterest CAPI Data to Full-Funnel Attribution
Setting up Pinterest CAPI is a meaningful technical achievement, but it is only the first step. The conversion signals you are now sending to Pinterest live inside Pinterest's reporting environment. To understand how Pinterest actually fits into your customer journey, you need to connect those signals to the rest of your marketing data.
This is where the limitations of platform-native reporting become clear. Pinterest can tell you that a conversion happened after a Pinterest ad interaction. It cannot tell you whether that same user also clicked a Google ad, engaged with a LinkedIn post, or came back through organic search before converting. Without cross-channel context, you are making budget decisions based on incomplete information.
For B2B SaaS teams, this gap is especially costly. A trial start attributed to Pinterest might actually be the result of a multi-touch journey that started on Google, moved through LinkedIn, and closed after a Pinterest retargeting ad. Understanding that full journey is what separates smart channel investment from guesswork. This is where understanding assisted conversions across channels becomes critical to accurate attribution.
Cometly is built specifically to solve this problem. It connects your ad platforms, including Pinterest, alongside your CRM and website data to create a unified view of every touchpoint from first ad click to closed revenue. Instead of reading Pinterest data in one tab and Google data in another, you get a single source of truth that shows how each channel contributes to pipeline and revenue.
Cometly's server-side tracking captures enriched first-party data and sends conversion-ready events back to ad platforms, improving the optimization signals that Pinterest, Meta, and Google use to target and bid. Its AI surfaces which ads and campaigns are actually performing across all channels, not just within the reporting environment of any single platform.
For growth leaders managing multi-channel campaigns, this kind of visibility is what makes it possible to scale with confidence. You can see whether Pinterest is driving trial starts that convert to paying customers, or whether it is generating sign-ups that churn early. That distinction changes how you allocate budget and which campaigns you scale.
If you are ready to go beyond Pinterest's native reporting and connect your CAPI data to a full-funnel attribution model, Get your free demo and see how Cometly gives your team complete attribution visibility across every channel you run.
