Pinterest Ads Integration

Reach high-intent shoppers on the world's visual discovery platform. Pinterest users actively search for ideas, products, and inspiration -- making them significantly more likely to convert than users on other social platforms. ILLIXIS connects to the Pinterest Marketing API v5 to sync your retargeting audiences as Customer Lists, create full campaign hierarchies (campaign, ad group, ad), and track conversions server-to-server.

What It Does

Pinterest is a visual search engine, not a traditional social network. Users come to Pinterest with purchase intent -- they search for "living room ideas," "summer outfits," or "meal prep recipes" and save what they find. This makes Pinterest advertising uniquely effective for product discovery and shopping.

ILLIXIS integrates with Pinterest Ads at the API level. You connect your Pinterest Business account, and ILLIXIS handles audience syncing, campaign creation, and conversion tracking through automated background tasks. Your retargeting audiences from Advertising sync directly to Pinterest as Customer List audiences, so you can target your existing contacts with promoted Pins.

The integration supports the full campaign creation pipeline: campaigns with objective-based optimization, ad groups with budget and bid controls, and ads that promote your existing Pins. Conversion tracking runs server-to-server through Pinterest's Conversions API, so you get accurate attribution without relying on browser pixels.

Prerequisites

| Requirement | Details |
|-------------|---------|
| Pinterest Business Account | Free to create at business.pinterest.com. Personal accounts cannot run ads. |
| Pinterest Ad Account | Created inside your Business account. You need the Ad Account ID. |
| OAuth Access Token | Generated through Pinterest's app developer portal. Access tokens are valid for 30 days. |
| Refresh Token | Optional but recommended. Valid for 1 year. Allows ILLIXIS to renew access without manual re-authentication. |
| Required OAuth Scopes | ads:read, ads:write |

Connecting Your Account

1. Go to Settings > Integrations and find the Pinterest Ads card under the Advertising tab.
2. Click Connect Pinterest.
3. Enter your OAuth access token. If you have a refresh token, enter that too.
4. ILLIXIS validates the token by fetching your ad accounts from https://api.pinterest.com/v5/ad_accounts.
5. If validation succeeds, ILLIXIS stores the connection with your first ad account's ID and name.
6. The Pinterest dot on your Advertising dashboard turns green.

Getting your access token:

Pinterest uses OAuth 2.0. To generate tokens:

1. Go to developers.pinterest.com and create an app (or use an existing one).
2. Set your app's redirect URI.
3. Complete the OAuth authorization flow to receive an access token and refresh token.
4. Copy both tokens into the ILLIXIS connection form.

Multiple ad accounts: If your Pinterest Business account has multiple ad accounts, ILLIXIS connects to the first one returned by the API. To use a different ad account, disconnect and reconnect with a token scoped to that account.

Disconnecting

1. Go to Settings > Integrations > Pinterest.
2. Click Disconnect.
3. ILLIXIS marks the connection as inactive and clears stored tokens. Existing synced audiences in Pinterest are not deleted -- they remain in your Pinterest Ads Manager.

Syncing Audiences

ILLIXIS syncs your retargeting audiences to Pinterest as Customer List audiences. These are first-party data audiences built from email addresses.

How It Works

1. Go to Advertising and find the audience you want to sync.
2. Click the Pinterest sync button on the audience card.
3. ILLIXIS queues a background task that:

• Extracts email records from the audience's analysis data
• Creates a Customer List in Pinterest with the email records
• Creates a Pinterest Audience linked to that Customer List
• Updates the audience record with the Pinterest Audience ID and sync status

Sync Statuses

| Status | Meaning |
|--------|---------|
| Not Synced | Audience has not been sent to Pinterest |
| Syncing | Background task is running |
| Synced | Audience is live in Pinterest Ads Manager |
| Error | Sync failed -- check the error message |

Bulk Sync

To sync all audiences at once, ILLIXIS provides a bulk sync that queues individual tasks for every active audience that hasn't been synced yet or previously errored.

Updating Audiences

If an audience already has a Pinterest Audience ID, subsequent syncs update the existing Customer List by adding new records rather than creating a duplicate list.

Customer List Types

| Type | Description |
|------|-------------|
| EMAIL | Email addresses (default). Pinterest hashes them for matching. |
| MAID | Mobile Advertising IDs (iOS IDFA / Android GAID) |
| IDFA | iOS-specific advertising identifiers |

ILLIXIS uses EMAIL by default. The sync function passes raw email addresses, and Pinterest handles hashing on their end during Customer List creation.

Creating Campaigns

ILLIXIS creates Pinterest campaigns through a three-level hierarchy: Campaign > Ad Group > Ad. Each level is created via a separate background task.

Step 1: Create a Campaign

ILLIXIS creates a campaign with these parameters:

