Collection Ad API

Collection is an ad format that makes it easier for people to discover, browse and purchase products and services from their mobile device in a visual and immersive way.

You can use Canvas to design your collection ad which provides a fullscreen experience for mobile devices. Choose a Canvas fullscreen template for your collection ad or create your own customized Canvas. For background, see Ads Help Center, Canvas.

For general information on using Collections, see:

Objectives and Placements

Collection is supported in the following objectives:

  • Traffic
  • Conversions
  • Product Catalog Sales - When you use Collections from a product set. This is available on a limited basis to white-listed partners and advertisers
  • Store Visits - Available on a limited basis to white-listed partners and advertisers

Collection is only available in the mobile News Feed placement on Facebook. Learn more about objectives and placements.

Creating Collection Ads from Canvas

Feature products in a fullscreen Canvas with four products under a hero image or video which displays in mobile News Feed. Only available for the Traffic and Conversions objectives and only compatible with mobile placements.

This API is available on a limited basis to white-listed partners and advertisers. Contact your Facebook representative if you want to use this API.

For example, create an image-based ad:

curl 
  -F 'name=Canvas Collection Sample Image Creative' 
  -F 'object_story_spec={ 
    "link_data": {
      "link": "https://fb.com/canvas_doc/ELIGIBLE_CANVAS_ID", 
      "message": "Ad message", 
      "name": "name", 
      "picture": "IMAGE_URL", 
      "collection_thumbnails": [
        {"element_crops": {"100x100": [[0, 0], [100, 100]]},"element_id": "PHOTO_ELEMENT_NO_PRODUCT_TAGS_ID",},
        {"element_crops": {"100x100": [[0, 0], [100, 100]]},"element_id": "PHOTO_ELEMENT_NO_PRODUCT_TAGS_ID",},
        {"element_child_index": 0,"element_id": "PHOTO_ELEMENT_NO_PRODUCT_TAGS_ID",},
        {"element_child_index": 1,"element_id": "PHOTO_ELEMENT_NO_PRODUCT_TAGS_ID",},
      ],
    }, 
    "page_id": "PAGE_ID" 
  }' 
  -F 'access_token=ACCESS_TOKEN' 
  https://graph.facebook.com/VERSION/act_AD_ACCOUNT_ID/adcreatives

Before you create Canvas Collection Ads, provide ad creative and a Canvas with at least four photo elements or products in photo elements with product tags. Child photo elements in slideshow element are also valid.

You can use a template as quick way to create a Canvas for a specific business goal. The layout for each template is fixed, however you can replace default content with your own images, videos, products, text and links. This is available on a limited basis, contact your Facebook Representative for access. For those with access, see Canvas Ads, Using Canvas Templates.

There are two types of Canvas Collection Ads: image-based and video-based, depending on the asset in your hero media. Once you have ad creative, you can create an ad with these fields:

Field NameDescriptionTypeRequired

link

Redirect viewer to Canvas

string

Yes

collection_thumbnails

Array of thumbnails. Four thumbnails required.

array

Yes

The thumbnail fields are as follows:

Field NameDescriptionTypeRequired

element_id

Photo or product list element ID. Image appears in the canvas after someone clicks the ad. A hero image element ID is invalid.

numeric string

Yes

element_child_index

Product index in array of photo element ids with product tags. Or product index in product_id_list containing product list elements

integer greater than or equal to zero

Yes, for photo element with product tags

element_child_index

Product index in array of photo element ids with product tags.

integer greater than or equal to zero

Yes, for photo element with product tags

element_crops

A JSON object defining crop dimensions for the image specified. **Only 100x100 crop key allowed.

AdsImageCrops.

Yes, for photo element

To create a video-based ad:

