Pinterest Ads

Pinterest Ads

Strategic skill for managing Pinterest Ads campaigns via the Pinterest Ads API v5 surface exposed by the Hyper MCP. Ad-group creation goes through a direct REST call (bypassing SDK model conversion) so parameter types must be sent exactly as documented — strings as strings, integers as integers.

Out of scope — defer to other skills

| Request | Send them to | | --- | --- | | Google Ads campaign | google-ads | | Meta (Facebook / Instagram) ad campaign | meta-ads | | Amazon Sponsored Products | amazon-ads | | TikTok ad campaign | tiktok-ads | | Competitor ad research from the Meta Ads Library | meta-ads-library | | Organic Pinterest pinning | not currently shipped — use the Pinterest app |

Requirements

• Hyper MCP installed and connected. https://app.hyperfx.ai/mcp
• Pinterest Ads integration connected at https://app.hyperfx.ai/integrations (Pinterest Business account with ad account access).

If pinterest_ads_list_ad_accounts is not in the tool list, stop and tell the user to enable the Hyper MCP and connect Pinterest Ads.

Tool surface

| Tool group | Tools | | --- | --- | | Accounts | pinterest_ads_list_ad_accounts, pinterest_ads_get_ad_account | | Campaigns | pinterest_ads_list_campaigns, pinterest_ads_get_campaign, pinterest_ads_create_campaign, pinterest_ads_update_campaign | | Ad groups | pinterest_ads_list_ad_groups, pinterest_ads_get_ad_group, pinterest_ads_create_ad_group, pinterest_ads_update_ad_group | | Ads | pinterest_ads_list_ads, pinterest_ads_get_ad, pinterest_ads_create_ad, pinterest_ads_update_ad | | Audiences | pinterest_ads_list_audiences, pinterest_ads_create_audience, pinterest_ads_create_customer_list | | Conversion | pinterest_ads_list_conversion_tags, pinterest_ads_create_conversion_tag, pinterest_ads_send_conversion_event | | Keywords | pinterest_ads_create_keyword | | Analytics | pinterest_ads_get_campaign_analytics |

Critical Rules

> CRITICAL: All budgets and bids are in microcurrency. $1.00 = 1,000,000 microdollars. $50/day = 50,000,000. Never pass dollar amounts directly.

> CRITICAL: When using is_flexible_daily_budgets: true, you MUST also set is_campaign_budget_optimization: true. FDB requires CBO.

> CRITICAL: Lifetime CBO campaigns MUST include end_time (Unix timestamp).

> CRITICAL: Create campaigns with status PAUSED initially. Never launch live without user review.

> CRITICAL: WEB_CONVERSION ad groups MUST use billable_event="IMPRESSION" (NOT CLICKTHROUGH) and MUST include optimization_goal_metadata with attribution_windows, conversion_event, conversion_tag_id, and cpa_goal_value_in_micro_currency.

> CRITICAL: Keyword creation REQUIRES match_type. Without it, the API returns 500 errors.

> CRITICAL: CBO campaigns manage budget at the campaign level. Do NOT set budget_in_micro_currency on ad groups under CBO campaigns.

> IMPORTANT: retention_days is deprecated for ENGAGEMENT audiences. Omit it from audience rules.

Phase 1: Account Discovery

Call pinterest_ads_list_ad_accounts() to list accessible accounts.

• If multiple: ask the user to select one.
• If single: inform the user and proceed.
• Note the ad_account_id — it's required for every subsequent tool call.

Phase 2: Account Assessment

Existing campaign audit

Run these in parallel to understand the account state:

pinterest_ads_list_campaigns(ad_account_id="")
pinterest_ads_list_ad_groups(ad_account_id="")
pinterest_ads_list_ads(ad_account_id="")
pinterest_ads_list_audiences(ad_account_id="")
pinterest_ads_list_conversion_tags(ad_account_id="")

Research & confirm

• Get the destination URL and creative assets (Pin IDs).
• Understand the campaign objective (awareness, consideration, conversions).
• Confirm daily / lifetime budget.
• Confirm target audience (geo, interests, demographics).
• If WEB_CONVERSION: ensure a conversion tag exists.

Phase 3: Campaign Structure

Pinterest campaign hierarchy

Ad Account
└── Campaign (objective, budget for CBO)
    └── Ad Group (targeting, bidding, schedule)
        └── Ad (creative Pin + tracking)

Campaign objectives

