# Snapchat Ads: Campaign Structure & Creation

Read [discovery.md](discovery.md) first — org/account selection and assessment must be complete.

## Phase 3: Campaign Structure

### Hierarchy

```
Organization
└── Ad Account ── Creatives ── Media
    └── Campaign (objective, optional budget)
        └── Ad Squad (targeting, bid, budget, optimization_goal, placement)
            └── Ad (links a Creative)
```

### Build order

1. **Campaign** (`status="PAUSED"`)
2. **Media**: `create_media` (container) → `upload_media` (file)
3. **Creative**: `create_creative` using the uploaded `top_snap_media_id`
4. **Ad squad** under the campaign (requires funding source)
5. **Ad** under the ad squad, linking the `creative_id`

Assets (2–3) and the ad squad (4) are independent; the ad (5) needs both a `creative_id` and an `ad_squad_id`.

### Campaign objectives

Pass the classic `objective` string, or newer objectives via `extra={"objective_v2_properties": {"objective_v2_type": "..."}}`.

| `objective` | Use case |
| --- | --- |
| `BRAND_AWARENESS` | Reach / impressions |
| `ENGAGEMENT` | Engagement, story opens |
| `VIDEO_VIEW` | Video views |
| `WEB_VIEW` | Traffic |
| `WEB_CONVERSION` | Purchases, signups, leads (pixel) |
| `APP_INSTALL` / `APP_REENGAGEMENT` | App installs / re-engagement |
| `LEAD_GENERATION` | On-Snap lead forms |
| `CATALOG_SALES` | Dynamic product ads |

`objective_v2_type` values: `AWARENESS_AND_ENGAGEMENT`, `TRAFFIC`, `SALES`, `APP_PROMOTION`, `LEADS`.

## Phase 4: Campaign Creation

### 1. Create campaign

```python
snapchat_ads_create_campaign(
    ad_account_id="<AD_ACCOUNT_ID>",
    name="Spring Launch 2026",
    objective="WEB_CONVERSION",
    status="PAUSED",
    start_time="2026-07-01T00:00:00-07:00",
    daily_budget_micro=50000000,   # $50.00/day, min $20
)
```

`buy_model` is `AUCTION` (default) or `RESERVED`. Use `daily_budget_micro` or `lifetime_spend_cap_micro`.

### 2. Upload media (two steps)

> **MEDIA SPECS — wrong specs cause creative error E2601** ("media cannot be used to create any creative type"). Top Snap image/video must be **1080×1920 px (9:16)**. Images: PNG/JPG, ≤ 5 MB. Video: MP4/MOV, 3–180 s. **If you generate the asset, generate it at 1080×1920.** Snapchat tags valid media with `media_usages` (e.g. `TOP_SNAP`); media with no usable usage is rejected at the creative step.

```python
snapchat_ads_create_media(
    ad_account_id="<AD_ACCOUNT_ID>",
    name="Spring Hero Video",
    type="VIDEO",            # IMAGE | VIDEO | LENS_PACKAGE | PLAYABLE — must match the file
)
# PREFER file_id (a Hyper file id, e.g. a generated image/video). It is read
# straight from storage, so it works even when a public URL isn't reachable
# from the backend. Use file_url / file_path only for genuinely external assets.
snapchat_ads_upload_media(
    media_id="<MEDIA_ID>",
    file_id="<HYPER_FILE_ID>",   # or file_url="https://..." / file_path="/server/path"
)
```

`upload_media` auto-chunks files larger than 32 MB (up to 1 GB). Confirm the returned `media_status` is `READY` before creating a creative.

### 3. Create creative

```python
snapchat_ads_create_creative(
    ad_account_id="<AD_ACCOUNT_ID>",
    name="Spring Hero Creative",
    type="WEB_VIEW",                  # SNAP_AD | WEB_VIEW | APP_INSTALL | DEEP_LINK | ...
    top_snap_media_id="<MEDIA_ID>",
    headline="Shop the Spring Drop",  # <= 34 chars (required)
    brand_name="Acme",                # <= 32 chars
    call_to_action="SHOP_NOW",
    web_view_properties={"url": "https://example.com/spring"},
)
```

> **`profile_properties` is required for ALL creative types on most accounts** (not just SNAP_AD): `profile_properties={"profile_id": "<PUBLIC_PROFILE_ID>"}`. If you don't have the public profile id, call `snapchat_ads_list_creatives` and copy `profile_properties.profile_id` from any existing creative. Without it, creation fails — previously silently, now with a clear error.

