Carousel ad
Launch a multi-card carousel — each card its own creative, title, and link.
A carousel ad shows 2–10 swipeable cards in one ad unit. Each card is a separate creative with its own title, description, and click-through link.
When to use this
You want to showcase multiple products or angles in a single ad that users swipe through.
Example body
POST /meta/launches
Every key applicable to a carousel ad, with sample values. Per-card fields (cardTitle / cardDescription / webLink) live on each creative. Required: adName, adSets, 2+ creatives[]._id, adProfiles, cta, webLink.
{
"adAccountId": "01H8Y4...",
"platform": "meta",
"ads": [
{
"adName": "Spring Carousel",
"adSets": ["123456789012345"],
"creativeDetails": {
"groupType": "carousel",
"creatives": [
{
"_id": "01H8YA...",
"cardTitle": "Dresses",
"cardDescription": "Up to 40% off",
"webLink": "https://example.com/dresses",
"productHeadline": "Best of dresses",
"productDescription": "Hand-picked styles",
"carouselPortrait": { "_id": "01H8YP..." }
},
{
"_id": "01H8YB...",
"cardTitle": "Shoes",
"cardDescription": "New arrivals",
"webLink": "https://example.com/shoes",
"productHeadline": "Step into spring",
"productDescription": "Fresh footwear"
}
]
},
"adProfiles": {
"facebook_page_id": "123456789012345",
"instagram_account_id": "987654321098765",
"page_backed_instagram_account_id": null
},
"cta": "SHOP_NOW",
"defaultPrimaryText": "Swipe through the spring edit.",
"defaultHeadline": "Spring Sale",
"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.
Required fields
adName,adSetscreativeDetails.creatives— 2 or more, each with_idadProfiles— at least one offacebook_page_id/instagram_account_idctawebLink
Fewer than 2 creatives is rejected (400). The server mints ads[].id and creativeDetails.groupId.
Optional fields
Per-card cardTitle / cardDescription / webLink / carouselPortrait; ad-level defaultPrimaryText, defaultHeadline (+variations), adDescription, displayLink, utm, adSchedule, promoCodeDetails, leadGenFormId, aiMediaDisclosure.
Custom-placement portrait cards
To run a 9:16 portrait variation of a card for Stories / Reels, upload the portrait asset and reference its fileId as carouselPortrait._id on that card.
{ "_id": "01H8YA...", "cardTitle": "Dresses", "carouselPortrait": { "_id": "01H8YP..." } }Only _id is needed — the launcher hydrates the portrait's file details.
Field notes
creatives[]order = card order on the ad.cardTitle/cardDescription/webLink— per-card overrides. A card-levelwebLinktakes precedence over the ad-levelwebLinkfor that card.carouselPortrait._id— optional per-card 9:16 asset for Stories / Reels.
Gotchas
- Portrait cards disallow
primaryTextVariations. If any card carries acarouselPortrait, sendingprimaryTextVariationsis rejected (400). Use a singledefaultPrimaryTextinstead. - All non-portrait cards should share an aspect ratio (Meta requires square 1:1).
- Every per-card
_idmust be uploaded and complete before launching.