| Parameter | Options | Notes |
|-----------|---------|-------|
| Objective | AWARENESS, CONSIDERATION, VIDEO_VIEW, WEB_CONVERSION, CATALOG_SALES, SHOPPING | Determines how Pinterest optimizes delivery |
| Daily Spend Cap | Amount in micro-currency | 5,000,000 = $5.00 USD |
| Lifetime Spend Cap | Amount in micro-currency | Total budget for campaign lifetime |
| Status | ACTIVE, PAUSED | Start running immediately or set up first |

Micro-currency: Pinterest's API uses micro-currency units. Multiply dollar amounts by 1,000,000. For example, a $50 daily budget = 50,000,000 in micro-currency.

Step 2: Create an Ad Group

The ad group sets budget, bidding, and targeting:

| Parameter | Options | Notes |
|-----------|---------|-------|
| Budget | Micro-currency amount | Default: $5 (5,000,000) |
| Bid | Micro-currency amount | Default: $2 (2,000,000) |
| Billable Event | IMPRESSION, CLICKTHROUGH, VIDEO_V_50_MRC | What you pay for |
| Targeting | Interest, keyword, audience, demographic, geographic | Passed as a targeting spec dict |
| Start/End Time | Unix timestamps | Schedule when the ad group runs |

Step 3: Create an Ad (Promoted Pin)

The ad creation step promotes an existing Pin:

| Parameter | Options | Notes |
|-----------|---------|-------|
| Pin ID | Your existing Pin ID | The Pin you want to promote |
| Creative Type | REGULAR, VIDEO, SHOPPING | Matches the Pin format |
| Click Tracking URL | URL | Optional click tracking for attribution |

You must have an existing Pin to promote. Pinterest Ads does not create content -- it promotes Pins that already exist on your boards.

Campaign Objectives

| Objective | Best For | Optimization |
|-----------|----------|-------------|
| AWARENESS | Brand visibility | Maximizes impressions |
| CONSIDERATION | Traffic and engagement | Maximizes clicks and saves |
| VIDEO_VIEW | Video content promotion | Maximizes video views |
| WEB_CONVERSION | Sales and signups | Maximizes conversion events |
| CATALOG_SALES | E-commerce product feeds | Promotes products from your catalog |
| SHOPPING | Direct product promotion | Drives purchases |

Ad Formats

Pinterest ads are promoted Pins. The format depends on the type of Pin you create:

| Format | Description | Best For |
|--------|-------------|----------|
| Standard Pin (Image) | Single image with title, description, and destination URL | Blog posts, landing pages, product highlights |
| Video Pin | Autoplay video (4 sec - 15 min) in the feed | Tutorials, demonstrations, storytelling |
| Carousel Pin | 2-5 swipeable images, each with its own link | Multiple products, step-by-step guides |
| Shopping Pin | Product Pin with price, availability, and buy link | E-commerce products from your catalog |
| Collage Pin | Multi-image creative combining multiple visuals | Mood boards, lifestyle imagery, collections |

Image specs:

• Recommended aspect ratio: 2:3 (1000 x 1500 px)
• Maximum file size: 20 MB (images), 2 GB (videos)
• Supported formats: PNG, JPEG (images); MP4, MOV (videos)

Audience Targeting

From ILLIXIS Audiences

Your synced Customer List audiences can be used directly in ad group targeting. These are your highest-value audiences because they already know your brand.