`call_to_action` is type-dependent (WEB_VIEW → `VIEW`/`SHOP_NOW`/`SIGN_UP`; APP_INSTALL → `INSTALL_NOW`/`DOWNLOAD`; DEEP_LINK → `OPEN_APP`/`PLAY`). WEB_VIEW needs `web_view_properties={"url": ...}`; APP_INSTALL/DEEP_LINK use `app_install_properties`/`deep_link_properties`.

### 4. Create ad squad

> **CRITICAL**: Required — `campaign_id`, `name`, `optimization_goal`, `targeting`, `billing_event="IMPRESSION"`, `bid_strategy`, a budget (`daily_budget_micro` OR `lifetime_budget_micro`), and `placement_v2`. `bid_micro` is required unless `bid_strategy="AUTO_BID"`.

```python
snapchat_ads_create_ad_squad(
    campaign_id="<CAMPAIGN_ID>",
    name="US Gen-Z 18-24",
    status="PAUSED",
    type="SNAP_ADS",                     # SNAP_ADS | LENS | FILTER
    optimization_goal="PIXEL_PURCHASE",
    billing_event="IMPRESSION",
    bid_strategy="LOWEST_COST_WITH_MAX_BID",
    bid_micro=3000000,                   # required for non-AUTO_BID
    daily_budget_micro=20000000,         # ad-squad min is $5 (5000000)
    placement_v2={"config": "AUTOMATIC"},
    # pixel_id="<PIXEL_ID>",             # required-ish for PIXEL_* goals
    targeting={
        "geos": [{"country_code": "us"}],
        "demographics": [{"min_age": 18, "max_age": 24}],
        "regulated_content": False,
    },
)
```

**`optimization_goal`:** `IMPRESSIONS`, `SWIPES`, `VIDEO_VIEWS`, `VIDEO_VIEWS_15_SEC`, `USES`, `STORY_OPENS`, `APP_INSTALLS`, `LANDING_PAGE_VIEW`, `LEAD_FORM_SUBMISSIONS`, `PIXEL_PAGE_VIEW`, `PIXEL_ADD_TO_CART`, `PIXEL_PURCHASE`, `PIXEL_SIGNUP`, `APP_ADD_TO_CART`, `APP_PURCHASE`, `APP_SIGNUP`, `APP_REENGAGE_OPEN`, `APP_REENGAGE_PURCHASE`.

**`bid_strategy`:** `AUTO_BID` (no `bid_micro`), `LOWEST_COST_WITH_MAX_BID` (`bid_micro` = max bid), `TARGET_COST` (`bid_micro` = target). `MIN_ROAS` is deprecated.

**`pacing_type`:** `STANDARD` (default) or `ACCELERATED`. **`placement_v2`:** `{"config": "AUTOMATIC"}` or `{"config": "CUSTOM", ...}`.

#### Targeting object

```python
targeting = {
    "regulated_content": False,
    "geos": [{"country_code": "us"}],                 # lowercase ISO country
    "demographics": [{"min_age": 18, "max_age": 34, "gender": "FEMALE"}],
    "interests": [{"category_id": ["<SCLS_ID>"]}],    # from snapchat_ads_search_targeting
    "devices": [{"os_type": "iOS"}],
}
```

#### Optional: forecast before launch

`snapchat_ads_estimate_ad_squad_outcomes` returns daily/weekly reach, conversion, and impression ranges for a proposed squad config — without creating anything. Useful to sanity-check budget/targeting before building:

```python
snapchat_ads_estimate_ad_squad_outcomes(
    ad_account_id="<AD_ACCOUNT_ID>",
    ad_squad={
        "optimization_goal": "IMPRESSIONS",
        "bid_strategy": "AUTO_BID",
        "daily_budget_micro": 50000000,
        "type": "SNAP_ADS",
        "placement_v2": {"config": "AUTOMATIC"},
        "targeting": {"geos": [{"country_code": "us"}]},
        "start_time": "2026-07-01T00:00:00-07:00",
    },
)
```

The tool auto-adds `delivery_constraint`. If it returns OE101/`UNSUPPORTED_DELIVERY_CONSTRAINT`, outcome estimation is likely **unavailable for this account type** (PARTNER accounts are often excluded) — skip forecasting and use the Snapchat Ads Manager reach planner instead.

#### Optional: audience size + suggested bid

Two lighter planning calls that work per targeting spec — use them to fill in the squad's numbers instead of guessing:

