Marketing API Version

buying_type and billing_event

buying_type is the way in which the advertiser pays for their delivery, defined on the campaign level. Most of the time we just use AUCTION, but there are a few special cases where we either bill based off of prediction (RESERVED), or use a fixed price means of negotiating the price an advertiser will pay (FIXED_CPM). Campaigns with buying_type require ad sets with a billing_event defined.

Valid billing_events for each buying_type:

AUCTIONRESERVEDFIXED_CPM

IMPRESSIONS

LINK_CLICKS

APP_INSTALLS

PAGE_LIKES

OFFER_CLAIMS

POST_ENGAGEMENT

VIDEO_VIEWS

Objectives and optimization_goal

optimization_goal defines what the advertiser is optimizing for. Certain campaign objectives support only certain ad set optimization_goals.

Campaign ObjectiveDefault optimization_goalOther valid optimization_goal

BRAND_AWARENESS

BRAND_AWARENESS

REACH

APP_INSTALLS (promoting Canvas app)

APP_INSTALLS

IMPRESSIONS, POST_ENGAGEMENT

APP_INSTALLS (promoting mobile app)

APP_INSTALLS

OFFSITE_CONVERSIONS, LINK_CLICKS, REACH, VIDEO_VIEWS

CONVERSIONS

OFFSITE_CONVERSIONS

IMPRESSIONS, POST_ENGAGEMENT, REACH, SOCIAL_IMPRESSIONS

EVENT_RESPONSES (promoting event)

EVENT_RESPONSES

IMPRESSIONS, REACH

EVENT_RESPONSES (promoting page post)

EVENT_RESPONSES

IMPRESSIONS, POST_ENGAGEMENT, REACH

LEAD_GENERATION

LEAD_GENERATION

LINK_CLICKS

LINK_CLICKS

LINK_CLICKS

IMPRESSIONS, PAGE_ENGAGEMENT, POST_ENGAGEMENT, REACH

LINK_CLICKS (promoting Canvas app)

ENGAGED_USERS

APP_INSTALLS, IMPRESSIONS, POST_ENGAGEMENT, REACH

LINK_CLICKS (promoting mobile app)

LINK_CLICKS

IMPRESSIONS, REACH, OFFSITE_CONVERSIONS

OFFER_CLAIMS

OFFER_CLAIMS

IMPRESSIONS, POST_ENGAGEMENT, OFFSITE_CONVERSIONS

PAGE_LIKES

PAGE_LIKES

IMPRESSIONS, PAGE_ENGAGEMENT, POST_ENGAGEMENT, REACH

POST_ENGAGEMENT

POST_ENGAGEMENT

IMPRESSIONS, PAGE_ENGAGEMENT, REACH, VIDEO_VIEWS, LINK_CLICKS

PRODUCT_CATALOG_SALES

LINK_CLICKS

IMPRESSIONS, POST_ENGAGEMENT, OFFSITE_CONVERSIONS, REACH

REACH

REACH

IMPRESSIONS

VIDEO_VIEWS

VIDEO_VIEWS

PAGE_ENGAGEMENT, POST_ENGAGEMENT, REACH

Optimization Goal and Billing events

For buying_type=AUCTION campaigns, with an optimization_goal set, we have restrictions on what billing_event you can choose for your ad set.

In the restrictions below, we assume you have an objective specified on the campaign level.

optimization_goalValid ad set billing_event

APP_INSTALLS

IMPRESSIONS, APP_INSTALLS

BRAND_AWARENESS

IMPRESSIONS

ENGAGED_USERS

IMPRESSIONS

EVENT_RESPONSES

IMPRESSIONS

IMPRESSIONS

IMPRESSIONS

LEAD_GENERATION

IMPRESSIONS

LINK_CLICKS

LINK_CLICKS, IMPRESSIONS

OFFER_CLAIMS

IMPRESSIONS, OFFER_CLAIMS

OFFSITE_CONVERSIONS

IMPRESSIONS

