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="<AD_ACCOUNT_ID>")
pinterest_ads_list_ad_groups(ad_account_id="<AD_ACCOUNT_ID>")
pinterest_ads_list_ads(ad_account_id="<AD_ACCOUNT_ID>")
pinterest_ads_list_audiences(ad_account_id="<AD_ACCOUNT_ID>")
pinterest_ads_list_conversion_tags(ad_account_id="<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="<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="<AD_ACCOUNT_ID>",
    name="US Women 25-54",
    campaign_id="<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="<AD_ACCOUNT_ID>",
    name="US Women 25-54",
    campaign_id="<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.

pint