AdnovaDocs
Ad Launcher

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, adSets
  • creativeDetails.creatives — 2 or more, each with _id
  • adProfiles — at least one of facebook_page_id / instagram_account_id
  • cta
  • webLink

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-level webLink takes precedence over the ad-level webLink for that card.
  • carouselPortrait._id — optional per-card 9:16 asset for Stories / Reels.

Gotchas

  • Portrait cards disallow primaryTextVariations. If any card carries a carouselPortrait, sending primaryTextVariations is rejected (400). Use a single defaultPrimaryText instead.
  • All non-portrait cards should share an aspect ratio (Meta requires square 1:1).
  • Every per-card _id must be uploaded and complete before launching.