snapchat-ads

name	snapchat-ads
description	Plan and create Snapchat Ads campaigns end-to-end via the Hyper MCP — campaign, ad squad, ad build order with media upload, creatives, targeting, Snap Pixel conversion tracking, and sync / async reporting, using micro-currency budgets and JSON-Patch partial updates. Use when the user wants to launch Snapchat ads, build ad squads, upload Snap creatives, set up Snap Pixel tracking, or analyze Snapchat ad performance. Also triggers on snap ads, snapchat campaign, or snapchat ads manager.
requires_toolkits	["snapchat_ads"]
icon	snapchat_ads
short_description	Plan and create Snapchat Ads with ad squads, creatives, Snap Pixel, and reporting.

Snapchat Ads Campaigns

Strategic guide for managing Snapchat advertising via the Snapchat Marketing API v1. The toolkit is a raw-HTTP client, so parameter types must be sent exactly as documented — strings as strings, integers as integers, and all money in micro-currency.

Requirements

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

If snapchat_ads_list_organizations is not in the tool list, stop and tell the user to enable Hyper MCP and connect Snapchat Ads. Creating ad squads or serving ads also requires an active funding source on the ad account — campaigns, media, and creatives can be created without one.

Out of scope — defer to other skills

• Creative generation (ad copy, images, video) → ad-creative-generation / video-generation.
• Cross-platform campaign launches → use this skill for Snapchat, then invoke meta-ads / tiktok-ads separately.

Critical Rules

CRITICAL: All budgets and bids are in micro-currency. $1.00 = 1,000,000 micros. $50/day = 50000000. Never pass dollar amounts directly. Minimum campaign daily budget / lifetime spend cap is $20 (20000000).

CRITICAL: Create campaigns, ad squads, and ads with status="PAUSED". Never launch live without explicit user review. Because everything defaults to PAUSED, you can build a full campaign and delete it without spending — ideal for demos.

CRITICAL: Updates are JSON-Patch partial updates — pass only the fields you want to change, parented on the PARENT entity. snapchat_ads_update_campaign needs ad_account_id; snapchat_ads_update_ad_squad needs campaign_id (NOT ad_account_id); snapchat_ads_update_ad needs ad_squad_id.

CRITICAL: Account-level stats (entity_type="adaccounts") only support fields="spend". For impressions / swipes / conversions, query at the campaign, adsquad, ad, creative, or media level.

CRITICAL: There is no time_range preset (e.g. LAST_30_DAYS does not exist). Pass start_time and end_time (ISO 8601). Omitting both returns lifetime totals, not a recent window.

CRITICAL: Ad squad billing_event is always IMPRESSION. bid_micro is required for bid_strategy="LOWEST_COST_WITH_MAX_BID" and "TARGET_COST"; omit it for "AUTO_BID".

IMPORTANT: Creating an ad squad requires an active funding source on the ad account. If the account is PENDING / unfunded, ad squad creation fails — that is a billing state, not a bug.

IMPORTANT: Creatives require top_snap_media_id (an uploaded media id) and a headline (≤ 34 chars). brand_name is ≤ 32 chars.

IMPORTANT: For LOWEST_COST_WITH_MAX_BID / TARGET_COST, don't guess bid_micro — get Snapchat's suggested range with snapchat_ads_get_bid_estimate (by targeting spec before building, or by ad_squad_id after). Size the audience the same way with snapchat_ads_get_audience_size before creating anything.

IMPORTANT (customer lists): snapchat_ads_add_segment_users requires identifiers that are already normalized and SHA-256 hashed (emails trimmed + lowercased before hashing; phones digits-with-country-code; mobile ad IDs lowercase with hyphens). One schema type per call (EMAIL_SHA256, PHONE_SHA256, MOBILE_AD_ID_SHA256), max 100,000 ids. Never send raw PII. Matching is asynchronous — segment size updates after processing.

Tool surface