curl 
  -F 'name=Canvas Collection Sample Video Creative' 
  -F 'object_story_spec={ 
    "page_id": "PAGE_ID", 
    "video_data": { 
      "call_to_action": {"type":"LEARN_MORE","value":{"link":"https://fb.com/canvas_doc/ELIGIBLE_CANVAS_ID"}}, 
      "image_url": "IMAGE_URL",
      "collection_thumbnails": [
        {"element_crops": {"100x100": [[0, 0], [100, 100]]},"element_id": "PHOTO_ELEMENT_NO_PRODUCT_TAGS_ID",},
        {"element_crops": {"100x100": [[0, 0], [100, 100]]},"element_id": "PHOTO_ELEMENT_NO_PRODUCT_TAGS_ID",},
        {"element_child_index": 0,"element_id": "PHOTO_ELEMENT_NO_PRODUCT_TAGS_ID",},
        {"element_child_index": 1,"element_id": "PHOTO_ELEMENT_NO_PRODUCT_TAGS_ID",},
      ],
      "title": "My title", 
      "video_id": "VIDEO_ID" 
    } 
  }' 
  -F 'access_token=ACCESS_TOKEN' 
  https://graph.facebook.com/VERSION/act_AD_ACCOUNT_ID/adcreatives

Engagement Audiences

You can automatically create audiences for people who interacted with your Canvas Collection ad.

This API is available on a limited basis to white-listed partners and advertisers. Contact your Facebook representative if you want to use this API.

Target your Canvas with fullscreen experience at people who tapped your Canvas Collection ad. We call this type of audience a Fullscreen Experience engagement audience. Build this audience by creating a Custom Audience with subtype set to ENGAGEMENT, object_id to CANVAS_ID, and a rule to track one of the Canvas events demonstrated below.

To create an audience of people who opened a Canvas:

curl \
    -F 'name=Collection Engagement Audience' 
    -F 'subtype=ENGAGEMENT' 
    -F 'description=People who opened this Canvas' 
    -F 'rule=[{"object_id":"CANVAS_ID","event_name":"instant_shopping_document_open"}]' 
    -F 'access_token=ACCESS_TOKEN' 
https://graph.facebook.com/VERSION/act_AD_ACCOUNT_ID/customaudiences

Or create an audience with people who clicked any links in the Canvas:

curl \
    -F 'name=Collection Engagement Audience' 
    -F 'subtype=ENGAGEMENT' 
    -F 'description=People who clicked any links in this Canvas' 
    -F 'rule=[{"object_id":"CANVAS_ID","event_name":"instant_shopping_element_click"}]'
    -F 'access_token=ACCESS_TOKEN' 
https://graph.facebook.com/VERSION/act_AD_ACCOUNT_ID/customaudiences

Collection Ads From Product Sets

Create collection ads from your Dynamic Ads catalog. A collection ad has four products under a hero image or video and displays in mobile News Feed. This is available for the advertising objectives: Traffic, Conversions and Product Catalog Sales on a limited basis to white-listed partners. Collection ads are only compatible with mobile placements.

The ad appears in News Feed, and people can see more in a fullscreen experience that opens when they tap the ad. To use a product set, you should be familiar with Dynamic Ads and alreadyhave a product catalog set up. See Dynamic Ads and Dynamic Ads, Product Catalog for more information.

Support and Limitations

You can use template URL spec and also additional_image_index when you provide the product image. See Dynamic Ads, Provide Ad Creative, Click Tracking and Templates.

Note that Engagement Custom Audiences are not supported

Creating

Before you create Collection Ads, you should provide ad creative. There are two types of Collection Ads with products: image-based and video-based. Use this new creative when creating your new Ad.

The fields used in these ads are as follows:

Field Name Description Type Required

product_set_id

Product Set to display to audience

numeric string

Yes

retailer_item_ids

Array of strings. Product ids to display from the product set. Use ["0", "0", "0", "0"] if you don't want to customize the products shown in feed.

array

Yes

description

Headline content

string

Yes

title or name

Post title

string

Yes

The creative product_set_id must match or be a subset of product_set_id in an ad set's `promoted_object. To create an image-based ad:

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\AdCreative;
use FacebookAds\Object\AdCreativeLinkData;
use FacebookAds\Object\AdCreativeObjectStorySpec;
use FacebookAds\Object\Fields\AdCreativeFields;
use FacebookAds\Object\Fields\AdCreativeLinkDataFields;
use FacebookAds\Object\Fields\AdCreativeObjectStorySpecFields;

