snapchat-ads

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 search("snapchat_ads_list_organizations") does not find snapchat_ads_list_organizations, 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.

How to run the tools in this skill

Every tool in this skill is named by its canonical tool name. Run it with the call your surface gives you:

Surface	Find a tool	Run it
MCP client (Claude, Cursor, Codex, ChatGPT)	`search("<what you want to do>")`, then `describe("<name>")`	`call("<name>", {...})`
Hyper CLI	`hyperai search "<what you want to do>"`, then `hyperai describe <name>`	`hyperai call <name> --json '{...}'`

If a tool is not found, its integration is not connected or not enabled for the workspace: stop and tell the user which integration to connect.

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).