> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markifact.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Catalog Ad

> Creates Advantage+ Catalog / dynamic Ads (carousel or single image) via product sets (bulk mode)

Creates Advantage+ Catalog / dynamic Ads (carousel or single image) via product sets (bulk mode). Meta has deprecated the legacy Collection ad format with its separate Instant Experience; the replacement is format automation, where one catalog carousel is rendered as a collection where that performs better. Meta applies this automatically to catalog ads created here, so no extra setting is needed, and it cannot be switched off through the API; use Ads Manager if a client needs collection disabled. By default it creates the full ad. It can also run in creative-only mode, which returns a creative\_id without attaching it to an ad; that creative\_id can then be used with meta\_ads\_replace\_ad\_creative. It also supports detailed-results mode: by default the response returns only IDs, while return\_detailed\_results=true returns per-row success and failure details. Detailed results are recommended for AI agents.

| | |
| - | - |
| **App** | Meta Ads |
| **Operation ID** | `meta_ads_create_catalog_ad` |
| **Type** | Action |
| **Connection** | `meta_ads` (required) |
| **Credits per run** | 1 |
| **Agent / MCP tool** | Yes |
| **Requires approval** | Yes (write operation) |

## Inputs

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `account` | DynamicAccount | Yes | - | Select the Meta Ads account, ask the user for it if not provided |
| `page` | string or SelectItem | Yes | - | Select Facebook page, ask the user for it if not provided |
| `instagram_user_id` | string or SelectItem | No | - | Optional Instagram account override. Leave empty in nearly all cases — the Instagram account linked to the selected Page is used automatically. Only set this when the user wants to advertise with a different Instagram account they have access to. Value is the numeric IG user/business account id. |
| `structured_data` | array (also accepts a comma-separated string) | Yes | - | Structured data containing catalog ad information. Each row represents one catalog ad. Required columns: adset\_id, product\_set\_id, ad\_name, website\_url, primary\_text, headline. Optional columns: primary\_text\_2 through primary\_text\_5, headline\_2 through headline\_5, and description\_2 through description\_5 (additional text variations, Meta picks the best combination per viewer; primary\_text\_1/headline\_1/description\_1 are accepted as aliases of the bare columns), description, url\_parameters, ad\_status (ACTIVE/PAUSED), ad\_type (carousel/single\_image), carousel\_card\_type (use value 'slideshow' to enable slideshow cards; any other value ignored), format\_option (Meta card layout, sent as given: 'carousel\_images\_multi\_items' shows several product images per card, 'carousel\_images\_single\_item' one image per card and needs multi\_share\_end\_card false, 'carousel\_slideshows' slideshow cards; takes precedence over carousel\_card\_type), multi\_share\_end\_card (only set FALSE by putting 'false'; omitted otherwise), show\_multiple\_images (only set TRUE by putting 'true'; omitted otherwise), static\_card\_media\_url, static\_card\_headline, static\_card\_description (if static\_card\_media\_url AND static\_card\_headline provided, a static card is prepended as first child attachment; supports both images and videos; description optional), call\_to\_action (optional, e.g. SHOP\_NOW, LEARN\_MORE, SIGN\_UP; defaults to SHOP\_NOW if omitted or invalid), disable\_creative\_enhancements (set to True to disable Meta's automatic creative optimizations like enhanced CTAs, image cropping, text optimizations, dynamic media, etc.), disable\_multi\_advertiser\_ads (set to True to opt out of showing your ad alongside other ads), ad\_start\_time (schedule ad start, format: YYYY-MM-DD HH:MM or YYYY-MM-DD, in the ad account's timezone), ad\_end\_time (schedule ad end, format: YYYY-MM-DD HH:MM or YYYY-MM-DD, in the ad account's timezone). For single image ads set ad\_type to 'single\_image' which internally sets force\_single\_link=true. Case-insensitive matching is applied for ad\_type, carousel\_card\_type, and the boolean flags. Note: user can provide direct media URLs or Google Drive share links; Markifact will convert Drive links to direct URLs automatically, the only requirement is that the file sharing is set to 'Anyone with the link'. |
| `creative_only` | boolean | No | `False` | Set to true to create only the Meta ad creative without creating an ad. Useful when editing an existing ad: create a new catalog creative with the updated product set, static card, text, or template data, then attach it using replace\_ad\_creative. When true, adset\_id is not required since you're not creating a new ad, just an ad creative. Returns creative IDs instead of ad IDs. Default is false. |
| `return_detailed_results` | boolean | No | `False` | If true, returns per-row results (success\_count, failed\_count, total\_count, results\[]) and does NOT raise an error on partial failures so the workflow can continue. If false (default), returns a simple summary and raises an error if any row fails. |

### SelectItem

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `value` | string | Yes | - | The value of the selectable item. |
| `label` | string | Yes | - | The label of the selectable item, used for display purposes. If not provided, defaults to the value. |

## Output

**Type**: `Dict`

Returns created ad details, a list of ad IDs and count.

**Fields**: `ad_ids`, `created_count`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.