| Objective | Use case | | --- | --- | | AWARENESS | Brand visibility, impressions | | CONSIDERATION | Traffic, engagement | | VIDEO_VIEW | Video completion | | WEB_CONVERSION | Purchases, signups, leads | | CATALOG_SALES | Shopping / product catalog | | WEB_SESSIONS | Website visits |

CBO vs Non-CBO

| Setting | CBO campaign | Non-CBO campaign | | --- | --- | --- | | Budget location | Campaign level (daily_spend_cap or lifetime_spend_cap) | Ad group level (budget_in_micro_currency) | | is_campaign_budget_optimization | true | false | | Ad group budget | Managed by Pinterest | Set per ad group |

Phase 4: Campaign Creation

1. Create campaign

pinterest_ads_create_campaign(
    ad_account_id="",
    name="Spring Collection 2026",
    objective_type="WEB_CONVERSION",
    status="PAUSED",
    daily_spend_cap=50000000,
    is_campaign_budget_optimization=true,
    is_flexible_daily_budgets=true,
)

Parameter requirements:

• is_flexible_daily_budgets=true → requires is_campaign_budget_optimization=true.
• lifetime_spend_cap → requires end_time.
• All spend caps in microcurrency.

2. Create ad group

> CRITICAL: This tool sends a direct REST call to the Pinterest API v5 (bypassing SDK models). Pass parameter values exactly as documented — strings as strings, integers as integers.

> CRITICAL: Ad-group parameters depend heavily on the parent campaign's objective_type. Follow the objective-specific templates below exactly.

billable_event values: CLICKTHROUGH, IMPRESSION, VIDEO_V_50_MRC.

Objective / billable_event compatibility

| Campaign objective_type | Required billable_event | bid_in_micro_currency | optimization_goal_metadata | | --- | --- | --- | --- | | AWARENESS | IMPRESSION | REQUIRED (integer) | Not needed | | CONSIDERATION | CLICKTHROUGH | REQUIRED (integer) | Not needed | | VIDEO_VIEW | VIDEO_V_50_MRC | Optional | Not needed | | WEB_CONVERSION | IMPRESSION | Optional | REQUIRED | | CATALOG_SALES | CLICKTHROUGH | REQUIRED (integer) | Not needed | | WEB_SESSIONS | CLICKTHROUGH | Optional | Not needed |

Template: CONSIDERATION campaign (simplest, non-CBO)

pinterest_ads_create_ad_group(
    ad_account_id="",
    name="US Women 25-54",
    campaign_id="",
    billable_event="CLICKTHROUGH",
    bid_in_micro_currency=1000000,
    budget_in_micro_currency=10000000,
    targeting_spec={"LOCATION": ["US"], "GENDER": ["female"], "MINIMUM_AGE": "25", "MAXIMUM_AGE": "54"},
    bid_strategy_type="AUTOMATIC_BID",
    status="PAUSED",
)

Template: CONSIDERATION campaign (CBO — no ad group budget)

pinterest_ads_create_ad_group(
    ad_account_id="",
    name="US Women 25-54",
    campaign_id="",
    billable_event="CLICKTHROUGH",
    bid_in_micro_currency=1000000,
    targeting_spec={"LOCATION": ["US"], "GENDER": ["female"], "MINIMUM_AGE": "25", "MAXIMUM_AGE": "54"},
    bid_strategy_type="AUTOMATIC_BID",
    status="PAUSED",
)

Template: WEB_CONVERSION campaign (requires optimization_goal_metadata)

> CRITICAL: WEB_CONVERSION ad groups MUST use billable_event="IMPRESSION" (NOT CLICKTHROUGH). They MUST provide optimization_goal_metadata with the full nested structure shown below.

> TYPE SAFETY: cpa_goal_value_in_micro_currency MUST be a string (e.g., "5000000"), NOT an integer. conversion_tag_id MUST be a string. attribution_windows values MUST be integers.

pinterest_ads_create_ad_group(
    ad_account_id="",
    name="Conversion - Checkout",
    campaign_id="",
    billable_event="IMPRESSION",
    targeting_spec={"LOCATION": ["US"]},
    bid_strategy_type="AUTOMATIC_BID",
    status="PAUSED",
    optimization_goal_metadata={
        "conversion_tag_v3_goal_metadata": {
            "attribution_windows": {
                "click_window_days": 30,
                "engagement_window_days": 30,
                "view_window_days": 1,
            },
            "conversion_event": "CHECKOUT",
            "conversion_tag_id": "",
            "cpa_goal_value_in_micro_currency": "5000000",
            "is_roas_optimized": false,
        },
    },
)

