Marketing API - Upgrade Guide

Changelogs and upgrade guides of Marketing API and Graph API are merged into Platform Changelog.

Upgrade your apps across versions. For a list of the changes in each Marketing API release, see our Marketing API Changelog. See Platform Changelog for any non-Marketing API (such as Pages API or general Graph API) changes that may affect you.

Upgrading from v2.x calls to v2.x

To upgrade to v2.x to a higher version of v2.x, modify your endpoint prefix to that version. For example from to You should have the API endpoint prefix set as a system constant or property, to make future version upgrades easier.

Full details of upgrading to different versions of v2.x are in the Marketing API changelog.

Upgrading from v2.2 calls to v2.3

To upgrade to v2.3, modify your endpoint prefix, from to You should have the API endpoint prefix set as a system constant or property, to make future version upgrades easier.

Deprecation of objective at ad level

Objectives are to be set only at ad campaign level in v2.3. Before v2.3, you could also set objectives at ad level, if the ad level objective is the same as it of the ad campaign, or if the objective of the ad campaign is NONE.

One special case is that, if the creative used by the ad is about an app, the ad or the ad campaign must have an *_APP_* objective. If the ad campaign has an objective of NONE, before v2.3, you could specify an *_APP_* objective at the ad level. With v2.3+, you will not have this option. For existing app ad campaigns in a NONE objective campaign, ads will continue delivering. To add additional ads in this case, you must create a new campaign.

Change of time fields

Before v2.3, you could set the ad set's start_time and end_time values without timezone, such as "2015-03-12 23:59:59", and the timezone of the ad account would be used. With v2.3+, you must specify the timezone when you create or update an ad set with those two fields. For example, you can use either "2015-03-12 23:59:59-07:00" or "2015-03-12 23:59:59 PDT".

Chunked video upload

Before v2.3, you could only upload ad videos in whole. With 2.3+, you can upload an ad video chunk by chunk. This is the preferred method for all ad video uploads. You need to write a three step script to upload ad videos in this way. You can find more details and examples in our ad videos document.

promoted_object for offer ads

Before v2.3, for OFFER_CLAIM campaigns, the promoted_object of an ad set took offer_id. With v2.3, you should specify page_id in promoted_object during ad set creation instead. You do not need to update existing ad sets to use page_id.

Pixels and Audiences

With v2.3 creating pixels using the /act_{AD_ACCOUNT_ID}/adspixels endpoint will require the name parameter.

For website custom audiences, before v2.3 pixel_id was an optional paramater when creating website custom audiences using the /act_{AD_ACCOUNT_ID}/customaudiences endpoint. With v2.3 you will need to specify the pixel_id parameter to create a website custom audience.

Upgrading from unversioned calls to v2.2

Implementing Versions in your Apps

To upgrade to v2.2, developers using a Facebook SDK should download the newest version of that SDK - our SDKs automatically use the newest API version available when that SDK version was released. If using our Ads SDKs, the latest PHP and Python SDKs are calling v2.2. Developers using other SDKs may have to manually add v2.2 to the URLs called when accessing the Graph API.

For example, here's a call to v2.2

curl -G \
-d "access_token={ACCESS_TOKEN}" \

This works for all versions, in this general form:{API_VERSION}/{request-path}

where {API_VERSION}/ is the version needed, preceded by 'v' (e.g. 'v2.2').

When a version of the Marketing API expires, all Marketing API calls made against that version will fail with an exception.

New Field Expansion format for Making Nested Requests

A new, more compact syntax has been introduced for making nested API requests. The old syntax is still available in v2.1, but apps should switch to using the new format as soon as possible.

API Response Changes

All API endpoints will now always return valid JSON. Many API calls before v2.1 returned plain text true or a raw int like 378293782 as the response. With v2.1+, those calls will now return valid JSON, such as:

  “success”: true

This will affect any API endpoints that previously returned something that was not valid JSON. Typically you receive this response only when you create or delete ad objects.

Consult the reference docs for Marketing API to see if any endpoints that you use have changed response formats.

Bid and Targeting

Begin specifying targeting and bid_type at the ad set level, Facebook will no longer accept these fields at the ad level. Also begin setting bid_info at the ad set level. This field will be required at ad set level, while optional at ad level for greater control.

Stop using Action Spec targeting, which is a beta feature. This will no longer be supported.

Addition of Promoted Object at Ad Set level