```python
# Reach range for a proposed squad spec (or pass ad_squad_id for an existing squad)
snapchat_ads_get_audience_size(
    ad_account_id="<AD_ACCOUNT_ID>",
    ad_squad_spec={
        "type": "SNAP_ADS",
        "optimization_goal": "APP_INSTALLS",
        "placement": "CONTENT",
        "daily_budget_micro": 50000000,
        "targeting": {"geos": [{"country_code": "us"}],
                      "demographics": [{"age_groups": ["21-24"]}]},
    },
)   # -> audience_size_minimum / audience_size_maximum

# Snapchat's suggested bid range (micro-currency) for a goal + targeting —
# use this to set bid_micro for LOWEST_COST_WITH_MAX_BID / TARGET_COST
snapchat_ads_get_bid_estimate(
    ad_account_id="<AD_ACCOUNT_ID>",
    optimization_goal="IMPRESSIONS",
    targeting={"geos": [{"country_code": "us"}]},
)   # -> bid_estimate_minimum / bid_estimate_maximum
```

Both also accept `ad_squad_id` to evaluate an existing squad after creation.

### 5. Create ad

> **Omit `type`** — it's auto-derived from the creative (a WEB_VIEW creative needs a `REMOTE_WEBPAGE` ad, SNAP_AD→SNAP_AD, APP_INSTALL→APP_INSTALL, DEEP_LINK→DEEP_LINK). Only set `type` to override.

```python
snapchat_ads_create_ad(
    ad_squad_id="<AD_SQUAD_ID>",
    name="Spring Hero Ad",
    creative_id="<CREATIVE_ID>",
    status="PAUSED",
)
```

# Snapchat Ads: Conversion Tracking, Reporting & Updates

## Phase 5: Conversion Tracking

For `PIXEL_*` / `APP_*` goals, discover the pixel and its custom conversions, then use the conversion id as a stats metric:

```python
snapchat_ads_list_pixels(ad_account_id="<AD_ACCOUNT_ID>")
snapchat_ads_list_custom_conversions(pixel_id="<PIXEL_ID>")     # or mobile_app_id="<APP_ID>"
```

Each custom conversion `id` is prefixed `conversion_` and can be passed in the `fields` of a stats call (e.g. `conversion_0029904941`).

## Phase 7: Reporting

### Synchronous stats

```python
# Account level — SPEND ONLY
snapchat_ads_get_stats(
    entity_type="adaccounts", entity_id="<AD_ACCOUNT_ID>",
    fields="spend", granularity="DAY",
    start_time="2026-06-01T00:00:00-07:00", end_time="2026-06-30T00:00:00-07:00",
)

# Campaign / ad squad / ad — full metrics
snapchat_ads_get_stats(
    entity_type="campaigns", entity_id="<CAMPAIGN_ID>",
    fields="impressions,swipes,spend,video_views,conversion_purchases",
    granularity="DAY",
    start_time="2026-06-01", end_time="2026-06-30",
    ad_account_id="<AD_ACCOUNT_ID>",   # lets the tool align DAY/HOUR to the account timezone
    breakdown="adsquad",
)
```

- **`spend` is micro-currency** — divide by 1,000,000 for dollars.
- `granularity`: `TOTAL`, `DAY`, `HOUR`, `LIFETIME`. For **DAY/HOUR**, pass `ad_account_id` (or `account_timezone`) and the tool auto-aligns `start_time`/`end_time` to the account-timezone midnight / hour boundaries Snapchat requires — no manual UTC math. At the adaccounts level the timezone is resolved automatically.
- `breakdown`: `campaign`/`adsquad`/`ad`. `report_dimension`: `country`, `region`, `dma`, `age`, `gender`, `os`, `make`, `lifestyle_category`.
- Stats finalize ~48h after the day ends in the account timezone — recent numbers can be partial.

### Asynchronous reports (large pulls / CSV export / reach overlap)

```python
snapchat_ads_create_stats_report(
    entity_type="campaigns", entity_id="<CAMPAIGN_ID>",
    fields="impressions,spend", granularity="DAY",
    start_time="2026-01-01T00:00:00-08:00", end_time="2026-06-30T00:00:00-07:00",
    async_format="csv",
)
# poll until report_run_status == COMPLETED, then read .result (signed download URL)
snapchat_ads_get_stats_report(
    entity_type="campaigns", entity_id="<CAMPAIGN_ID>", report_run_id="<REPORT_RUN_ID>",
)
```

For reach & frequency overlap (same ad account only): `overlap=True`, `overlap_type="campaign"`, `ids="<id1>,<id2>"`.

## Update & Delete

Updates are partial (JSON Patch) — send only what changes, with the correct parent id:

```python
snapchat_ads_update_campaign(ad_account_id="<AD_ACCOUNT_ID>", campaign_id="<ID>", status="ACTIVE")
snapchat_ads_update_ad_squad(campaign_id="<CAMPAIGN_ID>", ad_squad_id="<ID>", daily_budget_micro=30000000)
snapchat_ads_update_ad(ad_squad_id="<AD_SQUAD_ID>", ad_id="<ID>", status="PAUSED")
```

