Pinterest Conversions API for Shopify: a setup guide

The Pinterest Conversions API is Pinterest's server-to-server way to send conversion events. Your store, or a tool such as ROASaurus, sends events like purchases straight to your Pinterest ad account, instead of relying only on the Pinterest Tag in the shopper's browser. Pinterest uses the data for conversion reporting, campaign optimization and targeting.

This guide covers the v5 API and the events it accepts, the epik click id, how customer data is hashed, how deduplication with the Pinterest Tag works, how to test, and how to set it all up on Shopify.

What is the Pinterest Conversions API?

The Pinterest Tag is a script in the shopper's browser. The Conversions API does the same job from a server. In API version 5, you send events to the events endpoint of your ad account, authorized with a conversion access token that you create in Pinterest Ads Manager. Each event says where it happened: for a webshop, the action source is web.

Pinterest asks advertisers who also use the Tag to avoid counting a conversion twice, by passing an event_id with each event. It also asks for events in real time, or at most one hour after they happen.

On Shopify, a server connection has one clear advantage: purchases come from the order itself. Shopify reports each paid order to ROASaurus by webhook, and ROASaurus sends it to Pinterest shortly after payment, whether or not the Tag fired in the browser. The guide to server-side tracking on Shopify explains the idea in more depth.

Which events does the Pinterest Conversions API accept?

Pinterest has a fixed list of standard event names, written in lowercase with underscores, such as page_visit, add_to_cart and checkout. You can also define up to 15 custom event types per advertiser. ROASaurus maps the five Shopify shopping events like this:

The name can be confusing. Pinterest's checkout is the finished purchase, not the start of checkout. The start of checkout is a separate event, initiate_checkout.

For the checkout event, Pinterest recommends sending the value, the currency, the order id, the content ids and the number of items. ROASaurus sends all five, plus each item's quantity and price. Pinterest asks for the value before tax and shipping. On Shopify, ROASaurus sends exactly that: the order total minus tax and shipping, from the server and from the browser tag. When a webshop platform does not report tax and shipping separately, ROASaurus sends the order total.

How does Pinterest match an event to a person?

Every event carries user data. Pinterest requires at least one of three things: a hashed email address, a hashed mobile advertising id, or the IP address together with the user agent. A webshop has no advertising id, so it needs the email or the IP address and user agent. ROASaurus skips an event that has neither, instead of sending one Pinterest cannot use.

The epik click id

The Pinterest click id can come from two places: an epik parameter in the landing page URL, or the _epik cookie on your domain. Pinterest's API guide recommends passing the _epik cookie value, because it still works when the URL parameter is missing or removed, which gives better coverage.

ROASaurus reads both on your storefront, using the URL parameter when a new click brings one and the cookie otherwise. It stores the click id with the visitor and sends it in the click_id field of each server event, including the purchase. Visits with an epik count as Pinterest visits in ROASaurus attribution reports.

POST https://api.pinterest.com/v5/ad_accounts/549755885175/events

{
  "data": [{
    "event_name": "checkout",
    "action_source": "web",
    "event_time": 1793016000,
    "event_id": "order-5512345678901",
    "event_source_url": "https://example-store.com/checkouts/…/thank-you",
    "user_data": {
      "em": ["a3f1…9c2e"],
      "ph": ["7b40…11d8"],
      "external_id": ["e05c…4a7f"],
      "client_ip_address": "203.0.113.24",
      "client_user_agent": "Mozilla/5.0 (iPhone; …)",
      "click_id": "dj0yJnU9…"
    },
    "custom_data": {
      "currency": "USD",
      "value": "84",
      "order_id": "5512345678901",
      "content_ids": ["44123456789"],
      "contents": [{ "id": "44123456789", "quantity": 2, "item_price": "42" }],
      "num_items": 2
    }
  }]
}

How does deduplication with the Pinterest Tag work?

If the Tag and the API both report a purchase, Pinterest receives two events for one order. To treat them as one, it needs the same id on both sides: the event id in the Tag must match the event_id in the server event. Pinterest keeps the first event it receives and removes duplicates that arrive within 48 hours.

