Dynamic Media

Dynamic media allows advertisers to deliver video assets from their catalog in their Advantage+ catalog ads.

Before You Begin

You will need:

• A product catalog with existing products
• A video for each product item in a downloadable video URL format

See the Advantage+ catalog ads documentation to learn more about how they work.

Limitations

• We recommend a minimum of 20 products, but there are no required minimums.
• Each video size should not exceed 200MB. There are no length restrictions.
• Videos must be in one of the following formats: 3g2, 3gp, 3gpp, asf, avi, dat, divx, dv, f4v, flv, gif, m2ts, m4v, mkv, mod, mov, mp4, mpe, mpeg, mpeg4, mpg, mts, nsv, ogm, ogv, qt, tod, ts, vob, or wmv.
• The video_fetch_status may show as NO_STATUS until the video is used in an ad or another event that requires the video is triggered.

Add Videos to Your Catalog

There are 3 ways to add videos to product items in your catalog: catalog feed file, catalog batch API, and manual upload via your Commerce Manager.

Add videos with the catalog feed file

Step 1. Prepare Your Catalog Feed File

You can use one of the following processes to implement your catalog feed file.

• Process 1: Change the main feed

  • Add a video[0].url column to your existing catalog feed file, populate the video URL to only the selected products, and leave it empty for other product rows.
  • Additional videos for the same product can be added with additional columns: video[1].url, video[2].url, video[3].url, etc.
  • Tags may be added to the videos by including the tags in separate columns. For example: video[0].tag[0], video[0].tag[1], video[1].tag[0], and so on.
• Process 2: Supplemental feed
  Prepare a supplementary catalog feed file to supplement an existing feed upload. This supplemental feed can only add or replace videos to already existing product items. Add a video[0].url column and an ID column to associate the video with the product item ID.

Optional:
Instead of the video[0].url column, you can create a column called video and add tags to the video. The video column can contain multiple video URLs per product and multiple tags per URL encoded in a JSON format. If you choose to use a tag column for the product set filter, you’ll need to add this column to the feed file too.

For an XML feed, video URLs can be added using <video> tags like:

<video>
    <url>https://{URL1}</url>
    <tag>video_product_set1</tag>
    <tag>video_product_set2 </tag>
</video>
<video>
    <url>https://{URL2}</url>
    <tag>video_product_set1</tag>
</video>

Query video data from the product item API

The videos, videos_metadata, and video_fetch_status fields are available on the catalog APIs to retrieve catalog product video details.

curl -i GET \
  "http://graph.facebook.com/v24.0/<PRODUCT_ITEM_ID>?fields=videos,videos_metadata,video_fetch_status"

For more details on video information, see the Product Item details.

Add videos with the catalog batch API

Updates to product items are supported using the /{product_catalog_id}/items_batch endpoint. You can make a POST API call with the video field, which is an array of URLs.

curl \
  -d @body.json \
  -H "Content-Type: application/json"

> cat body.json
{
  "access_token": "<ACCESS_TOKEN>",
  "item_type": "PRODUCT_ITEM",
  "requests": [
    {
      "method": "CREATE",
      "data": {
        "id": "retailer-2",
        "availability": "in stock",
        "brand": "BrandName",
        "google_product_category": "t-shirts",
        "description": "product description",
        "image_link": "http://www.images.example.com/t-shirts/1.png",
        "title": "product name",
        "price": "10.00 USD",
        "shipping": [
          {
            "shipping_country": "US",
            "shipping_region": "CA",
            "shipping_service": "service",
            "shipping_price_value": "10",
            "shipping_price_currency": "USD"
          }
        ],
        "condition": "new",
        "link": "http://www.images.example.com/t-shirts/1.png",
        "item_group_id": "product-group-1",
        "video": [
          {"url": "http://www.jaspersmarket-example1.com/video-file.avi", "tag": ["Optional Tag1", "Optional Tag2"]}, 
          {"url": "http://www.jaspersmarket-example2.com/video-file.avi", "tag": ["Optional Tag1", "Optional Tag2"]}
        ]
      }
    },
    {
      "method": "UPDATE",
      "data": {
        "availability": "out of stock",
        "id": "retailer-3",
        "video": [
          {
            "url": "https://yourvideo.com/demo.mp4?q=1411"
          },
          {
            "url": "https://yourvideo.com/demo.mp4?q=1421"
          }
        ]
      }
    }
  ]
}

See this example in the Graph API Explorer.

Create Ads with Dynamic Media

When creating ads, there are three types of options that leverage video from the catalog:

• Carousel/Collection dynamic media (recommended)
• Show video when available (only available for single video format)
• Single image opted into dynamic media

Note: Selecting the dynamic media type with the API is similar to selecting the Dynamic Media options in Ads Manager. With changes starting in September 2025, Advantage+ catalog ads will be opted into using dynamic media by default.

Dynamic media type ads

When creating an ad creative object with the act_<AD_ACCOUNT_ID>/adcreatives endpoint

• Starting September 2025, Advantage+ catalog ads will begin delivering catalog product videos by default. You may set media_type_automation to OPT_out to turn off catalog product videos from surfacing in ads.
• The media_type_automation key works with Carousel, Collection, and Single Image formats.

curl -X POST \
-F 'name=Dynamic Media Ad Creative' \
-F 'object_story_spec={
    ...
  }' \
-F 'degrees_of_freedom_spec={
    "creative_features_spec": {
      "media_type_automation": {
        "enroll_status": "OPT_IN"
      }
    }
  }' \
-F 'product_set_id=<PRODUCT_SET_ID>' \
https://graph.facebook.com/v24.0/act_<AD_ACCOUNT_ID>/adcreatives

