Conversions API Payload Builder for Pinterest

How to build a Pinterest Conversions API event

The Pinterest Conversions API accepts an event only when five fields are right, and it can match the event to a person only when the customer details are hashed the way Pinterest asks. This builder follows Pinterest's Track conversion events in the API guide and the Send conversions reference, and turns your values into a request you can send or hand to a developer.

1. Get your ad account ID and token. In Ads Manager, open Conversions, then Set up API, and generate a conversion access token. Copy the ad account ID shown with it. The token stays with you; this page never asks for it.
2. Pick the source and the event. Choose web, offline or an app, then the event. Names from the tag or other platforms, like AddToCart or Purchase, are turned into the API names.
3. Set the time and event ID. The time becomes Unix seconds. The event ID is required, and it must match the eventID your tag sends for the same event.
4. Add customer details. Email, phone, name, city, state, ZIP, country, birth date and gender are normalized and hashed with SHA-256 right here, and written as lists like the API expects.
5. Copy the result. You get the JSON body, a curl command and, for web events, the matching pintrk call. Switch to batch mode to turn spreadsheet rows into requests of up to 1,000 events each; every request is shown.

Details the builder gets right for you

• value is a string. Pinterest reads "66.95" as a number on its side. Zero and negative values are flagged as invalid.
• Phones are digits only. No plus sign, spaces or leading zeros, but with the country code.
• States and countries are two letters. “California” becomes ca, lowercased as Pinterest's text says. Pinterest's own example hash uses uppercase “US”, so the tool tells you whenever it sends these.

Test and go live with the Pinterest Conversions API

1. Send a test request. Turn on test mode, which adds ?test=true, and send the payload with your token in the Authorization: Bearer header. Test events get the same response messages but aren't recorded.
2. Check the response. Each event comes back as processed or failed, in the order you sent them, with an error or warning message.
3. Confirm in Ads Manager. Open Campaign manager > Conversions > Test events to see the test event arrive.
4. Go live in real time. Remove ?test=true and send events as they happen, or within an hour. Send the same events from the Pinterest tag with the same event ID.
5. Watch event quality. The Conversions Health page in Ads Manager shows your Event Quality Score.

Pinterest Conversions API errors and fixes

“Invalid event_name”

Pinterest's own example rejects subscription and suggests subscribe or checkout. Use the lowercase API names. Custom events must be mapped to a standard event, up to 15 per advertiser.

“AdAccount not found”

Pinterest's example error for a request it can't link to an ad account. Check the ad account ID in the URL, and that your token was generated for that account. Copy both again from the Conversions API setup page.

401 or 403: token or permission problems

The token's user must own the ad account or have the Admin, Analyst, Audience or Campaign role through Business Access. Send it as Authorization: Bearer, not in the JSON.

pinterest conversions api hashed email not matching

Hash the lowercased email, and send em as a list. A hash of “[email protected]” never matches the hash Pinterest makes of “[email protected]”.

429: too many requests

The limit is 5,000 calls per minute per ad account. Batch events, up to 1,000 per request, instead of sending one call per event.

Events counted twice

The tag and the API sent the same checkout with different or missing IDs. Send one ID, such as the order number, from both. Offline events can't be deduplicated at all.