Pinterest is a visual discovery and bookmarking platform where users can find, save, and share ideas and inspirations. It allows users to create and organize collections of images, known as "pins," into thematic boards. These pins can link back to the original source, making Pinterest a powerful tool for discovering new content, planning projects, and finding creative inspiration. The platform is widely used for ideas on fashion, recipes, home decor, and more, catering to both personal interests and professional marketing.
Pinterest Conversion API (CAPI) is a tool that helps businesses track user interactions on their websites more accurately by sending events directly from their servers to Pinterest. This API enables better measurement of conversion actions, such as purchases or sign-ups, without relying solely on browser-based tracking, which can be affected by ad blockers or cookie restrictions. By using CAPI, businesses can gain deeper insights into the performance of their Pinterest campaigns, improve ad targeting, and optimize their marketing strategies for better results.
Product Type: Advertising
Integration Type: Starter Kit & ID Sync
Event Source Type: Web, Mobile Browser, and Mobile App
Event Scope: Full-Funnel Events
- Sends server-side conversion events directly to Pinterest's Conversions API, reducing the impact of ad blockers and cookie restrictions.
- Supports full-funnel events including page, product, cart, and order lifecycle actions.
- Sends hashed user identifiers (email, city, state, zip, country, external ID) for privacy-safe matching.
- Captures the
epik click ID via the sync for attribution.
- Derives the action source (
web, app_ios, or app_android) from event context.
- Supports batch delivery of up to 500 events per request.
- Authentication uses a Bearer conversion access token scoped to your Pinterest ad account.
- Each event must include either the hashed email (
em) or the IP address and user agent combination for Pinterest to match it to a user.
- Additional hashed match identifiers — mobile advertising ID (
hashed_maid), phone (ph), gender (ge), date of birth (db), last name (ln), and first name (fn) — can be added as Global or Event Specific mappings to improve match rates. These are recommended on checkout events at minimum.
- Captures the
epik click ID value used for conversion attribution.
- Required by Pinterest to associate events with prior ad clicks.
- Without this sync, conversions may not be accurately attributed in reporting.
- To collect the sync values (e.g.,
epik), you must implement a Pinterest CAPI ID sync. Refer to the following documentation to complete the setup: Pinterest CAPI - ID Sync Guide.
- Ad Account ID & Access Token: In Pinterest Business Manager, go to Conversions > API for Conversions, select "Conversion access token," and click Generate new token. Your Ad Account ID is displayed alongside the new token.
- 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 CAPI integration. Then, fill out the Connection Parameters:
| Connection Parameter | Description |
|---|
AD_ACCOUNT_ID | Your Pinterest ad account ID. |
ACCESS_TOKEN | Your conversion access token. |
- MetaRouter provides all of the event mappings that Pinterest CAPI integrations typically require. You may add custom events, parameters, or mappings in accordance with Pinterest CAPI's API documentation.
- In the Pipelines tab, add your Pinterest CAPI 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 |
|---|
partner_name Required | String: The third-party partner name responsible for sending the event to the Conversions API on behalf of the advertiser. | Enrichment – 'MetaRouter' |
action_source Required | String: Describes the source of the action or event (web, app_ios, or app_android). | Expression – derived from event context |
event_time Required | Integer: The timestamp of when the event occurred, in Unix time (seconds). | Expression – converts the event timestamp to seconds since epoch |
event_id Required | String: A unique identifier for the event, used for deduplication. | messageId |
event_source_url | String: The URL of the webpage where the event occurred. | context.page.url |
user_data.em Required | Array: User email address, SHA-256 hashed. | Expression – hashes trimmed, lowercased traits.email |
user_data.client_ip_address Required | String: The IP address of the user. | context.ip |
user_data.client_user_agent Required | String: The user agent string of the user's browser. | context.userAgent |
user_data.ct | Array: User city, SHA-256 hashed. | Expression – hashes traits.city |
user_data.st | Array: User state, SHA-256 hashed. | Expression – hashes traits.state |
user_data.zp | Array: User zip code, SHA-256 hashed. | Expression – hashes traits.zipcode |
user_data.country | Array: User country, SHA-256 hashed. | Expression – hashes traits.country |
user_data.external_id Highly Recommended | Array: An external ID for the user (hashed), used to match user data with other systems. | Expression – hashes anonymousId |
user_data.click_id Highly Recommended | String: A unique identifier for the user's click, used for tracking ad clicks. | context.providers.pinterestCAPI.epik |
| Output Key | Description | Expected Input |
|---|
event_name Required | String: Name of the event. | Enrichment – 'page_visit' |
| Output Key | Description | Expected Input |
|---|
event_name Required | String: Name of the event. | Enrichment – 'search' |
custom_data.search_string Required | String: The search string used by the user. | properties.query |
| Output Key | Description | Expected Input |
|---|
event_name Required | String: Name of the event. | Enrichment – 'view_category' |
custom_data.content_ids Required | Array: List of product IDs in the event. | Expression – maps product IDs from properties.products |
custom_data.contents Required | Array: Details of the contents, each with id, item_price, and quantity. | Expression – maps properties.products to content objects |
| Output Key | Description | Expected Input |
|---|
event_name Required | String: Name of the event. | Enrichment – 'page_visit' |
custom_data.currency Required | String: Currency of the transaction. | properties.currency (uppercased, default USD) |
custom_data.value Required | String: Total value of the transaction. | Expression – price × quantity |
custom_data.content_ids Required | Array: List of product IDs in the event. | Expression – builds from properties.product_id |
custom_data.contents Required | Array: Details of the contents, each with id, item_price, and quantity. | Expression – builds from properties |
custom_data.num_items Required | Integer: Number of items in the transaction. | properties.quantity |
| Output Key | Description | Expected Input |
|---|
event_name Required | String: Name of the event. | Enrichment – 'add_to_cart' |
custom_data.currency Required | String: Currency of the transaction. | properties.currency (uppercased, default USD) |
custom_data.value Required | String: Total value of the transaction. | Expression – price × quantity |
custom_data.content_ids Required | Array: List of product IDs in the event. | Expression – builds from properties.product_id |
custom_data.contents Required | Array: Details of the contents, each with id, item_price, and quantity. | Expression – builds from properties |
custom_data.num_items Required | Integer: Number of items in the transaction. | properties.quantity |
| Output Key | Description | Expected Input |
|---|
event_name Required | String: Name of the event. | Enrichment – 'page_visit' |
custom_data.currency Required | String: Currency of the transaction. | properties.currency (uppercased) |
custom_data.value Required | String: Total value of the transaction. | Expression – sums price × quantity across properties.products |
custom_data.content_ids Required | Array: List of product IDs in the cart. | Expression – maps product IDs from properties.products |
custom_data.contents Required | Array: Details of the contents, each with id, item_price, and quantity. | Expression – maps properties.products to content objects |
custom_data.num_items Required | Integer: Number of items in the cart. | Expression – sums quantity across properties.products |
custom_data.order_id Required | String: Order ID of the transaction. | properties.order_id |
| Output Key | Description | Expected Input |
|---|
event_name Required | String: Name of the event. | Enrichment – 'checkout' |
custom_data.currency Required | String: Currency of the transaction. | properties.currency (uppercased) |
custom_data.value Required | String: Total value of the transaction. | Expression – sums price × quantity across properties.products |
custom_data.content_ids Required | Array: List of product IDs in the order. | Expression – maps product IDs from properties.products |
custom_data.contents Required | Array: Details of the contents, each with id, item_price, and quantity. | Expression – maps properties.products to content objects |
custom_data.num_items Required | Integer: Number of items in the order. | Expression – sums quantity across properties.products |
custom_data.order_id Required | String: Order ID of the transaction. | properties.order_id |
These identifiers must be mapped to Pinterest CAPI in order for successful user matching to occur. Without these IDs, any events sent to Pinterest CAPI 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? |
|---|
em * Required | d41d8cd98f00b204e9800998ecf8427e | No |
client_ip_address * Required | 192.168.1.1 | No |
client_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 |
external_id Highly Recommended | 130161d0-8fee-4167-aa4d-d151eed27c6b | No |
click_id Highly Recommended | abcdef1234567890 | Yes |
ct Recommended | bb11df46c3c14b95b79b9e4c872c1e49f73eaa9570733e499cd4f36f9fbf2e6c | No |
st Recommended | 995c9ffcc78411b9e53d206ec0a9a6f63b74b090e179dba1e4eafd922c1e95ff | No |
zp Recommended | 49557a7a840fcb6f8d11d1b276844acdd71c1c6b46c9c6e0cc5b2f43ad5c3d57 | No |
country Recommended | e6fb06210fafc02fd7479ddbed2d042cc3a5155e0d3af5ed9da5760b31e020d6 | No |
*Either the hashed email (em) or the IP address and user agent combination is required for user matching.
Coordinate with your Pinterest representative, or use the Pinterest Ads dashboard, to confirm that events are being received and processed correctly on their backend.
