API Reference › Meta Ads › add_meta_catalog_ad_set

add_meta_catalog_ad_set

Meta Ads Write

User wants to add ANOTHER ad set to an existing Advantage+ Catalog campaign — e

Endpoint

POST https://api.adspirer.ai/api/v1/tools/add_meta_catalog_ad_set/execute

Headers

Description

User wants to add ANOTHER ad set to an existing Advantage+ Catalog campaign — e.g. one campaign running multiple strategies in parallel: ad set A = prospecting, ad set B = viewed-not-purchased retargeting, ad set C = a different product set or budget. Each catalog ad set independently controls its product set, audience strategy, budget, targeting, and retention window. The catalog is inherited from the parent campaign. Use this AFTER create_meta_catalog_campaign to layer on more ad sets. Adds the ad set + its first catalog ad, PAUSED.

Request body

All tool arguments are wrapped in an arguments object.

FieldTypeDescription
campaign_idstring requiredThe existing Advantage+ Catalog campaign ID to add the ad set to. Get it from create_meta_catalog_campaign or list_meta_campaigns.
product_set_idstring requiredProduct set this ad set promotes (required). From list_meta_product_sets.
primary_textstring requiredPrimary ad text for this ad set's first ad.
audience_typestring optional'prospecting' (broad) or 'retargeting' (pixel product audience). Retargeting REQUIRES pixel_id. default: "prospecting"
destination_typestring optional'WEBSITE' (default) or 'FACEBOOK' (on-Facebook Shop). default: "WEBSITE"
budget_dailynumber optionalDaily budget for THIS ad set. Provide unless the campaign uses CBO.
budget_lifetimenumber optionalLifetime budget for this ad set (requires end_time).
ad_account_idstring optionalMeta ad account ID. Auto-detected if omitted.
headlinestring optionalHeadline (defaults to {{product.name}}).
descriptionstring optionalDescription (defaults to {{product.current_price}}).
call_to_actionstring optionalCTA button type. default: "SHOP_NOW"
landing_page_urlstring optionalStorefront URL (derived from the catalog if omitted).
facebook_page_idstring optionalFacebook Page ID (auto-detected).
instagram_account_idstring optionalInstagram account ID (auto-detected).
pixel_idstring optionalPixel ID. REQUIRED for retargeting.
pixel_event_namestring optionalConversion event (default PURCHASE).
retargeting_presetstring optionalviewed_not_purchased | carted_not_purchased | all_engaged_not_purchased | cross_sell_purchasers | custom.
retention_daysinteger optionalRetargeting lookback window (days).
include_eventsarray optionalcustom preset: pixel events to include.
exclude_eventsarray optionalcustom preset: pixel events to exclude.
locationsarray optionalCountry codes (default ['US']).
age_mininteger optionalMin age. default: 18
age_maxinteger optionalMax age. default: 65
gendersarray optional['male']/['female']/omit.
interestsarray optionalInterest targeting specs.
behaviorsarray optionalBehavior targeting specs.
custom_audiencesarray optionalCustom audience IDs to include.
excluded_custom_audiencesarray optionalCustom audience IDs to exclude.
advantage_audienceboolean optionalAdvantage+ Audience expansion.
campaign_budget_optimizationboolean optionalSet true if the parent campaign uses CBO (then omit budget_daily). default: false
daily_min_spend_targetnumber optionalCBO: min daily spend for this ad set.
daily_spend_capnumber optionalCBO: max daily spend for this ad set.
end_timestring optionalAd set end time (ISO 8601).
ad_set_namestring optionalCustom ad set name.
ad_namestring optionalCustom ad name.

Example request

{
  "arguments": {
    "campaign_id": "<campaign_id>",
    "product_set_id": "string",
    "primary_text": "string",
    "audience_type": "prospecting",
    "destination_type": "WEBSITE",
    "budget_daily": 1.0,
    "budget_lifetime": 1.0,
    "ad_account_id": "string",
    "headline": "string"
  }
}

Example responses

200 — Success

{
  "success": true,
  "data": {
    "text": "(tool-specific textual output for add_meta_catalog_ad_set)",
    "quota": {
      "used": 42,
      "limit": 150,
      "tier": "plus",
      "period_end": "2026-05-01"
    }
  },
  "tool": "add_meta_catalog_ad_set"
}

400 — Tool-level error (bad arguments / multi-account selection)

{
  "success": false,
  "error": "You have 25 meta_ads accounts connected. Please specify which account to use by passing the ad_account_id parameter:\n  - Acme Holdings (ad_account_id=\"act_123456789\")\n  - Acme EU (ad_account_id=\"act_987654321\")",
  "is_error": true,
  "tool": "add_meta_catalog_ad_set"
}

402 — Quota exhausted

{
  "success": false,
  "error": "\ud83d\udea8 Monthly limit reached (150/150 tool calls on Plus tier).\nUpgrade to Pro at https://adspirer.ai to keep building.",
  "is_error": true,
  "tool": "add_meta_catalog_ad_set",
  "quota": {
    "used": 150,
    "limit": 150,
    "tier": "plus",
    "period_end": "2026-05-01",
    "upgrade_url": "https://adspirer.ai"
  }
}

Try it live

Interactive: Swagger UI

Machine-readable: OpenAPI 3.1 spec · llms-full.txt

More tools: Meta Ads · All tools

Adspirer REST API — get an API key at adspirer.ai/keys · adspirer.ai