Pinterest Tag & Conversions API Setup | OpsBlu Docs

Pinterest Tag & Conversions API Setup

Technical guide to Pinterest Tag (pintrk) installation, conversion events, Enhanced Match, API for Conversions, and shopping catalog tracking.

How Pinterest Tracking Works

Pinterest's measurement system consists of the Pinterest Tag (browser-side JavaScript) and the Pinterest API for Conversions (server-side). Both feed data into Pinterest Ads Manager for attribution, audience creation, and campaign optimization.

Browser-side (Pinterest Tag): The tag loads s.pinimg.com/ct/core.js, which initializes a global pintrk object. On initialization, it sets a _pinterest_ct_ua first-party cookie and a _pin_unauth cookie for unauthenticated user tracking. When events fire, the tag sends requests to ct.pinterest.com containing event data, cookie identifiers, and any Enhanced Match parameters.

Server-side (API for Conversions): The API accepts events via HTTPS POST to api.pinterest.com/v5/ad_accounts/{ad_account_id}/events. It requires an access token with the ads:write scope. Server-side events bypass ad blockers and provide more reliable tracking for iOS users.

Deduplication: Pinterest deduplicates events using the event_id field. If the same event_id arrives from both the tag and the API within the deduplication window, Pinterest keeps one instance. Always generate a consistent event_id and send it through both channels.

Identity matching: Pinterest matches users via the _pin_unauth cookie, hashed email, hashed phone, and the click identifier (epik) appended to landing page URLs from ad clicks. The epik parameter has a 7-day click-through attribution window.

Installing the Pinterest Tag

Add the base tag inside <head> on every page:

<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=!0,t.src=e;var
r=document.getElementsByTagName("script")[0];
r.parentNode.insertBefore(t,r)}}("https://s.pinimg.com/ct/core.js");

pintrk('load', 'YOUR_TAG_ID');
pintrk('page');
</script>
<noscript>
  <img height="1" width="1" style="display:none;" alt=""
    src="https://ct.pinterest.com/v3/?event=init&tid=YOUR_TAG_ID&noscript=1" />
</noscript>

Replace YOUR_TAG_ID with the tag ID from Pinterest Ads Manager > Conversions > Pinterest Tag.

Via Google Tag Manager: Use the Pinterest Tag template from the GTM Community Gallery. Configure the tag ID and set it to fire on All Pages. Add separate tags for conversion events with appropriate triggers.

Conversion Tracking

Standard Events

Pinterest supports a defined set of standard events. Fire them with pintrk('track'):

// Checkout / Purchase
pintrk('track', 'checkout', {
  value: 89.99,
  order_quantity: 2,
  currency: 'USD',
  line_items: [
    {
      product_name: 'Ceramic Planter',
      product_id: 'SKU-1234',
      product_category: 'Home & Garden',
      product_price: 44.99,
      product_quantity: 2
    }
  ]
});

// Add to Cart
pintrk('track', 'addtocart', {
  value: 44.99,
  currency: 'USD',
  line_items: [
    {
      product_name: 'Ceramic Planter',
      product_id: 'SKU-1234',
      product_quantity: 1
    }
  ]
});

// Page Visit (specific product or category view)
pintrk('track', 'pagevisit', {
  line_items: [
    {
      product_id: 'SKU-1234'
    }
  ]
});

// Lead / Signup
pintrk('track', 'lead', {
  lead_type: 'Newsletter'
});

// Search
pintrk('track', 'search', {
  search_query: 'modern planters'
});

// View Category
pintrk('track', 'viewcategory', {
  product_category: 'Home & Garden'
});

Full list of standard events: pagevisit, viewcategory, search, addtocart, checkout, watchvideo, signup, lead, custom.

Custom Events

For actions not covered by standard events:

pintrk('track', 'custom', {
  custom_event_name: 'wishlist_share',
  value: 0,
  currency: 'USD'
});

Custom events work for audience building but cannot be used as optimization goals for standard campaign types.

Enhanced Match

Enhanced Match sends hashed PII with tag events to improve user matching rates. Pinterest auto-hashes when passed through the pintrk('load') call:

pintrk('load', 'YOUR_TAG_ID', {
  em: 'user@example.com'  // auto-hashed to SHA-256
});
pintrk('page');

For dynamic values (e.g., after login or form submission):

pintrk('set', { em: 'user@example.com' });
pintrk('track', 'checkout', {
  value: 89.99,
  currency: 'USD'
});

Enhanced Match supports em (email) as the primary parameter. Phone number matching is available through the API for Conversions but not through the browser tag.

Automatic Enhanced Match: Enable in Pinterest Ads Manager under Conversions > Pinterest Tag > Settings. When enabled, the tag scans page forms for email fields. Explicit em parameter passing is more reliable.

Server-Side API for Conversions

The Pinterest API for Conversions sends event data from your server for improved accuracy and coverage.

Authentication

Generate an access token in Pinterest Business Hub > Apps with ads:write scope. The token is a long-lived OAuth token.

Sending Events

