Documento original do Skill
Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.
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/apps (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 usingis_flexible_daily_budgets: true, you MUST also setis_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: WEBCONVERSION ad groups MUST use `billableevent="IMPRESSION"(NOTCLICKTHROUGH) and MUST includeoptimizationgoalmetadatawithattributionwindows`, `conversionevent,conversiontagid, andcpagoalvalueinmicro_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.Core process
Discovery → audit account → research (objectives, audience, assets) → confirm strategy → create campaign (PAUSED) → create ad groups → create ads → review → activate only with user approval.
All reference files live in `references/`. Read them atreferences/<file>(e.g.references/discovery.md).
Routing table
| The user wants to… | Read these files first |
|---|---|
| Create a campaign (any objective) | references/discovery.md → references/campaigns.md |
| Build a WEB_CONVERSION campaign | references/discovery.md → references/campaigns.md (use the WEB_CONVERSION template exactly) + references/audiences-and-conversions.md for the conversion tag |
| Create or manage audiences / customer lists | references/audiences-and-conversions.md |
| Set up conversion tracking / send conversion events | references/audiences-and-conversions.md |
| Add keywords to an ad group | references/keywords-and-analytics.md |
| Pull campaign analytics | references/keywords-and-analytics.md |
| Update or pause existing campaigns / ad groups / ads | references/keywords-and-analytics.md |
| Goal not yet clear | references/discovery.md — discovery clarifies the goal |
Known Limitations
| Issue | Workaround |
|---|---|
Keyword creation returns 500 without match_type | Always specify match_type (BROAD, PHRASE, EXACT). |
retention_days deprecated for ENGAGEMENT audiences | Omit from rule dict. |
| WEB_CONVERSION ad groups require many parameters | Use the WEBCONVERSION template exactly — include full `optimizationgoal_metadata`. |
| WEBCONVERSION ad groups must use `IMPRESSION` `billableevent` | Do NOT use CLICKTHROUGH for WEB_CONVERSION. |
| CBO campaigns reject ad group budgets | Do NOT set budget_in_micro_currency when parent campaign has CBO enabled. |
cpa_goal_value_in_micro_currency must be a string | Pass as "5000000", not 5000000. |
conversion_tag_id must be a real tag from the account | List conversion tags first, then use an existing tag ID. |
Safety Rules
Never:
- Assume Pin IDs or ad account IDs — always ask or look up.
- Skip the account audit phase.
- Create campaigns without explicit approval.
- Set campaigns to
ACTIVEwithout user consent. - Pass dollar amounts instead of microcurrency.
- Use
retention_daysfor ENGAGEMENT audiences. - Create WEBCONVERSION ad groups without `optimizationgoal_metadata`.
- Use
CLICKTHROUGHbillable_eventfor WEB_CONVERSION campaigns (useIMPRESSION). - Set ad group budgets on CBO campaigns.
- Create keywords without specifying
match_type. - Pass
cpa_goal_value_in_micro_currencyas an integer (must be a string like"5000000"). - Omit
conversion_tag_idfrom WEB_CONVERSION optimization metadata (list tags first, use a real ID).
