/meta-ads

Creating campaigns from scratch

scripts/create_campaign.py builds an entire campaign tree (campaign → ad sets → creatives → ads) in one call from a spec JSON. This is a write operation — read write-actions.md first; the "Campaign creation" section at the bottom of that file is mandatory before you call --confirm for the first time in a session.

The workflow

1. Write a spec JSON that describes the campaign you want.
2. Run --dry-run. This reads the spec, queries Meta for account currency, resolves interest names to IDs, and prints the plan — no writes.
3. Walk the plan back to the user. They name the change to confirm.
4. Run --confirm. The script creates everything PAUSED by default and writes a state JSON with every ID.
5. If the user wants to activate: they toggle ACTIVE in Ads Manager (or via the API). Never flip ACTIVE programmatically as part of creation — that removes the final checkpoint.

Spec format (minimum viable)

{
  "campaign_name": "My Campaign - Q2 Flight",
  "objective": "OUTCOME_TRAFFIC",
  "status": "PAUSED",
  "special_ad_categories": [],
  "identity": {
    "page_id": "1234567890",
    "instagram_user_id": "17841400000000000"
  },
  "landing_url": "https://example.com",
  "ad_sets": [
    {
      "name": "Angle A — Broad",
      "daily_budget": 50.00,
      "optimization_goal": "LINK_CLICKS",
      "billing_event": "LINK_CLICKS",
      "targeting": {
        "countries": ["IL"],
        "age_min": 25,
        "age_max": 45,
        "interests": ["Artificial intelligence", "Productivity"],
        "publisher_platforms": ["instagram"],
        "instagram_positions": ["stream", "story", "reels"]
      },
      "image_path": "./creative/angle_a.png",
      "ads": [
        {
          "name": "A1_Direct",
          "message": "Primary body copy — can be multi-line.",
          "headline": "Short punchy headline",
          "description": "Optional secondary line",
          "cta": "LEARN_MORE"
        }
      ]
    }
  ]
}

Field reference

Top level

Ad set level

Ad level

Each ad inside an ad set uses the ad set's image.

Currency handling

The script queries /act_.../?fields=currency once at the start and converts daily_budget / lifetime_budget / bid_amount from major units to whatever minor unit the account uses:

• ILS / USD / EUR / GBP etc. → × 100 (agorot, cents, pence)
• JPY / KRW / VND / ISK / TWD / XAF / XOF / CLP → × 1 (no minor unit)

Write budgets in major units only. Never try to pre-convert.

Interest resolution

targeting.interests names are resolved via Meta's /search?type=adinterest endpoint. The script takes the top-ranked hit per name. This is convenient for readable specs but has two caveats:

1. The search ranking can change. A spec that resolved to "Productivity" today might resolve to "Productivity (software category)" tomorrow.
2. Search can return no match. Those names are dropped with a [warn] log.

For specs you'll re-run months later and want identical targeting, do one dry-run, copy the resolved_interests IDs into interest_ids, and delete interests. Now the targeting is frozen.

State file and rollback

Every --confirm run writes <spec>_state_<timestamp>.json with every object ID:

{
  "ok": true,
  "campaign_id": "120...",
  "ad_sets": [
    {"adset_id": "120...", "image_hash": "...", "ads": [{"ad_id": "120...", "creative_id": "120..."}]}
  ],
  "objects": [{"type": "campaign", "id": "120...", "name": "..."}, ...]
}

scripts/rollback_creation.py --state <file> --pause pauses everything. --delete permanently deletes in reverse order (ads → creatives are orphaned → adsets → campaign). Prefer --pause unless you really want the objects gone from Ads Manager history.

Common errors and how to handle them

error_subcode 1885036 — Ad account is unsettled. The campaign objects get created fine but nothing will deliver until the account balance is paid. Don't block on this at creation time; surface it to the user and continue.

The ad creative spec is invalid. Usually missing page_id or a malformed call_to_action value. Double-check the cta is in VALID_CTAS and the landing URL is fully qualified (https://...).

Invalid parameter on flexible_spec. Means an interest ID is stale. Re-run the dry-run so search re-resolves names, or remove the offending interest.

special_ad_categories mismatch. If your ad is in a regulated vertical and you forgot to mark it, Meta rejects the whole ad set. Reviewable in the ad set's delivery_info in Ads Manager.

Account not admin of page. The ad account owner must have advertiser-or-higher role on the Facebook Page. Fix in Business Settings → Pages → assign.

Instagram identity missing. If instagram_user_id is omitted, ads still run on Instagram placements but show "Sponsored by <Page Name>" instead of your IG handle. Almost always you want to set it.

When to NOT use this script

• You only want to duplicate an existing ad. Use scripts/duplicate_ad.py — it copies targeting, creative, and settings in one shot and is one API call instead of six.
• You're iterating on creative for an existing ad set. Creating a new campaign per iteration pollutes Ads Manager. Add new ads to the existing ad set via a partial spec or do it in the UI.
• You want dynamic creative / catalog ads / collection ads. Those have different creative shapes (asset_feed_spec, product_set_id, template_data). This script only handles single-image link ads. Extend it or build a sibling script.