curl -X POST "https://api.pinterest.com/v5/ad_accounts/YOUR_AD_ACCOUNT_ID/events" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "event_name": "checkout",
        "action_source": "web",
        "event_time": 1709510400,
        "event_id": "order_789_1709510400",
        "user_data": {
          "em": ["a]c4db8a2e6..."],
          "ph": ["1a2b3c4d5e..."],
          "client_ip_address": "203.0.113.42",
          "client_user_agent": "Mozilla/5.0...",
          "click_id": "epik_value_from_cookie"
        },
        "custom_data": {
          "value": "89.99",
          "currency": "USD",
          "content_ids": ["SKU-1234"],
          "num_items": 2
        },
        "event_source_url": "https://example.com/checkout/confirm",
        "partner_name": "ss-other"
      }
    ]
  }'

Hashing requirements: Email and phone must be SHA-256 hashed before sending. Lowercase and trim whitespace from email. Phone numbers must include country code without symbols (e.g., 11234567890).

The epik cookie: Pinterest sets a first-party _epik cookie on your domain when users arrive from Pinterest ad clicks. Read this value and pass it as click_id in the API for Conversions for click-through attribution.

Deduplication with Browser Tag

Generate a unique event_id on the client and send it through both channels:

// Browser-side
var eventId = 'order_' + orderId + '_' + Date.now();
pintrk('track', 'checkout', {
  event_id: eventId,
  value: 89.99,
  currency: 'USD'
});
// Pass eventId to your server with the order data

Audience Building

Pinterest creates audiences from tag and API activity:

  • Website Visitor Audiences: Target users who visited specific pages or triggered specific events. Lookback window up to 180 days.
  • Customer List Audiences: Upload hashed emails for direct matching. Minimum 100 matches required.
  • Actalike Audiences: Pinterest's equivalent of lookalike audiences. Built from any source audience. Available in 1%-10% range of a country's Pinterest users.
  • Engagement Audiences: Target users who engaged with your organic or promoted Pins (saves, clicks, close-ups).

Audience rules example:

  • Users who viewed a product page but did not add to cart (last 14 days)
  • Users who added to cart but did not purchase (last 7 days)
  • Past purchasers for exclusion or repeat purchase campaigns

Create audiences in Pinterest Ads Manager > Audiences.

Shopping Catalog Tracking

Pinterest shopping ads pull product data from a catalog feed. The tag fires pagevisit, addtocart, and checkout events with product_id values that match your catalog feed IDs.

Catalog feed setup: Upload a product feed (XML, CSV, or TSV) to Pinterest via Catalogs in Pinterest Business Hub. Required fields: id, title, description, link, image_link, price, availability.

Matching tag events to catalog: The product_id in tag events must match the id field in your catalog feed. This links browsing and conversion behavior to specific products for dynamic retargeting.

// Product page view - product_id matches catalog feed ID
pintrk('track', 'pagevisit', {
  line_items: [
    { product_id: 'SKU-1234' }
  ]
});

Dynamic retargeting: Once the tag fires events with matching product IDs, Pinterest can serve dynamic shopping ads showing the exact products users viewed or added to cart.

Common Issues

Tag not loading: Verify the tag ID in pintrk('load'). Use the Pinterest Tag Helper Chrome extension to confirm the tag fires. Check that consent management platforms are not blocking s.pinimg.com.

No conversions recorded: Confirm the event name matches exactly (lowercase): checkout, not Checkout or purchase. Pinterest uses checkout for purchases, not purchase.

epik cookie not present: The _epik cookie is only set when users click through a Pinterest ad. It requires that your domain is verified in Pinterest Business Hub and that no redirect strips the epik URL parameter.

Low match rates on API for Conversions: Include the _epik cookie value, hashed email, IP address, and user agent. The _epik click ID provides the strongest match signal.

Catalog feed errors: Common issues include mismatched id values between the feed and tag events, prices formatted with currency symbols instead of plain numbers, and availability values that are not in stock, out of stock, or preorder.

Enhanced Match not working: Check that the email is passed before the pintrk('track') call. If using pintrk('load', id, { em: email }), the email must be available at page load time. For dynamic values, use pintrk('set', { em: email }) before tracking.

Platform-Specific Considerations

Attribution windows: Pinterest defaults to 30-day click / 30-day view attribution. Adjustable in campaign settings to 1-day, 7-day, or 30-day for both click and view. View-through attribution counts users who saw a Pin but did not click, then later converted.

Pinterest Trends integration: Pinterest Trends data (trending search terms) is available in the Ads Manager for keyword targeting. This does not affect tracking but influences campaign setup.

Verified Merchant Program: Verified merchants get a blue checkmark and access to enhanced shopping features. Requires domain verification, active catalog feed, and compliance with Pinterest's merchant guidelines. Tag installation is a prerequisite.

Data processing: Pinterest processes tag and API data with up to a 24-hour delay for reporting. Real-time conversion counts in the Ads Manager may lag behind actual events. Use the Events Manager > Test Events tool for immediate validation during implementation.

Consent mode: Pinterest's tag supports a limited consent mode. Call pintrk('disableTracking') before pintrk('load') to prevent cookies from being set until consent is granted. Re-enable with pintrk('enableTracking').

Back to top