Deletes are permanent: `snapchat_ads_delete_campaign`, `snapchat_ads_delete_ad_squad`, `snapchat_ads_delete_ad`.

# Snapchat Ads: Discovery & Account Assessment

## Phase 1: Org & Account Discovery

Snapchat nests ad accounts under organizations. Start here:

```python
snapchat_ads_list_organizations(with_ad_accounts=True)
```

- If multiple organizations / accounts: ask the user to select one.
- If single: inform the user and proceed.
- Note the `ad_account_id` (and `organization_id`) — `ad_account_id` is required for most calls.

List accounts for a specific org explicitly with `snapchat_ads_list_ad_accounts(organization_id="<ORG_ID>")`.

## Phase 2: Account Assessment

Run in parallel to understand the account state:

```python
snapchat_ads_list_campaigns(ad_account_id="<AD_ACCOUNT_ID>")
snapchat_ads_list_ad_squads(ad_account_id="<AD_ACCOUNT_ID>")
snapchat_ads_list_ads(ad_account_id="<AD_ACCOUNT_ID>")
snapchat_ads_list_media(ad_account_id="<AD_ACCOUNT_ID>")
snapchat_ads_list_pixels(ad_account_id="<AD_ACCOUNT_ID>")
```

Then confirm: objective, daily/lifetime budget (convert dollars → micros), audience (geo/age/gender/interests/devices), creative assets + destination URL, and — for conversion goals — that a pixel/custom conversion exists.

# Snapchat Ads: Targeting Lookups

## Phase 6: Targeting Lookups

`snapchat_ads_search_targeting(path=...)` — `path` is appended to `/targeting/`:

| What | `path` | Notes |
| --- | --- | --- |
| Countries | `geo/country` | |
| Regions / metros | `geo/{country_code}/region`, `geo/{country_code}/metro` | nested |
| Age / gender / languages | `demographics/age_group`, `demographics/gender`, `demographics/languages` | |
| Interests (Snap Lifestyle Categories) | `interests/scls` | **requires** `extra={"country_code": "us"}` |
| Interests (other taxonomies) | `interests/dlxs`, `interests/nln` | |
| Devices | `device/os_type`, `device/carrier`, `device/marketing_name` | |

```python
snapchat_ads_search_targeting(path="interests/scls", extra={"country_code": "us"})
```

## Audience segments (customer lists + lookalikes)

Segments are reusable audiences targeted via the ad squad's targeting spec. Build order: create the segment → add hashed members → (optionally) derive a lookalike → reference the segment id in `targeting`.

```python
# 1. Customer list (FIRST_PARTY)
snapchat_ads_create_segment(
    ad_account_id="<AD_ACCOUNT_ID>",
    name="Newsletter subscribers",
    retention_in_days=180,
)

# 2. Add members — ids must be ALREADY normalized + SHA-256 hashed.
#    Emails: trim + lowercase before hashing. One schema per call, ≤ 100k ids.
snapchat_ads_add_segment_users(
    segment_id="<SEGMENT_ID>",
    schema="EMAIL_SHA256",
    ids=["c3a75685...", "5b5fbfe6..."],
)

# 3. Lookalike from the seed list (retention ≤ 180 days)
snapchat_ads_create_segment(
    ad_account_id="<AD_ACCOUNT_ID>",
    name="Subscribers LAL — US",
    seed_segment_id="<SEGMENT_ID>",
    countries=["US"],
    lookalike_type="BALANCE",    # BALANCE (default) | SIMILARITY (closest) | REACH (broadest)
)

# 4. Target it in an ad squad
targeting = {
    "geos": [{"country_code": "us"}],
    "segments": [{"segment_id": ["<SEGMENT_ID>"]}],
}
```

Matching is **asynchronous** — the segment's `approximate_number_users` fills in after processing (`snapchat_ads_get_segment`). Remove members with `snapchat_ads_remove_segment_users` (same hashed format, or `all_users=true` to clear the list); `snapchat_ads_delete_segment` permanently removes the segment and its data.

## Audience insights

`snapchat_ads_get_audience_insights` compares a target audience against a reference baseline — size ranges plus demographic / interest / device breakdowns with `target_index_to_reference` metrics (e.g. "this audience over-indexes 2.3× on sports"):

```python
snapchat_ads_get_audience_insights(
    ad_account_id="<AD_ACCOUNT_ID>",
    targeting_spec={"interests": [{"category_id": ["SLC_37"]}], "geos": [{"country_code": "us"}]},
    base_spec={"geos": [{"country_code": "us"}]},     # reference: everyone in the US
)
```