Back to News for Developers


September 12, 2017BySeema Harindran Puthyapurayil

Multi Product Ads allow an advertiser to display multiple product images in one ad unit that can appear in mobile or desktop News Feed. When a person clicks on a product image or description, s/he will be taken to the related product page. With the multi-link feature, each image in the Page post link ad can direct to a unique destination URL.

Multi Product Ad Examples:

Desktop News Feed

Mobile News Feed

Creating a Multi Product Ad

There are two steps to creating a Multi Product Ad, creating the ad creative and then using the creative in an ad.

Create the Ad Creative

Like most ad creatives, Multi Product Ads also rely on creating page posts for specifying the creative content. First create an unpublished page post using the child_attachments field of object_story_spec to specify an array of link objects. On each link object, picture, name and description are optional.

There are some recommendations for different components of the creative:

  • The headline should be a maximum of 120 characters.
  • Images should be at least 548x548px and be of high resolution, with the product being as big as possible. It is also recommended to have a consistent per-image background color.
  • The product name should be a maximum of 35 characters.
  • The product description should be a maximum of 30 characters.

Here is an example using the description to show the price of each product, but it also can be used to show other things like discount rates or extra details about the product. It is recommended that the advertiser try out different combinations of products and creatives when running campaigns and puts spend towards the combination that performs the best. Products can be combined by:

  • Products that are usually purchased together.
  • Products that are similar to each other.
  • Products that the advertiser wants to remarket to the user.

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Fields\AdCreativeFields;
use FacebookAds\Object\ObjectStorySpec;
use FacebookAds\Object\Fields\ObjectStorySpecFields;
use FacebookAds\Object\ObjectStory\LinkData;
use FacebookAds\Object\Fields\ObjectStory\LinkDataFields;
use FacebookAds\Object\ObjectStory\AttachmentData;
use FacebookAds\Object\Fields\ObjectStory\AttachmentDataFields;
use FacebookAds\Object\AdGroup;
use FacebookAds\Object\Fields\AdGroupFields;

// Create a new AdCreative
$creative = new AdCreative(null, $account_id);
$creative->{AdCreativeFields::NAME} = 'Multi Product Ad Creative';

// Create a new ObjectStorySpec to create an unpublished post
$story = new ObjectStorySpec();
$story->{ObjectStorySpecFields::PAGE_ID} = $page_id;

// Create LinkData object representing data for a link page post
$link = new LinkData();
$link->{LinkDataFields::LINK} = '';
$link->{LinkDataFields::CAPTION} = 'WWW.EXAMPLE.COM';