$link_data = new AdCreativeLinkData();
$link_data->setData(array(
  AdCreativeLinkDataFields::MESSAGE => 'Ad message',
  AdCreativeLinkDataFields::LINK => '<URL>',
  AdCreativeLinkDataFields::CAPTION => '<URL>',
  AdCreativeLinkDataFields::PICTURE => $picture_url,
  AdCreativeLinkDataFields::NAME => 'name',
  AdCreativeFields::RETAILER_ITEM_IDS =>
    array(<RETAILER_ID_1>, <RETAILER_ID_2>, <RETAILER_ID_3>, <RETAILER_ID_4>),
));

$object_story_spec = new AdCreativeObjectStorySpec();
$object_story_spec->setData(array(
  AdCreativeObjectStorySpecFields::PAGE_ID => <PAGE_ID>,
  AdCreativeObjectStorySpecFields::LINK_DATA => $link_data,
));

$creative = (new AdAccount('act_<AD_ACCOUNT_ID>'))->createAdCreative(
  array(
    AdCreativeFields::ID,
    AdCreativeFields::NAME,
    AdCreativeFields::OBJECT_STORY_SPEC,
    AdCreativeFields::PRODUCT_SET_ID,
  ),
  array(
    AdCreativeFields::NAME => 'Collection Sample Image Creative',
    AdCreativeFields::OBJECT_STORY_SPEC => $object_story_spec,
    AdCreativeFields::PRODUCT_SET_ID => $product_set_id,
  ));
from facebookads.adobjects.adcreative import AdCreative
from facebookads.adobjects.adcreativeobjectstoryspec \
    import AdCreativeObjectStorySpec
from facebookads.adobjects.adcreativelinkdata \
    import AdCreativeLinkData

link_data = AdCreativeLinkData()
link_data[AdCreativeLinkData.Field.description] = 'My Description'
link_data[AdCreativeLinkData.Field.message] = 'Ad message'
link_data[AdCreativeLinkData.Field.link] = url
link_data[AdCreativeLinkData.Field.picture] = '<IMAGE_URL>'
link_data[AdCreativeLinkData.Field.name] = 'name'
link_data[AdCreative.Field.retailer_item_ids] = [
    '<RETAILER_ID_1>',
    '<RETAILER_ID_2>',
    '<RETAILER_ID_3>',
    '<RETAILER_ID_4>',
]

object_story_spec = AdCreativeObjectStorySpec()
object_story_spec[AdCreativeObjectStorySpec.Field.page_id] = <PAGE_ID>
object_story_spec[AdCreativeObjectStorySpec.Field.link_data] = link_data

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.name] = 'Collection Sample Image Creative'
creative[AdCreative.Field.object_story_spec] = object_story_spec
creative[AdCreative.Field.product_set_id] = product_set_id
creative.remote_create()
curl \
  -F 'name=Collection Sample Image Creative' \
  -F 'object_story_spec={ 
    "link_data": { 
      "caption": "<URL>", 
      "link": "<URL>", 
      "message": "Ad message", 
      "name": "name", 
      "picture": 1000003, 
      "retailer_item_ids": [ 
        "<RETAILER_ID_1>", 
        "<RETAILER_ID_2>", 
        "<RETAILER_ID_3>", 
        "<RETAILER_ID_4>" 
      ] 
    }, 
    "page_id": "<PAGE_ID>" 
  }' \
  -F 'product_set_id=1000005' \
  -F 'fields=id,name,object_story_spec,product_set_id' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.8/act_<AD_ACCOUNT_ID>/adcreatives

Image-based fields:

Field Name Description Type

picture

URL of hero image in ad. Provide picture or image_hash.

string

image_hash

Hash of hero image. Provide picture or image_hash.

string

link

Redirect viewer to this URL

string

caption

Clean url for the CTA button at the bottom of the creative.

string

To create a video-based ad:

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\AdCreative;
use FacebookAds\Object\AdCreativeObjectStorySpec;
use FacebookAds\Object\AdCreativeVideoData;
use FacebookAds\Object\Fields\AdCreativeFields;
use FacebookAds\Object\Fields\AdCreativeObjectStorySpecFields;
use FacebookAds\Object\Fields\AdCreativeVideoDataFields;

