How to Set Up Pinterest Conversions API Tracking on Magento 2

TL;DR

Pinterest accepts two kinds of credential for the Conversions API, and the addon asks for the one the conversions rate-limit category does not apply to. Once the token and the advertiser ID are paired, the setup is three decisions: whether guest events go out at all, which of the ten events you select in each of the two places they can be selected, and whether a second ad account is worth the client-side step it quietly requires. The evidence shows up in three surfaces, none of which is a GA4 report.

Key Takeaways

• Pinterest documents two authentication routes. The ads_conversions rate limit category "applies to requests authenticated with a token acquired through the standard OAuth flow", and Pinterest's own recommendation is to "use the conversion access token, which enables you to send unlimited conversion-tracking events" [2].
• The addon's credential field is Pinterest Conversions API Access Token, which is the conversion-token form, so a correctly configured store sits outside the ads_conversions category limits [2][4].
• Pinterest publishes its matching floor: user_data "must include at least one of the following: em, hashed_maids, Pairing of client_ip_address and client_user_agent" [1]. That sentence, not a preference, is what decides the logged-in-only toggle.
• The client-side Pinterest pixel and the server-side addon cover the same ten event types in two separate admin sections with two separate configurations. They are never one merged list [4][5].
• A second advertiser receives only the enabled server-side events. PageVisit for attribution needs the extra tag IDs added client-side, comma separated, or the second account looks configured while its attribution surface is missing [4].

Which token you use decides which rate limits apply

Start here. This is where configurations fail.

Pinterest's prerequisites are an advertiser account plus either a conversion access token, which covers conversions only, or an OAuth token carrying at least the ads:write scope for the wider endpoint set [1]. The two routes are metered differently. The rate limits page puts the ads_conversions category at 1,000 requests per day per ad account per app on Trial access and 120,000 requests per minute per ad account per app on Standard access, then says that category "applies to requests authenticated with a token acquired through the standard OAuth flow", and recommends the conversion access token instead because it "enables you to send unlimited conversion-tracking events" [2].

The addon asks for a Pinterest Conversions API Access Token [4]. That is the conversion-token form, so a store that followed the guide is outside that category without having decided to be. Useful to know anyway, because the first thing anyone blames for missing events is a quota.

On our side the requirement is stated plainly in the addon guide: a Pinterest Business account with an approved Conversions API access token and an advertiser account ID, and each advertiser you connect needs its own valid token [4]. The addon requires the GA4 PRO extension, installs as weltpixel/module-ga4-pinterestss, and has been Composer-only since v1.16.0 (January 7, 2026). It runs on Magento 2.3.x through 2.4.9 across all editions and supports multiple store views, with PHP 8.5 and Magento 2.4.9 compatibility added in v1.17.0 (May 18, 2026) [4].

Where do the account ID and the token actually come from?

Pinterest documents both on one Ads Manager screen. Its path is Ad Account Overview > Conversions > Conversions API > Set up API, then Conversion access token and Generate new token; the token "is displayed with your ad account ID" [1]. Our guide points at that screen for the Pinterest Account ID and at Business Access → Conversions API for generating the token [4]. Whichever route produced yours, record it next to the account ID it belongs to, or you get the failure where one ad account's token sits next to another account's ID.

With the base extension already installed and its container generated, which the server-side tracking setup guide covers end to end, the addon's own configuration lives at WeltPixel → Google Analytics 4 Ecommerce PRO → Pinterest Conversions API Settings [4].

A switch outside this section changes what the whole addon does. Since v1.17.4 (September 1, 2026), with Require Visitor Consent for Server-Side Events switched on in the GA4 configuration, this addon's events are gated on the shopper's advertising consent, and an order pushed later by cron is judged on the consent stored with that order. It is off by default [4][5]. Which privacy controls actually exist in this extension, and which ones are marketing, is the subject of the PII controls article.

What breaks when you add a second advertiser?

Send eCommerce Event Data to multiple Pinterest endpoints exists for agencies and multi-brand operators, and the guide attaches a warning to it that is easy to read past: "Adding a new advertiser here will only send the enabled server-side events. If you need PageVisit events for attribution, also add the additional Pinterest Tag IDs in the Pinterest Pixel Tracking section above (comma separated)" [4]. Each additional advertiser also needs its own valid access token [4].

Read that as a two-step operation. The server rows give the second account its purchases and cart events. The client-side step, done in the Pinterest Pixel Tracking section as the guide directs, gives it the page views its attribution reporting is built on. Skip it and the second ad account shows conversions with nothing in front of them, which reads in Ads Manager as a targeting problem rather than a configuration one. The Klaviyo addon guide covers the same multi-account shape for a platform where the consequence differs.

Should you forward guest events? Pinterest publishes the floor

Set to Yes, Send events only for logged in users forwards only events carrying a hashed email [4]. Set to No, guest events go out too, and the question is whether Pinterest can do anything with them.

It can, and the criterion is documented. The user_data object "must include at least one of the following: em, hashed_maids, Pairing of client_ip_address and client_user_agent", where em is the SHA-256 hash of the lower-cased email address [1]. A guest checkout on the web clears that minimum through the IP and user-agent pairing. Pinterest also documents a click identifier, click_id, and tells you to read it from the _epik cookie rather than the &epik= query parameter, because "passing _epik cookie values is necessary when a URL parameter is missing or removed and ensures greater coverage" [1]. Our addon guide describes the No case as Pinterest stitching events via the Pinterest tag visitor ID [4]; the matching minimum quoted above is Pinterest's own statement of what it needs.