conversion_event values: PAGE_VISIT, SIGNUP, CHECKOUT, CUSTOM, VIEW_CATEGORY, SEARCH, ADD_TO_CART, WATCH_VIDEO, LEAD, APP_INSTALL.

attribution_windows — only these exact combos are accepted (click / engage / view):

| click_window_days | engagement_window_days | view_window_days | Shorthand | | --- | --- | --- | --- | | 30 | 30 | 30 | 30/30/30 | | 30 | 30 | 7 | 30/30/7 | | 30 | 30 | 1 | 30/30/1 (default) | | 7 | 7 | 7 | 7/7/7 | | 7 | 7 | 1 | 7/7/1 | | 7 | 0 | 0 | 7/0/0 | | 1 | 1 | 1 | 1/1/1 | | 1 | 0 | 0 | 1/0/0 |

> The tool auto-normalizes: if attribution_windows is missing or uses an invalid combo, it defaults to 30/30/1. It also auto-wraps in conversion_tag_v3_goal_metadata if the wrapper is missing, coerces cpa_goal_value_in_micro_currency to string, and defaults CPA to $10 if omitted.

cpa_goal_value_in_micro_currency: STRING (pattern ^[0-9]+$). Set high enough to avoid "CPA goal value below bid floor" errors. Example: "10000000" = $10 CPA.

Optional fields in conversion_tag_v3_goal_metadata:

• is_roas_optimized (boolean) — set true only when conversion_event="CHECKOUT" AND bid_strategy_type="AUTOMATIC_BID".
• learning_mode_type (string) — "ACTIVE" or "NOT_ACTIVE". Omit if not needed.

Template: AWARENESS campaign

pinterest_ads_create_ad_group(
    ad_account_id="",
    name="Brand Awareness",
    campaign_id="",
    billable_event="IMPRESSION",
    bid_in_micro_currency=2000000,
    targeting_spec={"LOCATION": ["US"]},
    bid_strategy_type="AUTOMATIC_BID",
    status="PAUSED",
)

Budget rules for ad groups

• CBO campaigns: Do NOT set budget_in_micro_currency on the ad group. Budget is controlled at the campaign level.
• Non-CBO campaigns: budget_in_micro_currency is REQUIRED at the ad group level.

bid_strategy_type values: AUTOMATIC_BID, MAX_BID, TARGET_AVG.

status: Always create with status="PAUSED" for review. Set to "ACTIVE" after user approval.

pacing_delivery_type: Optional. "STANDARD" (default) or "ACCELERATED".

targeting_spec keys (all values are arrays of strings unless noted):

• LOCATION — ISO Alpha-2 country codes or US Nielsen DMA codes (e.g., ["US", "CA"], ["807"]). Required (or use GEO).
• GEO — Region codes (e.g., ["BE-VOV"]) or postal codes (e.g., ["US-94107"]). Alternative to LOCATION.
• GENDER — ["male"], ["female"], or ["unknown"].
• MINIMUM_AGE — string "18" through "65" (use with MAXIMUM_AGE, not with AGE_BUCKET).
• MAXIMUM_AGE — string "18" through "65" or "65+" (use with MINIMUM_AGE).
• AGE_BUCKET — ["18-24", "25-34", "35-44", "45-54", "55-64", "65+"] (legacy, cannot combine with MIN/MAX_AGE).
• INTEREST — interest IDs from Pinterest taxonomy.
• LOCALE — ISO 639-1 language codes (e.g., ["en"]).
• APPTYPE — ["android_mobile", "android_tablet", "ipad", "iphone", "web", "web_mobile"].
• AUDIENCE_INCLUDE — audience IDs to include.
• AUDIENCE_EXCLUDE — audience IDs to exclude.

3. Create ad

pinterest_ads_create_ad(
    ad_account_id="",
    ad_group_id="",
    creative_type="REGULAR",
    pin_id="",
    name="Spring Sale Ad",
    status="ACTIVE",
    destination_url="https://example.com/spring-sale",
)

creative_type values: REGULAR, VIDEO, SHOPPING, CAROUSEL, MAX_VIDEO, SHOP_THE_PIN, IDEA.

Phase 5: Audience & Targeting

Create audience

