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

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

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

CBO vs Non-CBO

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

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