Catalog carousel ad
A dynamic carousel whose cards are generated from a catalog product set.
A catalog carousel (dynamic product ad) builds its cards automatically from a Meta catalog product set — Meta picks which products to show per user. Unlike a manual carousel, you don't supply per-card creatives.
It has two variants (see Two variants below), distinguished by how many creatives you send:
- With intro card — exactly one creative (the intro / cover card).
- Without intro card — an empty
creatives: [].
When to use this
You want Meta to assemble and personalise carousel cards from your catalog instead of hand-picking each card.
Example body
POST /meta/launches
Every key applicable to a catalog-carousel ad with an intro card, with sample values. Required: adName, adSets, adProfiles, cta, webLink, productSetId.
{
"adAccountId": "01H8Y4...",
"platform": "meta",
"ads": [
{
"adName": "Spring Catalog Carousel",
"adSets": ["123456789012345"],
"creativeDetails": {
"groupType": "catalog_carousel",
"creatives": [{ "_id": "01H8YA..." }]
},
"adProfiles": {
"facebook_page_id": "123456789012345",
"instagram_account_id": "987654321098765",
"page_backed_instagram_account_id": null
},
"productSetId": "678901234567",
"productSetData": {
"business_id": "1029384756",
"catalog_id": "456789012345",
"product_set_id": "678901234567"
},
"cta": "SHOP_NOW",
"defaultPrimaryText": "Picked for you from the spring range.",
"primaryTextVariations": ["Personalised spring picks", "Your spring edit"],
"defaultHeadline": "Spring Sale",
"headlineVariations": ["Up to 40% off", "New arrivals"],
"adDescription": "Free shipping on orders over $50.",
"webLink": "https://example.com/spring",
"displayLink": "example.com/spring",
"utm": "utm_source=facebook&utm_medium=cpc&utm_campaign=spring",
"leadGenFormId": null,
"adSchedule": { "startDate": "2026-06-01T00:00:00Z", "endDate": "2026-06-30T23:59:59Z" },
"promoCodeDetails": { "type": "manual", "manualCodes": ["SPRING40", "EARLYBIRD"] },
"aiMediaDisclosure": true
}
]
}Full schema: Create a launch.
Two variants: intro card or none
Both variants send creativeDetails (carrying groupType: catalog_carousel) so the ad type resolves. The difference is the creatives array:
- With intro card —
creativeshas exactly one entry (the intro / cover card), as in the example above. - Without intro card —
creativesis empty:
"creativeDetails": {
"groupType": "catalog_carousel",
"creatives": []
}Sending 2 or more creatives is rejected (400) — at most one is allowed (the intro card).
Required fields
adName,adSetscreativeDetails— withgroupType: catalog_carouseland acreativesarray of 0 or 1 entries (1 = intro card, 0 = no intro card)adProfiles— at least one offacebook_page_id/instagram_account_idctawebLinkproductSetId(or fullproductSetData) — the catalog product set Meta draws cards from
Missing productSetId is rejected (400). The server mints ads[].id and creativeDetails.groupId.
Optional fields
defaultPrimaryText, defaultHeadline (+variations), adDescription, displayLink, utm, adSchedule, promoCodeDetails, leadGenFormId, aiMediaDisclosure. (No per-card text — cards come from the catalog.)
Field notes
productSetId— required; the product set Meta draws cards from. From List catalogs.creatives[]— 0 or 1 entries. One is the intro / cover card (an uploaded asset); none means no intro card.
Gotchas
- The product set must be non-empty and approved in the catalog, or the ad fails at launch.
- Per-card
cardTitle/cardDescriptionare ignored — cards come from the catalog. - Not supported on App-conversion ad sets — see Ad set compatibility.