// Create 3 products as this will be a multi-product ad
$product1 = (new AttachmentData())->setData(array(
  AttachmentDataFields::LINK => '',
  AttachmentDataFields::IMAGE_HASH => '<AD_IMAGE_HASH_1>',
  AttachmentDataFields::NAME => 'Product 1',
  AttachmentDataFields::DESCRIPTION => '$4.99',

$product2 = (new AttachmentData())->setData(array(
  AttachmentDataFields::LINK => '',
  AttachmentDataFields::IMAGE_HASH => '<AD_IMAGE_HASH_2>',
  AttachmentDataFields::NAME => 'Product 2',
  AttachmentDataFields::DESCRIPTION => '$10.99',

$product3 = (new AttachmentData())->setData(array(
  AttachmentDataFields::LINK => '',
  AttachmentDataFields::IMAGE_HASH => '<AD_IMAGE_HASH_3>',
  AttachmentDataFields::NAME => 'Product 3',
  AttachmentDataFields::DESCRIPTION => '$29.99',

// Add the products into the child attachments
$link->{LinkDataFields::CHILD_ATTACHMENTS} = array(

$story->{ObjectStorySpecFields::LINK_DATA} = $link;
$creative->{AdCreativeFields::OBJECT_STORY_SPEC} = $story;
curl \
-F 'name=Multi Product Ad Creative' \
-F 'object_story_spec={"page_id":<PAGE_ID>,"link_data":{"message":"Try it out","link":"","caption":"WWW.EXAMPLE.COM", "child_attachments":[{"link":"","name":"product 1","description":"$10.99", "image_hash":"<AD_IMAGE_HASH_1>"},{"link":"","name":"product 2","description":"$20.99", "image_hash":"<AD_IMAGE_HASH_2>"},{"link":"","name":"product 3","description":"$30.99", "image_hash":"<AD_IMAGE_HASH_3>"}]}}' \
-F 'access_token=<ACCESS_TOKEN>' \<AD_ACCOUNT_ID>/adcreatives

Create an ad with the above creative

The multi-product ad works best when paired with Custom Audiences from your website. The functionality is especially powerful when an advertiser generates audiences based on site visits on a product page and then displays the product that was viewed alongside two related products in the multi-product ad.

It is also recommended that objective for the ad set is set to WEBSITE_CONVERSIONS if there is a conversion pixel set up for website or WEBSITE_CLICKS if no conversion pixel exists to ensure that ad performance is measured accurately.

Step 1: Create an ad set with the right targeting

use FacebookAds\Object\AdSet;
use FacebookAds\Object\Fields\AdSetFields;
use FacebookAds\Object\Values\AdObjectives;
use FacebookAds\Object\Fields\AdGroupBidInfoFields;
use FacebookAds\Object\Values\BidTypes;

// Call create using an array of parameters.
$fields = array(
  AdSetFields::NAME => 'My MPA AdSet',
  AdSetFields::BID_INFO => array(
    AdGroupBidInfoFields::ACTIONS => 500,
  AdSetFields::DAILY_BUDGET => 2000,
  AdSetFields::TARGETING => array(
    'geo_locations' => array(
      'countries' => array(
    'custom_audiences' => array(
        'id'=> <CUSTOM_AUDIENCE_ID>,
        'name'=>'my custom audience',
$ad_set = new AdSet(null, $account_id);
curl \
-F 'name=My MPA Adset' \
-F 'bid_type=ABSOLUTE_OCPM' \
-F 'bid_info={"ACTIONS": 500}' \
-F 'campaign_status=ACTIVE' \
-F 'daily_budget=2000' \
-F 'campaign_group_id=<CAMPAIGN_GROUP_ID>' \
-F 'targeting={ \
"geo_locations": {"countries": ["US", "GB"]}, \
"custom_audiences": [ {"id":<CUSTOM_AUDIENCE_ID>,"name":"My custom audience"}, ], \
}' \
-F 'access_token=<ACCESS_TOKEN>' \<AD_ACCOUNT_ID>/adcampaigns

Step 2: Creating the ad using the AD_CREATIVE_ID from Step 1

use FacebookAds\Object\AdGroup;
use FacebookAds\Object\Fields\AdGroupFields;

$fields = array(
  AdGroupFields::NAME => 'My First Multi Product Ad',
  AdGroupFields::CAMPAIGN_ID => $adset_id,
  AdGroupFields::CREATIVE => array(
    'creative_id' => $creative_id,

$ad = new AdGroup();
curl \
-F 'name=My First Multi Product Ad' \
-F 'campaign_id=<AD_SET_ID>' \
-F 'creative={"creative_id": <AD_CREATIVE_ID>}' \
-F 'access_token=<ACCESS_TOKEN>' \<AD_ACCOUNT_ID>/adgroups


This image below shows an example of a rendered Multi Product Ad, showing how the fields are used and displayed.

Monitoring Ad Statistics

Apart from usual ad statistics, for Multi Product Ads you can break down actions on a Multi-Product Ad by each product, using the actions_group_by field and grouping by action_target_id in the reportstats. action_target_id will contain the object id of the product's link if the user clicked on the product link or the page id if the user clicked on the page post.

use FacebookAds\Object\AdAccount;

$fields = array();

$params = array(
  'data_columns' => array(
  'filters' => array(
      'field' => 'action_type',
      'type' => 'in',
      'value' => array(
  'date_preset' => 'last_30_days',
  'time_increment' => 'all_days',
  'actions_group_by' => array(

$adaccount = new AdAccount($account_id);
$stats = $adaccount->getStats($fields, $params);
curl \
-G \
-d 'data_columns=["adgroup_id","actions","action_target_name"]' \
-d 'date_preset=last_30_days' \
-d 'time_increment=all_days' \
-d 'actions_group_by=["action_type","action_target_id","action_destination"]' \
-d 'filters=[{field:"action_type",type:"in",value:["link_click"]}]' \
-d 'access_token=<ACCESS_TOKEN>' \<AD_ACCOUNT_ID>/reportstats

The response will look like this


For more information please check the Multi Product Ads reference document