📘
The Pinterest Ads integration via MetaRouter enables comprehensive tracking of user actions post-interaction with Promoted Pins. MetaRouter collects and enriches web event data, incorporating key user information and managing first-party cookies to ensure accurate tracking. This data is transmitted to Pinterest's conversion tracking endpoints through unauthenticated GET requests, allowing for precise attribution and audience targeting. This integration helps measure return on ad spend (RoAS) and build targeted audiences, enhancing the effectiveness of your Pinterest advertising campaigns.
Product Type: Advertising
Integration Type: Starter Kit & ID Sync
Event Source Type: Web
Event Scope: Full-Funnel Events
- MetaRouter solves identity for the Pinterest Ads integration by grabbing the
pin_unauth, epik, and derived_epik cookies via the sync injector via a GET request. In addition, MetaRouter also passes the user agent for matching. Though IP is not required, it will be essential for geo-reporting.
pin_unauth - A first-party cookie placed by the Pinterest tag when we are unable to match the user. It contains a unique UUID to group actions across pages.epik - A query parameter found in the URL when a person visits a page from a Pinterest ad. When someone clicks on a Pinterest ad, information is added to the URL to help the Pinterest tag find a match. The Pinterest tag caches this information in this first-party cookie.derived_epik - Placed when the Pinterest tag reports a match identified without using cookies, such as through enhanced match. The Pinterest tag caches information to make matching on future pages easier.
- Track user actions post-ad engagement through Pinterest Ads reporting.
- Measure and optimize return on ad spend (RoAS) through Pinterest Ads reporting.
- Create targeted audiences in Pinterest Ads based on user interactions.
- In our testing, requests above ~20,000 characters in the URL began to fail. While this isn't a formally documented limit, it may be a practical constraint to consider when using this integration.
- All values must be URL-encoded and arrays pipe-delimited.
- One request per event; batching not supported.
- Complex lists (e.g., products) must be pipe-delimited.
- A SHA-256 hashed email (
em) can be added as a Global or Event Specific mapping to improve match rates via Pinterest's enhanced match.
- Server-side events are sent via HTTP forward uses unauthenticated GET requests.
- This integration is for web events only.
- Pinterest tag will still need to be implemented to grab the
pin_unauth and derived_epik cookies.
Pinterest Ads Integration
- Uses unauthenticated GET requests, eliminating the need for complex API authentication processes.
- Uses
pin_unauth first-party cookie and user agent as the main identifiers. Also uses epik and derived_epik as additional identifiers.
Pinterest CAPI Integration
- Uses authenticated API requests which provides enhanced security and verification for data being sent to Pinterest.
- Offers robust mechanisms for handling sensitive user data securely.
- Uses either IP and user agent combo and/or hashed email as identifiers. In addition, you may use the Pinterest CAPI sync to send
epik and external_id for increased user matching.
- Captures the
pin_unauth, epik, and derived_epik cookie values used for user matching and attribution.
- Required by Pinterest to associate events with users and prior ad clicks.
- Without this sync, events may not be accurately reflected in reporting.
- To collect the sync values (e.g.,
pin_unauth, epik, derived_epik), you must implement a Pinterest Ads ID sync. Refer to the following documentation to complete the setup: Pinterest Ads - ID Sync Guide.
- Grant MetaRouter access to your Pinterest Ads account:
- Navigate to Business Access > Partners and click "Add Partner."
- Enter
1142577505371214964 for the Partner ID and select "Invite this partner to access your ad accounts and tools."
- After seeing the Success message, click "Assign Assets."
- For each ad account, turn on the "Analyst" permission and click "Assign Permissions."
- Notify your Customer Success Manager once complete. The partner connection appears only after MetaRouter accepts the invitation.
- Pixel ID: In Pinterest Business Manager, go to Conversions > Tag Manager, then use "Install the Pinterest tag manually" to view your Tag ID. This ID is used as your Pixel ID in the sync.
- From the integration library, add a Pinterest Ads integration. Then, fill out the Connection Parameters:
| Connection Parameter | Description |
|---|
TAG_ID | Your pixel ID. |
- MetaRouter provides all of the event mappings that Pinterest Ads integrations typically require. You may add custom events, parameters, or mappings in accordance with Pinterest Ads' API documentation.
- In the Pipelines tab, add your Pinterest Ads integration.
- Select the correct integration revision.
- Click Add Integration to finalize deployment.
Global mappings will be applied to all events. If your parameter names do not match the Expected Inputs provided, you will need to overwrite the Inputs provided with your own.
| Output Key | Description | Expected Input |
|---|
noscript | String: Indicates whether the browser supports JavaScript. | Enrichment – '1' |
tid Required | String: The unique tag ID assigned to the Pinterest tag. | $$TAG_ID$$ |
cb Required | Integer: A cache-busting timestamp to prevent caching of the request. | Enrichment – event timestamp in seconds |
client_ip Required | String: The IP address of the client. | context.ip |
pd[derived_epik] | String: The derived epik parameter from the Pinterest provider. | context.providers.pinterest.epik |
ad[loc] Required | String: The URL of the current page. | context.page.url |
ad[ref] | String: The referrer URL of the current page. | context.page.referrer |
ed[page_url] Required | String: The URL of the current page. | context.page.url |
| Output Key | Description | Expected Input |
|---|
event Required | String: Indicates a page visit event. | Enrichment – 'pagevisit' |
ed[page_name] | String: The name of the page. | properties.name |
ed[page_category] | String: The category of the page. | properties.category |
| Output Key | Description | Expected Input |
|---|
event Required | String: Indicates a search event. | Enrichment – 'search' |
ed[search_query] Required | String: The search query used by the user. | properties.query |
| Output Key | Description | Expected Input |
|---|
event Required | String: Indicates a product list view event. | Enrichment – 'viewcategory' |
ed[line_items] Required | Object: Builds indexed line-item keys for each product, mapping product ID, name, category, and brand. | Expression – maps properties.products to indexed ed[line_items] keys |
| Output Key | Description | Expected Input |
|---|
event Required | String: Indicates a product view event. | Enrichment – 'pagevisit' |
ed[currency] Required | String: The currency of the product price. | properties.currency (uppercased) |
ed[line_items][0] Required | Object: Builds line-item keys for the viewed product, mapping product ID, name, category, brand, and price. | Expression – maps properties to ed[line_items][0] keys |
| Output Key | Description | Expected Input |
|---|
event Required | String: Indicates an add to cart event. | Enrichment – 'addtocart' |
ed[value] Required | Number: The total value of the added product(s). | Expression – price × quantity |
ed[currency] Required | String: The currency of the product price. | properties.currency (uppercased) |
ed[order_quantity] | Integer: The quantity of the added product(s). | properties.quantity (default 1) |
ed[line_items][0] Required | Object: Builds line-item keys for the added product, mapping product ID, name, category, brand, price, and quantity. | Expression – maps properties to ed[line_items][0] keys |
| Output Key | Description | Expected Input |
|---|
event Required | String: Indicates a cart view event. | Enrichment – 'pagevisit' |
ed[value] Required | Number: The total value of the cart. | Expression – sums price × quantity across properties.products |
ed[currency] Required | String: The currency of the cart value. | properties.currency (uppercased) |
ed[order_quantity] | Integer: The total quantity of items in the cart. | Expression – sums quantity across properties.products |
ed[line_items] Required | Object: Builds indexed line-item keys for each cart product, mapping product ID, name, category, brand, price, and quantity. | Expression – maps properties.products to indexed ed[line_items] keys |
| Output Key | Description | Expected Input |
|---|
event Required | String: Indicates an order completion event. | Enrichment – 'checkout' |
ed[order_id] | String: The ID of the order. | properties.order_id |
ed[value] Required | Number: The total value of the order. | Expression – sums price × quantity across properties.products |
ed[currency] Required | String: The currency of the order. | properties.currency (uppercased) |
ed[order_quantity] | Integer: The total quantity of items in the order. | Expression – sums quantity across properties.products |
ed[promo_code] | String: The promo code used in the order. | properties.coupon |
ed[line_items] Required | Object: Builds indexed line-item keys for each order product, mapping product ID, name, category, brand, price, and quantity. | Expression – maps properties.products to indexed ed[line_items] keys |
These identifiers must be mapped to Pinterest Ads in order for successful user matching to occur. Without these IDs, any events sent to Pinterest Ads may not be accurately reflected in reporting. For your convenience, required and recommended IDs are mapped as Global parameters to ensure they are added to every event.
| Attribute | Example | Sync Injector Required? |
|---|
pin_unauth Required | dWlkPU1EQTRaakkyTldNdE5UTmxZUzAwT1dRd0xXRTRPVGt0WkdRMllqQXpOakV4WlRSaA | Yes |
epik Recommended | EAabc1234 | Yes |
derived_epik Recommended | ABC123456789 | Yes |
ip Recommended | 192.168.1.1 | No |
user_agent Required | Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36 | No |
Coordinate with your Pinterest representative, or use the Pinterest Ads dashboard, to confirm that events are being received and processed correctly on their backend.