So the decision is about your checkout. If most of your revenue arrives through guest checkout, switching the toggle on discards most of your purchase volume from the Conversions API. If your store forces account creation anyway, the toggle costs nothing and keeps a hashed email on every event. Repeat buyers shift the balance: since v1.16.1 (March 6, 2026) the addon persists hashed customer data captured at purchase and sends it with later events from the same shopper [4], so such a store accumulates identity across visits.

The same ten events, chosen twice

Both halves of Pinterest tracking cover the same ten event types, configured in two different places. The addon's Track Events multiselect governs the server side [4]. The client-side pixel is a separate PRO feature at Admin → WeltPixel → Pinterest Pixel Tracking → Pinterest Pixel Tracking Configuration, with its own Track Events multiselect and a Product Identifier [ID / SKU] choice [5]. Two sections, two configurations, one event vocabulary:

The mapping above is Pinterest's [1]. Keeping the two selections in step is manual, which is the part people skip. With Send enabled events via the frontend Pinterest tag as well switched on, duplicates "are automatically deduplicated via the event ID" [4], and Pinterest's side of that bargain is explicit: pass event_id and event_name "in all the sources you use, making sure that the event_id is identical for each redundant event", after which "Pinterest retains the first event captured and removes duplicates within 48 hours" [1]. The client-side pixel has to be enabled with its tag code in place for browser and server events to match at all [4].

Platforms where the two lists genuinely differ need a stricter version of this discipline, which the Snapchat addon guide works through. Pinterest is the easier case, and for that reason the one where a merged mental list survives longest.

Pinterest's guidance for client_user_agent is "Do not send user agents produced by bot" [1], and v1.17.4 (September 1, 2026) added server-side bot filtering to the addon using the same merchant-editable pattern list as the GA4 Measurement Protocol, while order events are always sent [4].

The three places the evidence shows up

None of them is a GA4 report.

Enable Test Mode marks outgoing requests so Pinterest treats them as tests instead of conversions; Pinterest caps test requests at 10 per app per second, sent with is_test set to TRUE [2][4]. Enable File Log writes the addon's request and response traffic to var/log/pinterest-api.log, which is where an authentication failure or a rejected payload actually appears [4]. On the platform side, Pinterest's instruction is direct: "To check the quality of your conversion data, go to the Conversions Health page in Ads Manager" [1]. Behind all three, the endpoint the addon calls is POST /v5/ad_accounts/{ad_account_id}/events on API v5 [3].

Check your version before trusting any of it. v1.17.5 (September 16, 2026) was a catalog-wide security release, and for this addon it narrowed the public server-side tracking endpoint so it only sends events for the current session's own order or cart, and validates a posted event name against the configured event map [4]. A store on an older build can be fed events it did not generate, which is a data-integrity problem before it is anything else.

For the wider question of whether a given event ever left Magento, the event verification guide covers the dataLayer, the container and the server-side log chain.

FAQ

Can the Pinterest addon run without the GA4 PRO extension?

No. The addon requires the Google Analytics 4 PRO extension and installs alongside it through Composer as weltpixel/module-ga4-pinterestss [4]. It reads the event layer the base extension builds, which is also why the client-side pixel configuration sits in the base extension and not in the addon.

Do I need a Pinterest developer app approved for the Conversions API?

Our guide asks for a Pinterest Business account, an approved Conversions API access token and an advertiser account ID, with one token per advertiser [4]. Pinterest documents generating a conversion access token directly in Ads Manager under Ad Account Overview > Conversions > Conversions API > Set up API [1]. The OAuth route with the ads:write scope is the one that reaches the broader API surface and the metered ads_conversions category [1][2].

Will running the tag and the server events together double my conversions?

Not if both sides send the same event_id. Pinterest keeps the first event it captures and removes duplicates within 48 hours [1], and the addon's frontend duplication option is built to share the event ID so that deduplication works [4]. The failure mode to watch for is the reverse one: a browser tag that is switched off, leaving server events with nothing to match against [4].

Why does my second ad account show purchases but no page views?

Because additional advertisers configured for multiple endpoints receive only the enabled server-side events, and PageVisit for attribution needs the extra tag IDs added in the Pinterest Pixel Tracking section, comma separated [4].

Where do I look when an event does not arrive?

var/log/pinterest-api.log for what Magento sent and what Pinterest answered [4], then the Conversions Health page in Ads Manager for what Pinterest thinks of the data it received [1].

The addon and the client-side pixel it pairs with are the Pinterest API Addon for Google Analytics 4 PRO and the Magento 2 Google Analytics 4 extension on its PRO tier, both currently at v1.17.5, released September 16, 2026.

Sources

1. Track conversion events in the API, Pinterest developer documentation, retrieved September 21, 2026, https://developers.pinterest.com/docs/track-conversions/track-conversions-in-the-api
2. Rate limits, Pinterest developer documentation, retrieved September 21, 2026, https://developers.pinterest.com/docs/reference/rate-limits/
3. Events create, Pinterest API v5 reference, retrieved September 21, 2026, https://developers.pinterest.com/docs/api/v5/events-create/
4. WeltPixel Pinterest Addon User Guide, v1.17.5, September 16, 2026, https://docs.weltpixel.com/PinterestAddon/User-Guide-WeltPixel-Pinterest-Addon.html
5. WeltPixel Google Analytics 4 User Guide, v1.17.5, September 16, 2026, https://docs.weltpixel.com/GA4/User-Guide-WeltPixel-Google-Analytics-4.html