build-campaign

What this skill does

# Spotify Ads API — Full Campaign Builder

Given a plain-text description of an advertising campaign, parse it into structured API
calls and create the full campaign hierarchy: Campaign → Ad Sets → Ads.

## Setup

1. Read `access_token`, `ad_account_id`, and `auto_execute` from the active platform settings file:
   - Codex: prefer `.codex/spotify-ads-api.local.md`, then fall back to `.claude/spotify-ads-api.local.md`.
   - Claude: prefer `.claude/spotify-ads-api.local.md`, then fall back to `.codex/spotify-ads-api.local.md`.
2. Base URL: `https://api-partner.spotify.com/ads/v3`
3. If neither settings file exists, instruct the user to run `/spotify-ads-api:configure` first.
4. Read the active platform manifest for the plugin `version`: `.codex-plugin/plugin.json` on Codex or `.claude-plugin/plugin.json` on Claude.
5. Set `SDK_PRODUCT` to `codex-plugin` on Codex or `claude-code-plugin` on Claude. Set `SDK_HEADER="X-Spotify-Ads-Sdk: $SDK_PRODUCT/$PLUGIN_VERSION"` and include `-H "$SDK_HEADER"` on all API requests.

## Step 1: Parse the Campaign Description

Extract the following from the user's plain-text input. If a field is missing or ambiguous,
use the defaults noted below. If a required field cannot be inferred, ask the user.

### Campaign-level fields

| Field | Required | Default |
|-------|----------|---------|
| name | yes | — |
| objective | yes | REACH |

Valid objectives: `REACH`, `CLICKS`, `VIDEO_VIEWS`, `CONVERSIONS`, `LEAD_GEN`, `EVEN_IMPRESSION_DELIVERY`, `PODCAST_STREAMS`, `APP_INSTALLS`, `WEBSITE_VISITS`

### Ad set-level fields (one or more)

| Field | Required | Default | Notes |
|-------|----------|---------|-------|
| name | yes | — | 2-200 chars |
| start_time | yes | — | ISO 8601 UTC |
| end_time | required if LIFETIME | — | ISO 8601 UTC |
| budget.micro_amount | yes | — | Dollar amount x 1,000,000 |
| budget.type | yes | DAILY | `DAILY` or `LIFETIME` |
| asset_format | yes | AUDIO | `AUDIO`, `VIDEO`, `IMAGE`, or `CATALOG` |
| category | yes | — | Valid `ADV_X_Y` code (fetch from `GET /ad_categories` if needed) |
| bid_strategy | yes | MAX_BID | Plain string: `MAX_BID`, `COST_PER_RESULT`, `AUTOBID`, or `UNSET` |
| bid_micro_amount | yes with MAX_BID/COST_PER_RESULT | 15000000 | Bid cap in micro-units. Not required with AUTOBID. |
| pacing | no | PACING_EVEN | `PACING_EVEN` or `PACING_ASAP` |
| delivery | no | ON | `ON` or `OFF` |
| targets.age_ranges | yes | [{"min":18,"max":54}] | Array of `{min, max}` objects |
| targets.geo_targets | yes | {"country_code":"US"} | **Flat object** with `country_code` string |
| targets.platforms | no | ["ANDROID","DESKTOP","IOS"] | Valid: `ANDROID`, `DESKTOP`, `IOS` |
| targets.placements | yes | ["MUSIC"] | `MUSIC` or `PODCAST` |
| targets.genders | no | [] | `MALE`, `FEMALE`, `NON_BINARY` |

**Ad set validation guardrails:**
- Reject or ask to correct zero/negative budgets and zero bids. `budget.micro_amount` and `bid_micro_amount` must be positive when present.
- Do not include `currency` in ad set `budget`; currency is only required in `/estimates/audience` budget payloads.
- Do not send `cost_model`, `skippable`, `is_skippable`, or `ad_platforms` in ad set create payloads.
- Only use `ANDROID`, `DESKTOP`, and `IOS` in `targets.platforms`; never use `WEB`, `MOBILE`, or `CONNECTED_DEVICE`.
- Use `min >= 18` for age ranges unless the user explicitly confirms a market/category that allows minors.
- When geo refinements are present (`city_ids`, `dma_ids`, `postal_code_ids`, `region_ids`), include `country_code` in the same `geo_targets` object.
- If `bid_strategy=UNSET`, omit `bid_micro_amount` unless the API response or user-provided source explicitly requires it.

### Ad-level fields (one or more per ad set)