pinterest_ads_create_audience(
    ad_account_id="",
    name="Website Visitors",
    audience_type="VISITOR",
    rule={"visitor_source_id": "", "type": "visitors"},
)

audience_type values: CUSTOMER_LIST, VISITOR, ENGAGEMENT, ACTALIKE.

Rule structure by type:

| Type | Rule example | | --- | --- | | VISITOR | {"visitor_source_id": "", "type": "visitors"} | | ENGAGEMENT | {"source": "AUDIENCE_RETENTION"} (do NOT include retention_days) | | CUSTOMER_LIST | {"list_type": "EMAIL"} | | ACTALIKE | {"source_id": "", "country": "US", "percentage": 5} |

Create customer list

pinterest_ads_create_customer_list(
    ad_account_id="",
    name="Email Subscribers",
    records="user1@example.com,user2@example.com,...",
    list_type="EMAIL",
)

list_type values: EMAIL, IDFA, MAID, LR_ID, DLX_ID, HASHED_PINNER_ID.

> Lists must match at least 100 Pinterest accounts after processing.

Phase 6: Conversion Tracking

List existing tags

pinterest_ads_list_conversion_tags(ad_account_id="")

Create conversion tag

pinterest_ads_create_conversion_tag(
    ad_account_id="",
    name="Purchase Tracking",
    aem_enabled=true,
)

Send conversion event

pinterest_ads_send_conversion_event(
    ad_account_id="",
    event_name="checkout",
    action_source="web",
    event_time=1709424000,
    event_id="unique_event_123",
    user_data={
        "em": ["5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"],
        "client_ip_address": "192.168.1.1",
        "client_user_agent": "Mozilla/5.0...",
    },
    custom_data={"currency": "USD", "value": "99.99"},
)

event_name values: add_to_cart, checkout, custom, lead, page_visit, search, signup, view_category, watch_video.

action_source values: app_android, app_ios, web, offline.

user_data requirements (at least one identifier required):

• em — array of SHA256-hashed email addresses (NOT plain text).
• hashed_maids — array of hashed mobile ad IDs.
• OR: client_ip_address + client_user_agent.

Phase 7: Keywords

> CRITICAL: match_type is REQUIRED. Without it, the Pinterest API returns a 500 error.

pinterest_ads_create_keyword(
    ad_account_id="",
    parent_id="",
    value="spring fashion trends",
    match_type="BROAD",
)

match_type values: BROAD, PHRASE, EXACT, EXACT_NEGATIVE, PHRASE_NEGATIVE.

• BROAD — ads show for related searches.
• PHRASE — ads show when search contains the phrase.
• EXACT — ads show only for exact match.
• EXACT_NEGATIVE / PHRASE_NEGATIVE — exclude these terms.

bid (optional): Bid in microcurrency for this keyword. Overrides ad group default bid.

Phase 8: Analytics

pinterest_ads_get_campaign_analytics(
    ad_account_id="",
    campaign_ids=[""],
    start_date="2026-02-01",
    end_date="2026-03-01",
    columns=["SPEND_IN_MICRO_DOLLAR", "TOTAL_IMPRESSION", "TOTAL_CLICKTHROUGH", "CPC_IN_MICRO_DOLLAR", "CTR", "CPM_IN_MICRO_DOLLAR"],
    granularity="DAY",
)

granularity values: TOTAL, DAY, HOUR, WEEKLY, MONTHLY.

Common analytics columns: SPEND_IN_MICRO_DOLLAR, TOTAL_IMPRESSION, TOTAL_CLICKTHROUGH, CPC_IN_MICRO_DOLLAR, CPM_IN_MICRO_DOLLAR, CTR, ECTR, TOTAL_CONVERSIONS, TOTAL_CONVERSIONS_VALUE_IN_MICRO_DOLLAR.

Update Operations

pinterest_ads_update_campaign, pinterest_ads_update_ad_group, and pinterest_ads_update_ad all follow the same shape — pass ad_account_id, the entity ID (campaign_id / ad_group_id / ad_id), and any fields you want to change. Statuses use ACTIVE, PAUSED, or ARCHIVED (cannot be unarchived).

pinterest_ads_update_campaign(
    ad_account_id="",
    campaign_id="",
    name="Updated Name",
    status="PAUSED",
    daily_spend_cap=75000000,
)

Cam

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hyperfx-ai
• Source: hyperfx-ai/marketing-skills
• License: MIT
• Homepage: https://www.hyperfx.ai/mcp

Install and usage instructions live in the source repository linked above.