PAGE_ENGAGEMENT

IMPRESSIONS

PAGE_LIKES

IMPRESSIONS, PAGE_LIKES

POST_ENGAGEMENT

IMPRESSIONS, POST_ENGAGEMENT

REACH

IMPRESSIONS

SOCIAL_IMPRESSIONS

IMPRESSIONS

VIDEO_VIEWS

IMPRESSIONS

Objectives and Creatives

If an ad's objective is specified, the ad is validated against the creative. Please refer to the ads guide for a list of creatives supported per objective.

In the API, the objective determines which creatives are valid.

ObjectiveCreative ValidationCreative fields

NONE

No restrictions

BRAND_AWARENESS

Cannot use mobile app ads

APP_INSTALLS (promoting Canvas app)

Canvas app install ad

object_story_id or object_story_spec

APP_INSTALLS (promoting mobile app)

Mobile app install ads

object_story_id or object_story_spec

CONVERSIONS (conversions promoting mobile app)

Mobile app engagement ads

object_story_id or object_story_spec

LINK_CLICKS (promoting Canvas app)

Canvas app engagement ad

object_story_id or object_story_spec

LINK_CLICKS (promoting mobile app)

Mobile app engagement ads

object_story_id or object_story_spec

EVENT_RESPONSES

Event ads

object_id
body

EVENT_RESPONSES

Page post ads

object_story_id or object_story_spec

LEAD_GENERATION

Page post ads

object_story_id or object_story_spec

OFFER_CLAIMS

Offer ads

object_story_id or object_story_spec

PAGE_LIKES

Page like ads

object_id
body

PAGE_LIKES

Page post ads

object_story_id or object_story_spec

POST_ENGAGEMENT

Page post ads
Cannot include link ads pointing to an app store

object_story_id or object_story_spec

LINK_CLICKS

Link ads not connected to a page

title
body
object_url
(image_file or image_hash)

LINK_CLICKS

Link ads
Photo ads with a link in the message
Cannot include link ads pointing to an app store

object_story_id or object_story_spec

LINK_CLICKS

If you select this as both optimization goal and billing event, you must include call_to_action

call_to_action

CONVERSIONS

Link ads not connected to a page

title
body
object_url
(image_file or image_hash)

CONVERSIONS

Link ads
Photo ads with a link in the message
Cannot include link ads pointing to an app store

object_story_id or object_story_spec

VIDEO_VIEWS

Video ads

object_story_id or object_story_spec

Ad Creative Validation

Within the ad creative object, validation occurs on the grouping of fields specified. For instance, the below call will create a valid ad:

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Fields\AdCreativeFields;

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');

$creative->setData(array(
  AdCreativeFields::NAME => 'Sample Creative',
  AdCreativeFields::TITLE => 'my title',
  AdCreativeFields::BODY => 'my body',
  AdCreativeFields::OBJECT_URL => 'https://www.link.com',
  AdCreativeFields::LINK_URL => 'https://www.link.com',
  AdCreativeFields::IMAGE_HASH => '<IMAGE_HASH>',
));

$creative->create();
from facebookads.adobjects.adcreative import AdCreative

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.title] = 'my title'
creative[AdCreative.Field.body] = 'my body'
creative[AdCreative.Field.object_url] = 'https://www.link.com'
creative[AdCreative.Field.link_url] = 'https://www.link.com'
creative[AdCreative.Field.image_hash] = '<IMAGE_HASH>'

creative.remote_create()
AdCreative adCreative = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdCreative()
  .setName("Sample Creative")
  .setTitle("my title")
  .setBody("my body")
  .setObjectUrl("https://www.link.com")
  .setLinkUrl("https://www.link.com")
  .setImageHash(<IMAGE_HASH>)
  .execute();
String ad_creative_id = adCreative.getId();
curl \
  -F 'name=Sample Creative' \
  -F 'title=my title' \
  -F 'body=my body' \
  -F 'object_url=https://www.link.com' \
  -F 'link_url=https://www.link.com' \
  -F 'image_hash=<IMAGE_HASH>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/act_<AD_ACCOUNT_ID>/adcreatives