| Field | Required | Notes |
|-------|----------|-------|
| name | yes | 2-200 chars |
| tagline | yes | 2-40 chars |
| advertiser_name | yes | 2-25 chars |
| assets.asset_id | yes | UUID — prompt user to select |
| assets.logo_asset_id | yes | UUID — prompt user to select |
| assets.companion_asset_id | yes (audio) | UUID — required for AUDIO format ads |
| call_to_action.key | yes | e.g. `SHOP_NOW`, `LEARN_MORE`, `LISTEN_NOW`, `SIGN_UP` |
| call_to_action.clickthrough_url | yes | Landing page URL |
| delivery | no | `ON` (default) or `OFF` |

## Step 2: Confirm the Parsed Plan

Before making any API calls, present the full parsed plan as a visual tree:

```
Campaign: "My Campaign" (objective: REACH)
├── Ad Set 1: "Ad Set A" (AUDIO, $75/day, US, ages 25-54, Mar 1 start)
│   └── Ad 1: "My Ad" → SHOP_NOW → example.com
└── Ad Set 2: "Ad Set B" (VIDEO, $500 lifetime, US, ages 18-54, Mar 4–Apr 4)
    └── Ad 2: "My Video Ad" → LEARN_MORE → example.com
```

Also show a table with all field values for each entity. Ask the user to confirm or adjust.

If the ad category was not specified, ask the user to select one using AskUserQuestion.
You can fetch valid categories from `GET /ad_categories` to present options.

## Step 2.5: Validate Audience Size

After the user confirms the plan but before executing API calls, run an audience estimate for each ad set's targeting:

```bash
curl -s -w "\nHTTP_STATUS:%{http_code}" -X POST -H "Authorization: Bearer $TOKEN" \
  -H "$SDK_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_account_id": "<AD_ACCOUNT_ID>",
    "start_date": "<start_time>",
    "asset_format": "<AUDIO|VIDEO|IMAGE|CATALOG>",
    "objective": "<campaign_objective>",
    "bid_strategy": "<MAX_BID|COST_PER_RESULT|AUTOBID|UNSET>",
    "bid_micro_amount": <bid>,
    "budget": {"micro_amount": <budget>, "type": "<DAILY|LIFETIME>", "currency": "USD"},
    "targets": { <same targets object as the ad set> }
  }' \
  "https://api-partner.spotify.com/ads/v3/estimates/audience"
```

**Important:** This endpoint is NOT scoped under `/ad_accounts/{id}/` — it's at the top level: `POST /estimates/audience`. Use the base URL directly followed by `/estimates/audience`.

Display the estimate results in a summary:

```
Audience Estimate for "Ad Set A":
  Projected unique users: ~142,000
  Estimated daily reach: 8,500 – 12,000
  Estimated daily impressions: 15,000 – 22,000
  Estimated CPM: $12.50 – $18.00
  Likely to deliver budget: Yes
```

Convert any CPM micro-amounts to dollars for display.

**If the audience is too small** (very low `projected_unique_users` or the API returns a 400 error indicating audience too small), warn the user and suggest:
- Broadening the age range
- Adding more platforms
- Removing restrictive targeting (artist/genre/interest)
- Switching from VIDEO to AUDIO format (lower thresholds)
- Expanding geo targeting

Use AskUserQuestion to ask whether to:
1. Proceed anyway with current targeting
2. Adjust targeting (then re-estimate)
3. Cancel this ad set

Run the estimate for each ad set in the plan before proceeding to Step 3.

## Step 3: Prompt for Assets

For each ad, fetch available assets from the account:

```bash
curl -s -w "\nHTTP_STATUS:%{http_code}" -H "Authorization: Bearer $TOKEN" \
  -H "$SDK_HEADER" \
  "$BASE_URL/ad_accounts/$AD_ACCOUNT_ID/assets?limit=50&sort_direction=DESC"
```

Present audio/video assets and image assets separately in tables, and ask the user to pick:
- **asset_id** — the creative (must match the ad set's `asset_format`: audio for AUDIO, video for VIDEO, etc.)
- **logo_asset_id** — a logo image
- **companion_asset_id** — a companion image (required for AUDIO format ads)

## Step 4: Execute API Calls Sequentially

Execute each step in order, passing IDs forward from each response.

### 4a. Create Campaign

```bash
curl -s -w "\nHTTP_STATUS:%{http_code}" -X POST -H "Authorization: Bearer $TOKEN" \
  -H "$SDK_HEADER" \
  -H "Content-Type: application/json" \
  -d '{"name":"...","objective":"..."}' \
  "$BASE_URL/ad_accounts/$AD_ACCOUNT_ID/campaigns"
```

Extract the campaign `id` from the response.

### 4b. Create Ad Sets (using campaign_id from 4a)

For each ad set:

```bash
curl -s -w "\nHTTP_STATUS:%{http_code}" -X POST -H "Authorizat