pooriaarab Pinterest Ads
Pinterest has a public, self-serve Conversions API. A Pinterest Business account and an advertiser account are the real gates. The CAPI conversion token does not need a Pinterest app or app ID. Conversions API overview
Use this skill with ad-conversion-hub. The hub owns event timing, consent,
normalization, hashing, retries, durable dispatch, and failure isolation. This
skill owns Pinterest names, fields, endpoints, and account settings.
Account and API access
- Create a free Pinterest Business account from a desktop device, or convert a personal account. The email must not already belong to another Pinterest account when creating a new one. Create a Business account
- In Business Manager, open Ad accounts, select Create ad account, choose the country, and assign people. Pinterest does not allow a later currency change. Create an advertiser account
- Check that the advertiser country is supported. Pinterest blocks direct ad setup in other markets. Some markets use an advertising partner such as Aleph, Mediadonuts, or DMS. Ads availability Campaign API use also needs Business Access, the Advertising Services Agreement, a business profile, and billing. Ads API prerequisites
- For CAPI only, open Ads Manager → Ad Account Overview → Conversions → Conversions API → Set up API, choose Conversion access token, and generate a token. Copy the token and advertiser ID immediately. Generate a conversion token
- Use
PINTEREST_TAG_IDin the browser,PINTEREST_AD_ACCOUNT_IDin the server endpoint, andPINTEREST_CAPI_TOKENin the server secret store. - If the integration also uses campaigns, audiences, or other Pinterest API
endpoints, use an OAuth token with at least
ads:writeand an advertiser ID. Register an app, accept the Developer Terms, and request trial access first. A conversion token is not general Pinterest API access. App access and CAPI prerequisites
Pinterest Tag
Load the base code once in the document <head> on every page. Run it before
any event code. Use the generated code from Conversion Tag Manager with the ID
in PINTEREST_TAG_ID; do not create one tag per page. Install the base code
<script>
!(function (e) {
if (!window.pintrk) {
window.pintrk = function () {
window.pintrk.queue.push(Array.prototype.slice.call(arguments));
};
var n = window.pintrk;
n.queue = [];
n.version = '3.0';
var t = document.createElement('script');
t.async = true;
t.src = e;
var r = document.getElementsByTagName('script')[0];
r.parentNode.insertBefore(t, r);
}
})('https://s.pinimg.com/ct/core.js');
pintrk('load', '<PINTEREST_TAG_ID>');
pintrk('page');
</script>
Fire the event code only after the user action. A conversion event placed in a
confirmation page fires again on every reload. For a purchase, send the same
hub event_id in the Tag event object:
pintrk('track', 'checkout', {
event_id: '<shared-event-id>',
value: 25.00,
currency: 'USD',
order_id: '<order-id>',
order_quantity: 1,
});
Pinterest documents eventID, event_id, and eid as accepted, case-sensitive
Tag fields. Use event_id in this adapter. Tag event data
Call pintrk('setconsent', true) only after the hub grants measurement consent.
Call it with false when consent is denied. false stops events and deletes
Pinterest first-party session storage. Tag consent
The Tag can send enhanced match data. Pinterest hashes an unhashed email before transmission. The hub still requires consent before identity collection. Use the hub's lowercased, trimmed SHA-256 values. Enhanced match
Conversions API
Send a server event after the payment provider confirms the charge. Do not wait for a click ID. Pinterest can match with hashed identity or client data.
POST https://api.pinterest.com/v5/ad_accounts/<PINTEREST_AD_ACCOUNT_ID>/events
Authorization: Bearer <PINTEREST_CAPI_TOKEN>
Content-Type: application/json
The body has a data array. Each event requires action_source, event_id,
event_name, and event_time. Use web for website events. event_time is
Unix seconds. user_data must contain em, hashed_maids, or the pair
client_ip_address and client_user_agent. Send conversion events
{
"data": [
{
"action_source": "web",
"event_name": "checkout",
"event_time": 1769818901,
"event_id": "<shared-event-id>",
"event_source_url": "https://example.com/checkout/complete",
"opt_out": false,
"user_data": {
"em": ["<sha256-email>"],
"external_id": "<sha256-user-id>",
"click_id": "<epik-cookie-value>",
"client_ip_address": "<client-ip>",
"client_user_agent": "<client-user-agent>"
},
"custom_data": {
"value": "25.00",
"currency": "USD",
"order_id": "<order-id>",
"num_items": 1
}
}
]
}
em, external_id, and ph are SHA-256 values. Normalize email to lowercase
before hashing. Normalize phone to digits with country code, area code, and
number. Remove symbols, letters, spaces, and leading zeros. Follow the hub's
identity rules and consent gate. User data formatting
For purchases, Pinterest calls the standard event checkout. Its order_id
is recommended for CAPI and required for Tag conversion analysis reporting.
Send the pre-tax, pre-shipping value and the ISO-4217 currency. Pinterest
accepts value as a string and parses it as a number. CAPI parameter reference and Tag event data
The response can contain mixed results. Check num_events_processed and each
event's status; do not treat an HTTP 200 response as proof that every event
was processed. CAPI response example
Hub event mapping
Use the same canonical event_id in both browser and server events. The API
uses snake case names. The Tag uses the corresponding event names shown below;
Pinterest's code examples also show their lowercase forms.
| Hub event | CAPI event_name |
Tag event | Notes |
|---|---|---|---|
page_view |
page_visit |
PageVisit / pagevisit |
Send on route or page load. |
view_content |
view_content |
ViewContent / viewcontent |
Send on a meaningful product or plan view. |
lead |
lead |
Lead / lead |
Send after a qualified form submit. |
signup |
signup |
SignUp / signup |
Send after account creation. |
begin_checkout |
initiate_checkout |
InitiateCheckout / initiatecheckout |
Send when checkout starts. |
purchase |
checkout |
Checkout / checkout |
Send after a confirmed charge. |
subscription_start |
subscribe |
Subscribe / subscribe |
Closest standard event. Confirm campaign semantics. |
refund |
custom refund |
custom refund |
No standard refund event. Map the custom event to a standard event only if reporting needs it. |
These names and purposes come from Pinterest's conversion event table. Custom events support audience creation, but need a standard-event mapping for conversion reporting. Conversion event types
Deduplication
Pinterest deduplicates redundant Tag and API events with matching event_id
and event_name. The Tag's eventID value must equal the API's event_id
value. Pinterest keeps the first event and removes duplicates within 48 hours.
Use the payment transaction ID for a purchase when possible. Deduplication and event IDs
Do not reuse a purchase ID for a refund or another event. Do not send a new random ID when retrying a request. Let the hub retry policy and durable dispatch record control retries.
Click ID and attribution
Pinterest adds epik to the landing URL. The Tag caches it in first-party
_epik. Send that cookie as user_data.click_id; Pinterest prefers it when a
redirect removes the URL value. CAPI click ID and Pinterest cookies
Tag cookies persist for one year from installation, but users can delete them.
epik's separate expiry is UNVERIFIED; Pinterest does not publish one. The
default reporting window is one-day view and 30-day click. Cookie behavior and Conversion windows
Capture epik on first landing. Store first-touch and most-recent values in
first-party storage under the hub's retention policy. Also pass the browser's
_epik cookie to the server at conversion time. Never make the click ID a
condition for sending a purchase; organic and direct purchases still need
measurement.
Tracking quirks that bite
- Each advertiser account needs its own Tag. The base code runs once before event code. A page-load event fires again on every reload. Tag setup
- Tag reporting exposes
valueandorder_quantity. CAPI accepts richer data, but purchaseorder_id, value, and currency must be correct. Tag event data - Send CAPI events within one hour. Production batches allow 1,000 events. Test batches process only the first 20. CAPI best practices
- Use
webfor browser events. Other sources areapp_android,app_ios, andoffline. Automatic enhanced match is an Ads Manager setting that can hash form fields in certain regions. Align it with consent. Action sources and match - Conversion Insights can take days to build. Its selected windows can differ from Ads reporting and analytics. Conversion Insights
Verification
- Send a test request to the same endpoint with
?test=true. Test data goes to a sandbox and does not affect reporting or optimization. - Open Ads Manager → Campaign manager → Conversions → Test events. Confirm the event appears there. CAPI test events
- For production, require each response event to be
processed. Then inspect Conversions Health and the deduplication view. Conversions Health - Confirm Tag
verifiedstatus and Tag Event History. This can take up to three hours. Reconcile processedcheckoutevents with succeeded charges. Tag verification
Common pitfalls
- Use
PINTEREST_CAPI_TOKEN, not a browser-visible token orPINTEREST_ADS_TOKEN. - Put the advertiser ID in the URL path. Use
checkoutfor a completed purchase; useinitiate_checkoutonly when checkout starts. - Include dynamic
order_id,value, andcurrency. Do not use zero, negative, static, or pre-tax-incorrect values. - Do not use
epikas the send gate. Do not replace_epikwith a new ID. - Do not send raw email or phone values in CAPI or Tag image requests. Check each event status in a mixed response. Match reporting windows before comparing Pinterest with last-click analytics.
Security
Keep PINTEREST_CAPI_TOKEN in the server secret store. Never put it in client
JavaScript, URLs, logs, screenshots, or commits. Use HTTPS and the hub consent
gate. Keep raw identity data server-side. Load https://s.pinimg.com/ct/core.js
only as the official Pinterest Tag script.