ROASaurus builds the purchase id from the Shopify order id. The purchase from order 5512345678901 has the event id order-5512345678901, in the Tag that fires in checkout and in the server event.

All five events are deduplicated

Each shopping event in ROASaurus has one event id, used by the Tag in the browser and by the server event. The Tag uses Pinterest's own names for the same events: pagevisit, viewcontent, addtocart, initiatecheckout and checkout, which match page_visit, view_content, add_to_cart, initiate_checkout and checkout in the API. So when both run, Pinterest keeps one copy of each page visit, product view, add to cart, checkout start and purchase.

You can run it in two ways:

• Tag and Conversions API together. The Tag adds browser signals, the server fills in what the Tag misses, and Pinterest merges the copies.
• Run the API without the Tag. Leave the Tag ID empty or switch off Also load the browser tag. Every event is then sent once, from the server only.

The help article on double counting covers the same checks for the other ad platforms.

How do you test the Pinterest Conversions API?

The API has a test flag. Requests sent with test=true go to a sandbox: Pinterest handles them as test data and does not use them for reporting or optimization.

1. Switch on test mode

   In ROASaurus, edit the Pinterest pixel under Tracking & platforms and tick Test mode (events show under Test events, max 20). Every server event is then sent with test=true. Pinterest processes at most 20 test events per batch.

2. Place a test order

   Visit your store, view a product, add it to the cart and complete an order.

3. Read the result

   Open the Event log. Pinterest can answer HTTP 200 while one event in a request failed, so ROASaurus checks the status of each event and shows failures there.

4. Switch test mode off

   Untick test mode, so events count in reporting and optimization.

5. Check the Events Overview

   In Pinterest Ads Manager, open the Events Overview page. It shows the events that arrive and the deduplicated conversions. Pinterest recommends aiming for a Good Event Quality Score.

How to set up the Pinterest Conversions API on Shopify with ROASaurus

You need a Shopify store with the ROASaurus app and access to Pinterest Ads Manager. The Pinterest integration page lists every field ROASaurus sends.

1. Connect your Shopify store

   Go to Add a store › Shopify, click Install app and switch on the ROASaurus app embed in the theme editor. It captures epik and the _epik cookie on every page. The Shopify setup guide shows each step.

2. Create a conversion access token

   In Pinterest Ads Manager, go to Conversions and create a conversion access token. Note your ad account ID.

3. Add the Pinterest pixel in ROASaurus

   Go to Tracking & platforms, click Add pixel on the Pinterest card and fill in Ad account ID and Conversion access token.

4. Add your Tag ID

   For deduplication with the Tag, fill in Pinterest Tag ID and keep Also load the browser tag ticked. Without a Tag ID, ROASaurus sends server events only and does not load the Tag.

5. Add the checkout pixel

   In Shopify admin › Settings › Customer events, add a custom pixel named ROASaurus and paste the snippet from your Tracking & platforms page. It fires the Tag's checkout event in Shopify's checkout, with the order id as event_id.

6. Choose server events, then test

   Pick the server events you want and test with test mode before you go live.

With Respect visitor consent on, which is the default, ROASaurus follows the shopper's choice in Shopify's cookie banner. When a shopper declines marketing cookies, ROASaurus does not load the Pinterest Tag for them, sets no visitor id, so their clicks are not linked to them, and does not send their browsing events to Pinterest. Their paid order is still sent to the Conversions API from the server, with hashed order data and the order's IP address and user agent, but without a click id. The consent and privacy guide explains what is stored and sent.

Connect your Pinterest ad account under Setup › Ad spend and ROASaurus pulls campaign spend every hour, so you see Pinterest ROAS and profit after ads in profit analytics. The TikTok Events API guide covers the same setup for TikTok, where every event that goes both ways is deduplicated.

Sources

1. Pinterest Developers: Track conversion events in the API
2. Pinterest Business help: The Pinterest Conversions API
3. Pinterest Developers: Track conversions with Pinterest Tag

In ROASaurus

• Pinterest integration
• Server-side tracking in ROASaurus
• Help: prevent double counting

Keep reading