Actalike Audiences (Pinterest's Lookalike)

Pinterest calls their lookalike audiences "Actalike." After syncing a Customer List, you can create an Actalike audience in Pinterest Ads Manager that finds users with similar interests and behaviors.

Interest Targeting

Pinterest offers interest categories based on what users search for and save. Target by topic (e.g., "Home Decor," "Fitness," "Recipes") to reach users actively exploring those categories.

Keyword Targeting

Unlike most social platforms, Pinterest supports keyword targeting. Users search Pinterest like a search engine, so you can target specific search terms (e.g., "minimalist desk setup," "easy dinner recipes").

Demographic Targeting

Standard demographic filters: age, gender, location, language, device.

Conversion Tracking (CAPI)

ILLIXIS tracks conversions server-to-server through Pinterest's Conversions API (CAPI). This is more reliable than browser-based pixels because it works even when cookies are blocked or users switch devices.

How It Works

ILLIXIS sends conversion events directly to Pinterest:

1. A conversion happens on your site (purchase, signup, lead form).
2. ILLIXIS fires a background task with the event details.
3. The task sends the event to Pinterest's /ad_accounts/{id}/events endpoint.
4. Pinterest matches the event to the ad impression using hashed email data.

Supported Events

| Event | When to Use |
|-------|-------------|
| checkout | Purchase completed |
| lead | Lead form submitted |
| signup | Account created |
| add_to_cart | Product added to cart |
| page_visit | Key page viewed |
| search | Site search performed |
| view_category | Category page viewed |

Event Data

Each conversion event can include:

| Field | Description |
|-------|-------------|
| email | User email (SHA256 hashed automatically by ILLIXIS) |
| event_id | Unique ID for deduplication -- prevents double-counting |
| value | Revenue amount (e.g., 49.99) |
| currency | Currency code (default: USD) |
| order_id | Order identifier for purchase events |
| event_time | Unix timestamp (defaults to current time) |

Deduplication: Always pass an event_id to prevent the same conversion from being counted twice. Pinterest uses this to deduplicate events sent from both browser pixels and CAPI.

Token Management

Pinterest OAuth tokens expire. ILLIXIS handles this, but you should understand the timeline:

| Token Type | Validity | What Happens When It Expires |
|------------|----------|------------------------------|
| Access Token | 30 days | API calls return 401. ILLIXIS marks connection as unauthorized. |
| Refresh Token | 1 year | Must reconnect manually through Settings > Integrations. |

Automatic Token Refresh

When ILLIXIS detects an access token is about to expire (within 1 day of expiration), it uses the refresh token to obtain a new access token. This happens automatically if a refresh token is stored.

Manual Reconnection

If both tokens expire (access token expired and no refresh token, or refresh token also expired after 1 year):

1. Generate a new access token through Pinterest's developer portal.
2. Go to Settings > Integrations > Pinterest.
3. Disconnect the existing connection.
4. Reconnect with the new tokens.

Token Status Check

The connection model tracks is_token_valid with a 1-day buffer. If token_expires_at is less than 1 day from now, is_token_valid returns false, triggering a refresh attempt.

Automation Schedule

ILLIXIS automatically manages your Pinterest Ads integration on a regular schedule:

| Data Type | Frequency | Timing |
|-----------|-----------|--------|
| Audience Sync (new/updated audiences) | Daily | 6:00 AM UTC |
| Campaign Performance Metrics | Every 6 hours | 12:00 AM, 6:00 AM, 12:00 PM, 6:00 PM UTC |
| Conversion Event Processing | Real-time | Sent as events occur |
| Token Refresh Check | Daily | 5:00 AM UTC |

What this means for you:

• Morning data: By 6:00 AM UTC, any new audience members are synced to Pinterest and token health is verified.
• Performance tracking: Campaign metrics refresh four times daily. Check after any refresh window for the most current data.
• Conversions: Sent immediately when they happen. No batch delay.
• Token health: Checked daily. If your access token is expiring within 24 hours and you have a refresh token, it renews automatically.

Troubleshooting

"Invalid access token" on Connect

Cause: The access token you entered is expired, revoked, or incorrectly copied.

Fix:

1. Generate a fresh access token from Pinterest's developer portal.
2. Make sure you copy the full token string without extra spaces.
3. Verify your Pinterest app has the ads:read and ads:write scopes.

"No ad accounts found"

Cause: Your Pinterest token is valid but not associated with any ad account.

Fix:

1. Log into Pinterest Business and confirm you have an ad account (not just a business profile).
2. Create an ad account at ads.pinterest.com if you don't have one.
3. Ensure your Pinterest app is connected to the correct business account.

Audience Sync Shows "Error"

Cause: Usually means no email records were available, or the API rejected the data.

Fix:

1. Check the audience detail page for the specific error message.
2. Verify the audience has email data in its analysis_data.
3. Minimum audience size for Pinterest Customer Lists is 100 emails. Smaller lists may be rejected.
4. Retry the sync -- transient API errors auto-retry up to 3 times.

Campaign Not Delivering

Cause: Budget too low, targeting too narrow, or creative not approved.

Fix:

1. Check campaign status in Pinterest Ads Manager.
2. Pinterest has no minimum spend, but budgets below $5/day often deliver slowly.
3. Verify your promoted Pin follows Pinterest's ad policies (no misleading claims, no before/after images for health products).
4. Broaden targeting -- add interest categories or expand geographic targeting.

Conversions Not Matching

Cause: Email mismatch between the conversion event and the ad impression.

Fix:

1. Ensure the email used in the conversion event matches what was used in the Customer List.
2. ILLIXIS SHA256-hashes emails automatically. Do not pre-hash them.
3. Always pass an event_id for deduplication.
4. Check the Pinterest Ads Manager conversion report for a 24-48 hour attribution window.

Connection Shows "Unauthorized"

Cause: Access token expired (30-day limit) and no refresh token was stored, or refresh token also expired.

Fix:

1. Go to Settings > Integrations > Pinterest.
2. Disconnect the current connection.
3. Generate a new access token from Pinterest's developer portal.
4. Reconnect with both an access token and a refresh token to avoid this in the future.

API Rate Limits

Pinterest API v5 allows 100 calls per second per user per app. ILLIXIS stays well within this limit under normal operation. If you trigger bulk operations (syncing many audiences simultaneously), tasks are queued and processed sequentially with automatic retry on rate limit errors (HTTP 429).

Related Features

• Advertising: Manage all ad platform integrations from one dashboard
• Prospecting Campaigns: Create campaigns targeting new audiences across platforms
• Lookalike Audiences: Build lookalike/actalike audiences from your customer data