However, if the object_url is left out, the creative is now invalid:

curl \
  -F 'name=Sample Creative' \
  -F 'title=my title' \
  -F 'body=my body' \
  -F 'link_url=https://www.link.com' \
  -F 'image_hash=<IMAGE_HASH>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.5/act_<AD_ACCOUNT_ID>/adcreatives

It is advised to validate on the grouping of fields, not on any one field against another.

Objectives and Tracking Specs

Tracking specs are applied by default based on the objective specified, please see the full list of defaults by objective here.

There are two important scenarios to take into account:

  • Tracking pixels will not be applied by default, and you must specify it explicitly when your objective is CONVERSIONS
  • Mobile app ads will no longer track installs or app events by default. You must explicitly specify to track installs or app events for mobile app ads otherwise your ad will not track.

To specify to track an install or app event, set the following in your ad:

tracking_specs=[{'action.type':['mobile_app_install'],'application':[{your_app_id}]},{'action.type':['app_custom_event'],'application':[{your_app_id}]}]

Certain objectives of ad campaigns requires the promoted_object to be set in ad sets. The validation around this field is documented here.

Objective & Placement Validation

Certain types ad placement are valid only for specific objectives or creatives. The table below illustrates which placements are compatible with which objectives or creatives. You can pick a combination of those compatible placements. Note that audience_network cannot be selected by itself only.

ObjectiveCreativePlacement

BRAND_AWARENESS

all

publisher_platforms: facebook, instagram, facebook_positions: feed

APP_INSTALLS (promoting Canvas app)

Desktop app ads

device_platforms: desktop

APP_INSTALLS (promoting mobile app)

Photo or video mobile app ads

device_platforms: mobile

CONVERSIONS

Photo or video link ads from a page

all

CONVERSIONS

Link ads not connected to a page

facebook_positions: rightcolumn

CONVERSIONS (promoting mobile app)

Photo or video mobile app ads

device_platforms: mobile

EVENT_RESPONSES

Event ads

facebook_positions: rightcolumn

EVENT_RESPONSES

Page post ads

publisher_platforms: facebook

LEAD_GENERATION

Page post ads

facebook_positions: feed

LINK_CLICKS

Photo or video link ads from a page

all

LINK_CLICKS

Link ads not connected to a page

facebook_positions: rightcolumn

LINK_CLICKS (promoting Canvas app)

Desktop app ads

device_platforms: desktop

LINK_CLICKS (promoting mobile app)

Photo or video mobile app ads

device_platforms: mobile

OFFER_CLAIMS

Offer ads

publisher_platforms: facebook, audience_network

PAGE_LIKES

Video creatives

publisher_platforms: facebook

POST_ENGAGEMENT

Page post ads (video or photo)

publisher_platforms: facebook, instagram

POST_ENGAGEMENT

Page post ads (text)

publisher_platforms: facebook

VIDEO_VIEWS

Video ads

publisher_platforms: facebook, instagram, audience_network

Objective, Optimization Goal and attribution_spec

Use click-through and view-through attribution windows for ad set to track conversions then use for ads delivery optimization. This is different from the attribution window you use for ads reporting. With attribution_spec, select a combination of click-through or view-through windows of 1 day or 7 days. The combinations you can use depend on your ad set's optimization_goal and campaign's objective.

Optimization GoalObjectiveAllowed Combination

OFFSITE_CONVERSION

OFFER_CLAIMS, CONVERSIONS

1-day click
7-day click
1-day click and 1-day view
7-day click and 1-day view

APP_INSTALLS, LINK_CLICKS, PRODUCT_CATALOG_SALES

1-day click
7-day click

APP_INSTALLS

APP_INSTALLS

1-day click
1-day click and 1-day view

For all other optimization_goal and objective combinations you can only use 1-day click for attribution_spec.