$video_data = new AdCreativeVideoData();
$video_data->setData(array(
  AdCreativeVideoDataFields::TITLE => 'My title',
  AdCreativeVideoDataFields::IMAGE_URL => $thumbnail_url,
  AdCreativeVideoDataFields::VIDEO_ID => <VIDEO_ID>,
  AdCreativeVideoDataFields::CALL_TO_ACTION => array(
    'type' => 'LEARN_MORE',
    'value' => array(
      'link' => '<URL>',
      'link_format' => 'VIDEO_LPP'
    ),
  ),
  "retailer_item_ids" => array(
    <RETAILER_ID_1>,
    <RETAILER_ID_2>,
    <RETAILER_ID_3>,
    <RETAILER_ID_4>),
));

$object_story_spec = new AdCreativeObjectStorySpec();
$object_story_spec->setData(array(
  AdCreativeObjectStorySpecFields::PAGE_ID => <PAGE_ID>,
  AdCreativeObjectStorySpecFields::VIDEO_DATA => $video_data,
));

$creative = (new AdAccount('act_<AD_ACCOUNT_ID>'))->createAdCreative(
  array(
    AdCreativeFields::ID,
    AdCreativeFields::NAME,
    AdCreativeFields::OBJECT_STORY_SPEC,
    AdCreativeFields::PRODUCT_SET_ID,
  ),
  array(
    AdCreativeFields::NAME => 'Collection Sample Video Creative',
    AdCreativeFields::OBJECT_STORY_SPEC => $object_story_spec,
    AdCreativeFields::PRODUCT_SET_ID => $product_set_id,
  ));
from facebookads.adobjects.adcreative import AdCreative
from facebookads.adobjects.adcreativeobjectstoryspec \
    import AdCreativeObjectStorySpec
from facebookads.adobjects.adcreativelinkdatacalltoaction \
    import AdCreativeLinkDataCallToAction
from facebookads.adobjects.adcreativevideodata \
    import AdCreativeVideoData

video_data = AdCreativeVideoData()
video_data[AdCreativeVideoData.Field.title] = 'My title'
video_data[AdCreativeVideoData.Field.video_id] = <VIDEO_ID>
video_data[AdCreativeVideoData.Field.image_url] = '<IMAGE_URL>'
video_data[AdCreativeVideoData.Field.call_to_action] = {
    'type': AdCreativeLinkDataCallToAction.Type.learn_more,
    'value': {
        'link': url,
        'link_format': 'VIDEO_LPP',
    },
}
video_data['retailer_item_ids'] = [
    '<RETAILER_ID_1>',
    '<RETAILER_ID_2>',
    '<RETAILER_ID_3>',
    '<RETAILER_ID_4>',
]

object_story_spec = AdCreativeObjectStorySpec()
object_story_spec[AdCreativeObjectStorySpec.Field.page_id] = <PAGE_ID>
object_story_spec[AdCreativeObjectStorySpec.Field.video_data] = video_data

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.name] = 'Collection Sample Video Creative'
creative[AdCreative.Field.object_story_spec] = object_story_spec
creative[AdCreative.Field.product_set_id] = product_set_id
creative.remote_create()
curl \
  -F 'name=Collection Sample Video Creative' \
  -F 'object_story_spec={ 
    "page_id": "<PAGE_ID>", 
    "video_data": { 
      "call_to_action": {"type":"LEARN_MORE","value":{"link":"<URL>","link_format":"VIDEO_LPP"}}, 
      "image_url": 1000003, 
      "retailer_item_ids": [ 
        "<RETAILER_ID_1>", 
        "<RETAILER_ID_2>", 
        "<RETAILER_ID_3>", 
        "<RETAILER_ID_4>" 
      ], 
      "title": "My title", 
      "video_id": "<VIDEO_ID>" 
    } 
  }' \
  -F 'product_set_id=1000006' \
  -F 'fields=id,name,object_story_spec,product_set_id' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/act_<AD_ACCOUNT_ID>/adcreatives

Video-specific fields are:

Field Name Description Type

video_id

Unique id for hero video

string

image_hash

Thumbnail image for video. Provide image_hash or image_url.

string

image_url

URL for video thumbnail. Provide image_hash or image_url.

string

link

Redirect viewer to this URL

string

link_caption