A new field promoted_object will be required while creating ad sets when the campaign's objectives is WEBSITE_CONVERSIONS, PAGE_LIKES, OFFER_CLAIMS, MOBILE_APP_INSTALLS, CANVAS_APP_INSTALLS, MOBILE_APP_ENGAGEMENT or CANVAS_APP_ENGAGEMENT. It describes the thing an ad set is promoting. See Promoted Object.

Knowing what object an ad set is meant to promote is helpful for a number of reasons:

  1. Facebook can automatically infer the conversion specs for ads
    Right now, for objectives like MOBILE_APP_INSTALLS you must specify the conversion specs explicitly. Once the application being promoted is specified explicitly within the promoted object, there is no more ambiguity and the conversion specs becomes automatic. See conversion specs documentation for more details.

  2. We can prevent the mixing of promoted objects
    The Facebook ads delivery system will try to find the best performing ad within an ad set. As such, it assumes that all of the ads within an ad set are essentially fungible. If they are promoting completely different things, this will often lead to un-desireable results. For a long time, we have encouraged Facebook advertisers NOT to promote multiple mobile applications, or use multiple, different conversion pixels among the ads in a single ad set. Now, this can be automatically checked and enforced. All ads must validate against the promoted object if it set in the ad set during creation.

  3. Simplify user interfaces
    For marketing developers who are creating self-serve interfaces, the promoted object will help pre-set information when advertisers are creating new ads. For example, if someone is making a new ad, inside of an existing ad set, if that ad set is promoting a particular page, or application, or conversion pixel, this information can be retrieved from the API and used to pre-set certain aspects of the ad, or limit the choices available. We expect this to lead to simpler, more streamlined interfaces where advertisers do not have to specify this kind of information multiple times.

More information on this change here.

Reach and Frequency

  • The target_specs endpoint will be replaced with target_spec, only allowing for one spec per prediction.
  • The new target_spec field returns an object where target_specs used to return an array.
  • A new field, story_event_type, will be added. This field will be used to specify when an ad set may or may not have video ads and is required when targeting all mobile devices.

More information on this change here.

Custom Audience Targeting

Advertisers will need to specify one or many App IDs when adding, removing, or opt-ing out users from Custom Audiences based only on the Facebook user ID or app-scoped user ID. Specifically, a new field, app_ids, is required when "schema"="UID" and takes an array of app IDs.

use FacebookAds\Object\CustomAudience;
use FacebookAds\Object\Fields\CustomAudienceFields;
use FacebookAds\Object\Values\CustomAudienceTypes;

// Add Facebook IDs of users of certain applications
$audience = new CustomAudience('<AUDIENCE_ID>');
  array(1234, 5678, 9012), // User ids
  array(1111,2222)  // App ids
// Add Facebook IDs of users of certain applications
curl \
-F 'payload = { \ 
"schema":"UID", \
"data":[1234, 5678, 9012], \
"app_ids":[1111,2222]}' \
-F "access_token=<ACCESS_TOKEN>" \

More information on this change here.

New Graph API framework conversion

Starting with 2.2 update the endpoints listed in the changelog to respect OAuthInsufficientScopeException instead of GraphMethodException and to begin using a cursor-based approach to paging. You may also now specify a flag summary=true to fetch back the total_count.

Also pay special attention to the /{USER_ID}/adaccounts edge which has additional changes.

Make sure to check out the changelog for a comprehensive list of breaking changes specific to Marketing API v2.2.

Upgrading to Facebook AdsAPI PHP SDK v2.2.*

This section is meant only for developers transitioning between the SDK v0.9.* to v2.2.*, if you want to get started using the sdk visit our Github page

Get the latest verson

If you included the SDK into your application through composer:

composer update --no-dev

Otherwise check our Github releasese page to download the latest version.

facebook/php-sdk-v4 and psr/log are not required anymore.

The new init method

Previous versions of the SDK used to rely on \Facebook\FacebookSession to initialize:

// THIS IS LEGACY CODE: won't work with v2.2.0+

use FacebookAds\Api;
use Facebook\FacebookSession;

// Set the default application information to be used with this session
FacebookSession::setDefaultApplication('{APP_ID}', '{APP_SECRET}');
$session = new FacebookSession('{ACCESS_TOKEN}');
$api = new Api($session);

In v2.2.* the Api object can initiate itself. Be sure to replace the previous code with:

use FacebookAds\Api;

// Initialize a new Session and instantiate an Api object
Api::init('{APP_ID}', '{APP_SECRET}', '{ACCESS_TOKEN}');

// The Api object is now available trough singleton
$api = Api::instance();