Common questions about v2.2 migration

We recently announced that v2.2 of the Marketing API will be enforced on March 11th, 2015. Starting on that date, all unversioned API requests, and API requests with version 2.1 or earlier, will result in errors. If you are already calling Marketing API with v2.2 specified, you would experience no difference after March 11.

Here are some frequently asked questions around this migration.

Promoted Object

• What is this field useful for?

  • Before promoted_object, an adset could have ads with different goals such as each ad promoting a different page. As targeting, budget and bid are all set on the adset level, this will cause unwanted resource competition.
• What is the relationship between promoted_object and objective?

  • promoted_object is an ad set level setting, and objective is an ad campaign level setting.
  • Not all ad sets require having promoted_object. Currently ad sets of ad campaigns with the objective of Website Conversions, Page Likes, Offer Claims, and App Installs or Engagement objectives would have to have promoted_object field set.
  • There are some validations between objectives and the promoted_objects. For example, if you have an objective of Offer Claims in an ad campaign, the promoted_objects of ad sets in that ad campaign must have offer_id set, and it will be checked that the ads in this ad set are promoting the right offer. So you cannot use the wrong offer_id ad in the ad set.
• What about ad sets that do not require a promoted object?

  • Ad sets of ad campaigns with other objectives do not require promoted_object. If you try to create or update an ad set with promoted_object in this case, you would get an error reply.
• What is the relationship between promoted_object and conversion specs?

  • promoted_object is an ad set level setting, and conversion_specs is an ad level setting.
  • For those ads within ad campaigns with certain objectives of which promoted_object is required, the conversion specs of the ad are inferred from the objective of the ad campaign and the promoted_object in ad set together. You cannot update the conversion specs for ads of ad campaigns of those objectives, any attempts will be ignored.
• What is the relationship between promoted_object and tracking specs?

  • promoted_object is an ad set level setting, and tracking_specs is an ad level setting.
  • Tracking specs are defaulted by the objective of the ad campaign, and by the ad creative if the objective is NONE. The promoted_object of the ad set does not have a direct role here. However, as the whether the promoted_object is needed is decided by the objective, and the promoted_object also has some validation against the ad creative, it is fair to say that the promoted_object of an ad set has an indirect relationship with the default tracking specs of the ads.
• What will happen to ads without promoted_object after March 11?

  • Since the promoted_object of an ad set is immutable, all ads without promoted_object would still be without it. There is nothing for you to migrate, even if you want. The required promoted_object will only be checked during new ad set creation in v2.2 or later.
  • Ad sets without promoted_object will still work as before - those ads will still deliver if they are active, you can still update those ad sets, and you can still update ads in those ad sets including changing conversion_specs. You just cannot create new ad sets without promoted_object with v2.2 or later. And this is true even before March 11, as the API checks version, not date.
• Can the objective and promoted_object be updated?

  • The objective, an ad campaign level setting, can only be updated between a valid objective and NONE, either direction. It cannot be changed from a Mobile App Install to an Offer Claim, for example.
  • The promoted_object, an ad set level setting, cannot be updated currently in most cases. However, as it is a common case to switch among multiple conversion pixels in an ad with WEBSITE_CONVERSIONS objective, the promoted_object of an ad set in an ad campaign with that objective may be updated.
• How to set promoted_object if the object is created inline by using object_story_spec?

  • For an ad set of those certain objectives that require promoted_object, you must have the object to promote ready before you create an ad set. The object could a conversion pixel, a Page, an offer, or an app. Among these objects, only offer can be created 'inline', i.e. during ad creative creation, which would happen after the creation of an ad set. As the result, we are disabling the inline creation of offer, to break this mutual dependency. Thus you should not create offers inline anymore, even if you still can currently.

Ad Set Level Targeting and Bidding

• How to migrate targeting and bidding of existing ads to comply with the new model?

  • The ideal structure would be to have each targeting/bidding combination contained within one ad set. And each ad is just a container of an ad creative. So if you have ads with different targeting/bidding settings within the same ad set, you'd better split the ad set to multiple ad sets. Check out our blog post with a sample script to migrate old ad sets.
• What will happen to ads not migrated, e.g. still have ads with different bid_type or targeting within an ad set, after March 11?

  • Those ads will still deliver as before. However, when you use a Facebook interface such as Ad Manager, to edit such an ad set, you would see a message telling you to migrate. And if you use v2.2 or later API to update the bid_type or targeting of those ads, you would get an error, while you can still update other fields, including bid_info, of the ad.
• Is there a plan to move the "reachestimate" connection to ad set as well?

  • Yes. In the meantime, it is recommended for you to use the targeting specs to get the reach estimate, instead of using ad or ad set id.
• Why is bid_info still at ad level while bid_type is moved to ad set level?

  • Both bid_type and bid_info are moved to the ad set level. However, as we noticed that some partners like to have different bidding amounts for different ads, to do their own optimization or for other purposes, we allow bid_info to be overwritten at ad level. After March 11, bid_info still can be specified during the creation or update of an ad, just like before, even if it is not migrated, i.e. the bid_type or targeting is still at ad level.