Meta Ads Write
User wants to create an Advantage+ Catalog ad / Dynamic Product Ad (DPA) — ads that automatically show products from their Meta product catalog
POST https://api.adspirer.ai/api/v1/tools/create_meta_catalog_campaign/execute
Authorization: Bearer sk_live_... — your Adspirer API key (required)Content-Type: application/json (required)Idempotency-Key: <uuid> — recommended for write operations to make retries safeAll tool arguments are wrapped in an arguments object.
| Field | Type | Description |
|---|---|---|
campaign_name | string required | Name for the campaign. |
product_catalog_id | string required | Product catalog ID (required). Get it from list_meta_catalogs. |
product_set_id | string required | Product set ID to advertise (required). Get it from list_meta_product_sets — use the catalog's 'All Products' set to advertise everything, or a narrower set to boost specific items. |
primary_text | string required | Primary ad text shown above the products (max ~125 chars). You may use {{product.name}} / {{product.current_price}} tokens. |
audience_type | string optional | 'prospecting' (broad audience — find new buyers) or 'retargeting' (show products to people who already engaged via the Pixel). Retargeting REQUIRES pixel_id. default: "prospecting" |
destination_type | string optional | Where the ad sends people. 'WEBSITE' (default — your product pages off Facebook) or 'FACEBOOK' (an on-Facebook product listing / Shop). Use WEBSITE unless you run a Facebook/Instagram Shop. default: "WEBSITE" |
budget_daily | number optional | Daily budget in account currency (e.g. 20.0). Provide this OR budget_lifetime. |
budget_lifetime | number optional | Lifetime budget in account currency. Provide this OR budget_daily. Requires end_time. |
ad_account_id | string optional | Meta ad account ID. Required for multi-account users. Get from get_connections_status. |
headline | string optional | Headline. Defaults to the product name ({{product.name}}) when omitted. |
description | string optional | Description line. Defaults to the product price ({{product.current_price}}) when omitted. |
call_to_action | string optional | CTA button type (e.g. SHOP_NOW, LEARN_MORE, BUY_NOW). default: "SHOP_NOW" |
landing_page_url | string optional | Optional override landing page. Defaults to each product's own URL ({{product.url}}). |
facebook_page_id | string optional | Facebook Page ID. Auto-detected from the ad account if omitted. |
instagram_account_id | string optional | Instagram account ID for IG placements (optional, auto-detected). |
pixel_id | string optional | Meta Pixel ID. REQUIRED when audience_type='retargeting' (used to build the viewed/added-to-cart product audience). Optional for prospecting. Get it from list_meta_pixels. |
pixel_event_name | string optional | Conversion event to optimize/track (default PURCHASE). |
retargeting_preset | string optional | Retargeting audience preset (audience_type='retargeting' only): 'viewed_not_purchased' (default, 14d), 'carted_not_purchased' (7d), 'all_engaged_not_purchased' (30d), 'cross_sell_purchasers' (180d), or 'custom'. |
retention_days | integer optional | Override the lookback window (days) for the retargeting audience. |
include_events | array optional | For retargeting_preset='custom': pixel events to INCLUDE (e.g. ['ViewContent','AddToCart']). |
exclude_events | array optional | For retargeting_preset='custom': pixel events to EXCLUDE (e.g. ['Purchase'] to skip recent buyers). |
locations | array optional | List of country codes / location specs (default ['US']). |
age_min | integer optional | Minimum age (default 18). default: 18 |
age_max | integer optional | Maximum age (default 65). default: 65 |
genders | array optional | ['male'] / ['female'] / omit for all. |
interests | array optional | Interest targeting specs from search_meta_targeting. |
behaviors | array optional | Behavior targeting specs from search_meta_targeting. |
custom_audiences | array optional | Custom audience IDs to include (from list_meta_custom_audiences). |
excluded_custom_audiences | array optional | Custom audience IDs to exclude. |
advantage_audience | boolean optional | Enable Advantage+ Audience expansion. |
special_ad_categories | array optional | HOUSING/EMPLOYMENT/CREDIT/etc. if applicable. |
campaign_budget_optimization | boolean optional | Enable CBO (budget at campaign level). default: false |
end_time | string optional | Campaign/ad set end time (ISO 8601). Required for lifetime budget. |
ad_set_name | string optional | Custom ad set name. |
ad_name | string optional | Custom ad name. |
{
"arguments": {
"campaign_name": "string",
"product_catalog_id": "string",
"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"
}
}
{
"success": true,
"data": {
"text": "(tool-specific textual output for create_meta_catalog_campaign)",
"quota": {
"used": 42,
"limit": 150,
"tier": "plus",
"period_end": "2026-05-01"
}
},
"tool": "create_meta_catalog_campaign"
}
{
"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": "create_meta_catalog_campaign"
}
{
"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": "create_meta_catalog_campaign",
"quota": {
"used": 150,
"limit": 150,
"tier": "plus",
"period_end": "2026-05-01",
"upgrade_url": "https://adspirer.ai"
}
}
Interactive: Swagger UI
Machine-readable: OpenAPI 3.1 spec · llms-full.txt
Adspirer REST API — get an API key at adspirer.ai/keys · adspirer.ai