Likewise, if creating an Advantage+ catalog ad object with the act_<AD_ACCOUNT_ID>/ads endpoint, the ad will begin delivering available catalog product videos by default. You may set the media_type_automation key to OPT_out to turn off catalog product videos from surfacing in ads.

curl -X POST \
  -F 'adset_id=<ADSET_ID>' \
  -F 'creative={
    "name": "Dynamic Media Ad Creative",
    "object_story_spec": {
      ...
    },
    "degrees_of_freedom_spec": {
      "creative_features_spec": {
        "media_type_automation": {
          "enroll_status": "OPT_IN"
        }
      }
    },
    "product_set_id": "<PRODUCT_SET_ID>"
  }' \
https://graph.facebook.com/v24.0/act_<AD_ACCOUNT_ID>/ads

Dynamic media ads (with Collection format)

• Dynamic media only replaces hero media. Product thumbnails in pre-click experience and in Instant Experiences will always be images.
• If opted into dynamic media and if the product video is available, we will replace the dynamic video hero media with a product video. Advantage+ catalog ads in Collection format will be opted into dynamic media by default and begin delivering catalog product videos starting September 2025. You may continue to set media_type_automation to OPT_OUT to turn off catalog product videos from surfacing in ads.
• Dynamic media only replaces dynamic video hero media when opted-in. Currently a static hero image and video won’t be replaced by a product video, i.e., The image slideshow experience is replaced with a product video.

Example Creative Spec for Collection with Dynamic Media

curl -X POST \
-F 'name=Dynamic Media Ad Creative' \
-F 'object_story_spec={
      "template_data": {
          ...
          "format_option": "collection_video",
          "link": "https://fb.com/canvas_doc/<CANVAS_ID>",
          "message": "Your Collection Ad",
          ...
    }
  }' \
-F 'degrees_of_freedom_spec={
    "creative_features_spec": {
      "media_type_automation": {
        "enroll_status": "OPT_IN"
      }
    }
  }' \
-F 'product_set_id=<PRODUCT_SET_ID>' \
https://graph.facebook.com/v24.0/act_<AD_ACCOUNT_ID>/adcreatives

Dynamic media ads (Show videos when available)

In the object_story_spec, change format_option to single_video. This is only available for single image/video format.

curl -X POST \
  -F 'adset_id=<ADSET_ID>' \
  -F 'creative={
    "name": "Dynamic Media Ad Creative",
    "object_story_spec": {
      "page_id": "<PAGE_ID>",
      "template_data": {
        ...
        "format_option": "single_video",
        ...
      }
    },
    "product_set_id": "<PRODUCT_SET_ID>"
    }' \
https://graph.facebook.com/v24.0/act_<AD_ACCOUNT_ID>/ads

Dynamic media ads (Single image opted into dynamic media)

In the object_story_spec, the format_option of single_image will show dynamic media when opted into media_type_automation.

Starting September 2025, Advantage+ catalog ads using format_option of single_image will be opted into dynamic media by default and will surface available catalog product videos in ads. You may set media_type_automation to OPT_OUT to turn off catalog product videos from surfacing in ads.

curl -X POST \
  -F 'adset_id=<ADSET_ID>' \
  -F 'creative={
 "name": "Dynamic Media Ad Creative",
 "object_story_spec": {
   "page_id": "<PAGE_ID>",
   "template_data": {
     "format_option": "single_image"
   }
 },
 "degrees_of_freedom_spec": {
   "creative_features_spec": {
     "media_type_automation": {
       "enroll_status": "OPT_IN"
     }
   }
 }
},
    "product_set_id": "<PRODUCT_SET_ID>"
    }' \
https://graph.facebook.com/v24.0/act_<AD_ACCOUNT_ID>/ads

Optional: Opt into or out of automatic video cropping

Use the video_crop_style field to control automatic video cropping. The available values are AUTO or NONE.

To opt out of automatic video cropping, set video_crop_style to NONE, or remove customizations from the media_type_automation settings.

curl -X POST \
  -F 'adset_id=<ADSET_ID>' \
  -F 'creative={
    "name": "Dynamic Media Ad Creative",
    "object_story_spec": {
      ...
    },
    "degrees_of_freedom_spec": {
      "creative_features_spec": {
        "media_type_automation": {
          "customizations": {
            "video_crop_style": "NONE"
          },
          "enroll_status": "OPT_IN"
        }
      }
    },
  "product_set_id": "<PRODUCT_SET_ID>"
  }' \
https://graph.facebook.com/v24.0/act_<AD_ACCOUNT_ID>/ads

Auto-crop only applies to videos that don't meet the placement size requirements, and auto-crop is currently designed to primarily fit the video into the player's viewport.

If there is a video that matches the aspect ratio for the ad placement, that video will be returned. If all the aspect ratios of a given product video are provided, auto-crop will not be applied. Otherwise, the ad will select a video of the item and check the auto-crop setting: AUTO returns the auto-cropped video and NONE returns the original video.

Dynamic Media Insights

Video Engagement metrics from the Ads Manager can also be queried on the API. Use the following chart for comparison.

Example Request

curl GET \
  -d 'access_token=<ACCESS_TOKEN>' \
  -d 'fields=impressions,video_continuous_2_sec_watched_actions,actions,video_thruplay_watched_actions' \
https://graph.facebook.com/v24.0/<AD_ID>/insights

For more information, see the Insights API documentation.