Clean url for the CTA button at the bottom of the creative.

string

link_format

Use VIDEO_LPP

string

To create a Post Click Configuration ad:

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\AdCreative;
use FacebookAds\Object\AdCreativeLinkData;
use FacebookAds\Object\Fields\AdCreativeLinkDataFields;
use FacebookAds\Object\AdCreativeObjectStorySpec;
use FacebookAds\Object\Fields\AdCreativeObjectStorySpecFields;
use FacebookAds\Object\Fields\AdCreativeFields;

$link_data = new AdCreativeLinkData();
$link_data->setData(array(
  AdCreativeLinkDataFields::MESSAGE => 'try it out',
  AdCreativeLinkDataFields::LINK => '<URL>',
  AdCreativeLinkDataFields::IMAGE_HASH => '<IMAGE_HASH>',
  'retailer_item_ids' => array(
    $retailer_id_1,
    $retailer_id_2,
    $retailer_id_3,
    $retailer_id_4
  ),
  'post_click_configuration' => array(
    'post_click_item_headline' => '{{product.name}}',
    'post_click_item_description' => '{{field.hide}}',
  ),
));

$object_story_spec = new AdCreativeObjectStorySpec();
$object_story_spec->setData(array(
  AdCreativeObjectStorySpecFields::PAGE_ID => <PAGE_ID>,
  AdCreativeObjectStorySpecFields::LINK_DATA => $link_data,
));

$creative = (new AdAccount('act_<AD_ACCOUNT_ID>'))->createAdCreative(
  array(),
  array(
    AdCreativeFields::NAME => 'Collection Sample Image Creative',
    AdCreativeFields::OBJECT_STORY_SPEC => $object_story_spec,
    AdCreativeFields::PRODUCT_SET_ID => $product_set_id,
  ));
from facebookads.adobjects.adcreative import AdCreative
from facebookads.adobjects.adcreativelinkdata import AdCreativeLinkData
from facebookads.adobjects.adcreativeobjectstoryspec \
    import AdCreativeObjectStorySpec

link_data = AdCreativeLinkData()
link_data[AdCreativeLinkData.Field.message] = 'try it out'
link_data[AdCreativeLinkData.Field.link] = '<URL>'
link_data[AdCreativeLinkData.Field.image_hash] = '<IMAGE_HASH>'
link_data[AdCreativeLinkData.Field.name] = 'name'
link_data['retailer_item_ids'] = [
    retailer_id_1,
    retailer_id_2,
    retailer_id_3,
    retailer_id_4,
]
post_click_item = {}
post_click_item['post_click_item_headline'] = '{{product.name}}'
post_click_item['post_click_item_description'] = '{{field.hide}}'
link_data['post_click_configuration'] = post_click_item

object_story_spec = AdCreativeObjectStorySpec()
object_story_spec[AdCreativeObjectStorySpec.Field.page_id] = <PAGE_ID>
object_story_spec[AdCreativeObjectStorySpec.Field.link_data] = link_data

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.name] = 'Collection Sample Image Creative'
creative[AdCreative.Field.object_story_spec] = object_story_spec
creative[AdCreative.Field.product_set_id] = product_set_id
creative.remote_create()
curl \
  -F 'name=Collection Sample Image Creative' \
  -F 'object_story_spec={ 
    "link_data": { 
      "image_hash": "<IMAGE_HASH>", 
      "link": "<URL>", 
      "message": "try it out", 
      "retailer_item_ids": [ 
        1, 
        2, 
        3, 
        4 
      ], 
      "post_click_configuration": { 
        "post_click_item_headline": "{{product.name}}", 
        "post_click_item_description": "{{field.hide}}" 
      } 
    }, 
    "page_id": "<PAGE_ID>" 
  }' \
  -F 'product_set_id=1000005' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/act_<AD_ACCOUNT_ID>/adcreatives

Post Click Configuration fields:

Field Name Description Example

post_click_configuration

Provide a content or product field template for the product headline and description.

post_click_item_headline

Item headline. Displays with template tag.

For example {{product.name}}

post_click_item_description

Item description. Displays with template tag or hidden.

For example {{product.brand}}. To hide this field, use: {{field.hide}}