Group	Tools
Org & accounts	snapchat_ads_list_organizations, snapchat_ads_list_ad_accounts, snapchat_ads_get_ad_account
Campaigns	snapchat_ads_list_campaigns, snapchat_ads_get_campaign, snapchat_ads_create_campaign, snapchat_ads_update_campaign, snapchat_ads_delete_campaign
Ad squads	snapchat_ads_list_ad_squads, snapchat_ads_get_ad_squad, snapchat_ads_create_ad_squad, snapchat_ads_update_ad_squad, snapchat_ads_delete_ad_squad, snapchat_ads_estimate_ad_squad_outcomes
Ads	snapchat_ads_list_ads, snapchat_ads_get_ad, snapchat_ads_create_ad, snapchat_ads_update_ad, snapchat_ads_delete_ad
Creatives	snapchat_ads_list_creatives, snapchat_ads_get_creative, snapchat_ads_create_creative
Media	snapchat_ads_list_media, snapchat_ads_create_media, snapchat_ads_upload_media
Reporting	snapchat_ads_get_stats, snapchat_ads_create_stats_report, snapchat_ads_get_stats_report
Conversion	snapchat_ads_list_pixels, snapchat_ads_list_custom_conversions
Audiences	snapchat_ads_list_segments, snapchat_ads_get_segment, snapchat_ads_create_segment, snapchat_ads_update_segment, snapchat_ads_delete_segment, snapchat_ads_add_segment_users, snapchat_ads_remove_segment_users
Planning estimates	snapchat_ads_get_audience_size, snapchat_ads_get_bid_estimate, snapchat_ads_get_audience_insights
Targeting	snapchat_ads_search_targeting

All reference files live in references/. Read them at references/<file> (e.g. references/discovery.md).

Routing table

The user wants to…	Read these files first
Launch a Snapchat campaign	references/discovery.md → references/campaign-creation.md
Upload media / create creatives / ad squads / ads	references/campaign-creation.md
Resolve targeting (geo, demo, interests, devices)	references/targeting.md
Build custom audiences / lookalikes / audience insights	references/targeting.md
Estimate audience size / get a suggested bid	references/campaign-creation.md
Set up Snap Pixel / custom conversions	references/conversions-and-reporting.md
Pull stats / async reports / update or delete entities	references/conversions-and-reporting.md
Goal not yet clear	references/discovery.md — discovery clarifies the goal

Campaign Workflow

Discover org/account → audit account → research (objective, audience, budget, assets) → confirm strategy → create campaign (PAUSED) → upload media → create creative → create ad squad → create ad → review with user → activate (update_* to ACTIVE).

Known Limitations

Issue	Workaround
Creative creation fails (historically a silent null error)	Almost always a missing profile_properties.profile_id (required for ALL creative types) — pull one from list_creatives. The tool now raises a clear error instead of a null "success".
Ad creation fails with a type mismatch	Omit type so it's derived from the creative (WEB_VIEW → REMOTE_WEBPAGE, etc.).
Forecast returns OE101 / UNSUPPORTED_DELIVERY_CONSTRAINT	The tool auto-adds delivery_constraint; if it persists, outcome estimation is unavailable for the account type (often PARTNER) — use the Ads Manager reach planner.
DAY-granularity stats reject the time range (E1008)	Handled automatically — pass ad_account_id to get_stats/create_stats_report and the tool aligns to account-timezone midnight + hour boundaries.
Media rejected with E2601 ("cannot be used to create any creative type")	The file doesn't meet specs — use a 1080×1920 (9:16) PNG/JPG ≤ 5 MB image or 1080×1920 MP4/MOV. Re-generate the asset at the right size, re-upload, and confirm media_status is READY.
Upload fails on file_path / internal URL (Errno 2 / DNS error)	Pass file_id (the Hyper file id) instead — it reads from storage directly. Avoid server-local paths and internal files.* URLs.
Account-level stats reject non-spend fields (error E1008)	Query other metrics at campaign/adsquad/ad/creative/media level.
No time_range/date preset	Pass start_time + end_time; omitting them returns lifetime totals.
Ad squad creation fails on unfunded accounts	Add a funding source; campaigns/media/creatives still work without one.
bid_micro required for non-AUTO_BID strategies	Provide bid_micro for LOWEST_COST_WITH_MAX_BID / TARGET_COST.
Media > 32 MB	Handled automatically (chunked upload, up to 1 GB).
Partial updates	Use the update tools (PATCH) with the correct parent id — never resend the whole object.
Customer-list upload "succeeds" but the segment stays small	Identifiers must be normalized + SHA-256 hashed before upload; matching is asynchronous and only hashes that match Snapchat users count. Check the segment's approximate_number_users after processing.
Lookalike creation rejected	Lookalikes need a healthy seed: a FIRST_PARTY segment with enough matched users, countries (ISO-2), and retention_in_days ≤ 180.

Safety Rules

Never:

• Assume organization, ad account, campaign, media, or creative IDs — look them up or ask.
• Skip the account audit phase.
• Create campaigns, ad squads, or ads without explicit user approval.
• Set anything to ACTIVE without user consent.
• Pass dollar amounts instead of micro-currency.
• Query non-spend metrics at the adaccounts level.
• Use a time_range preset — always pass start_time/end_time.
• Use LOWEST_COST_WITH_MAX_BID / TARGET_COST without bid_micro.
• Pass the wrong parent id to update tools (ad squad → campaign_id, ad → ad_squad_id).