Breaking Changes

Breaking changes are any changes to existing functionality that will take effect immediately and impact all API versions. These changes can be introduced at any time and will not be tied to a specific release.

We avoid releasing Breaking Changes whenever possible and will make every effort to bundle changes into Platform Version releases so you have ample time to adjust your code.


Restrictions for 2-tier Business Manager

We removed the ability to add Admins to child Business Managers in the 2-tier Business Manager. Admins of a parent Business Manager can still add people as Employees to child Business Managers in order to have insight into those accounts.

To create other Business Managers, your business needs to obtain BUSINESS_MANAGEMENT permission during the app review process. If your app is in development mode, you can surpass this requirement, but only to create two child businesses.

Please refer to the 2-tier Business Manager documentation for details.


Permissions Change for agency_client_declaration

You now need to be an admin in order to read agency_client_declaration. For details, see Reference, Ad Account.


New requirements for Housing, Credit and Employment Ads

Starting December 4, 2019, all advertisers must specify a special_ad_category for advertising campaigns that offer housing, employment, and credit opportunities. Advertisers delivering ads in these areas have limited targeting and audience selections. The special_ad_category should be one of the following: HOUSING, CREDIT, EMPLOYMENT, and NONE.

If you create your campaign before December 4, and don't assign it a special_ad_category, that campaign will have special_ad_category automatically set to NONE on December 4. After that date, you are required to set a special_ad_category if you create a new ad campaign.

Ads Manager

If you use Ads Manager to modify your ads before December 4, you must immediately start following Special Ad Category rules and limitations. In that case, the requirements are effective immediately.

Learn more about Special Ad Category.


Deprecating project for Businesses Manager API

On October 14, 2019, we deprecate Business Manager, Projects API, which is 60 days after the launch of Business asset groups. You should migrate all apps on Projects API to Business asset groups groups. This impacts:

  • POST /{BUSINESS_ID>}businessprojects
  • GET /{BUSINESS_ID}/businessprojects
  • POST /{PROJECT_ID}/pages
  • GET /{PROJECT_ID}/pages


Deprecate /users on Ad Accounts

Deprecated POST or DELETE of /users on ad accounts. This impacts these endpoints:

  • POST /{ad_account_ID}/users
  • DELETE /{ad_account_ID}/users


Deprecating subtype for Audiences

We will not support subtype after v3.0 of Marketing API for custom audiences for websites, apps, engagement custom audiences, and audiences from offline conversion data. The one exception is that subtype will still be supported for engagement custom audiences for video.


Live Video Ads Options

We are updating our support of live video ads used with different optimization_goals, placements and bid types. Note that this API is under limited availability for advertisers with verified Pages. Contact your Facebook Representative to access it. You can use live video ads in the following scenarios:

Optimization goals supported:


Billing events supported:


Placements supported:

  • facebook_positions: feed


Introducing a new recommendation_type field, with a positive or negative value, for Pages. This new field will replace the rating field, with its scale of 1 to 5. Please see the Managing Pages API documentation for more details.


In addition to the upcoming July 2018 deprecations we announced in February 2018, we will also deprecate action_link_click_destination in July of 2018.

We will no longer support action_carousel_card_id and action_carousel_card_name breakdowns for conversion metrics and for any calculated metrics in July of 2018. You can still get actions:link_click and unique_actions:link_click metrics grouped by these carousel card breakdowns and can still get conversion metrics without these carousel card breakdowns.

These are breaking changes which will impact all available versions of the API.


Access Token Expiration: An access tokens is invalid if the user hasn't engaged the app within the last 90 days. Learn more in the Developer News Blog.


Accompanying blog post: New Facebook Platform Product Changes and Policy Updates

Events API

  • /event node — You can no longer perform POST operations on the attending, maybe, interested, and declined edges.

Facebook Analytics

  • 90 Day Breaking Change — On August 1, 2018, we will be removing the app_event metric from the app-id/app_insights edge.

  • 90 Day Breaking Change — On August 1, 2018, we will be removing the Application Analytics App Events Export API. Aggregated data will still be available in the Facebook Analytics interface.

Facebook Login

  • The publish_actions permission has been removed. Apps that have already been approved for publish_actions can continue using the permission until August 1st, 2018. If you want to provide a way for your app users to share content to Facebook and Instagram beyond this date, we encourage you to use our Sharing products instead.

Instagram Graph API

  • /comment node:
    • Added a new username field.
    • For GET requests, the user and biography fields will not be included in responses unless the User making the request owns the Comment; instead, we will return username for all commenters. This also applies to queries on Comments made through other APIs, such as the Mentions API.
  • /media node:
    • Added a new username field.
    • For GET requests, the owner field will not be included in responses unless the User making the request owns the media object; instead, we will return username for all commenters. This also applies to queries on media objects made through other APIs, such as the Mentions API.

Instant Articles

  • Article Insights API — The Video Insights endpoint has been deprecated.

Live API

  • App Review — All apps that use the Pages API to publish Videos to Pages must go through App Review. Apps previously reviewed before April 24th, 2018, have until August 1, 2018 to be reviewed again or lose access to the Pages API.
  • 90-Day Breaking Change — On August 1st, 2018, the Live API publish_actions permission, which allows an app to publish on behalf of its Users, will be reserved for approved partners. In the coming weeks, a new permission model that allows apps to publish Videos to their User's Groups and Timelines will be announced.
  • RTMP — On May 1st, 2019, the Real-time Messaging Protocol (RTMP) will be deprecated from the Live API, GoLive Dialog, and Publisher Pages. RTMPS (RTMP over a TLS/SSL connection) will continue to be supported.

Messenger Platform

Pages API

  • Page-scoped User IDs — New apps that pass App Review will receive Page-scoped User IDs (PSIDs) instead of App-scoped User IDs (ASIDs). Existing apps that pass App Review will continue receiving ASIDs for 180 days from approval, and will be given access to an API that can map ASIDs to their PSID equivalents.
  • Devmode Apps — Apps in Devmode are now rate-limited to 200 calls per hour, per page-app pair, and can only access Users who have a role on the app (admin, developer, or tester).
  • /page/feed edge — 90-Day Breaking Change — For POST requests on the /page/feed edge, the targeting parameter no longer allows specifying genders, locales, or age_max. In addition, age_min can only be set to 13, 17, 18, 19 or 21.
  • /page/photos?type=tagged edge — For GET requests, this edge no longer returns Photos in which a Page has been tagged.
  • /page/tagged — For GET requests, this edge now requires the manage_pages permission. For user posts, the from field will only be returned if the user making the GET request created the post.

Places Graph

  • The /photos?type=tagged edge, which returned photos a Place was tagged in, no longer supports GET operations.


Marketing API, Ads with Political Content

To increase transparency of ads on Facebook, we require advertisers running ads with political content to complete authorization. We will begin enforcing this in the next few weeks. You must also indicate that your ad has political content and provide the name of the funding source for the ad:

  • Your ad account must be authorized by a Page admin to run political ads for this Page. This is done by a Page admin on the Authorizations tab under Page Settings.

  • Ad account users must go through a verification process.


Accompanying blog post: API and Other Platform Product Changes

App Insights API

The following breakdowns have been removed from the app_event metric:

  • age
  • country
  • gender

Events API

  • All apps, including formerly approved apps, must undergo App Review in order to gain access to the API.

  • GET /events — You can no longer get the following edges:

    • attending
    • comments
    • declined
    • feed
    • interested
    • live_videos
    • maybe
    • noreply
    • photos
    • pictures
    • posts
    • videos

Facebook Login


  • Instant Games context.getPlayersAsync() will only return players who have actively played the game in the current context within the last 90 days.
  • Returns Empty Set — The following nodes and edges will now only return empty data sets:

    • /achievement_id
    • /app/achievements
    • /app/scores
    • /user/achievements
    • /user/invitable_friends
    • /user/scores
    • /user/taggable_friends
  • Deprecated Edges — The following edges have been removed:

    • /app/staticresources

Groups API

  • App Review — All apps, including formerly approved apps, must undergo App Review in order to gain access to the API.

  • Deprecated Edges and Fields — The following Group node fields and edges have been removed:

    • /group/admins
    • /group/members
    • /group?fields=owner
  • GET /group/albums — You can no longer get the following fields and edges on Albums returned by this edge:

    • from
    • likes
    • reactions
  • GET /group/albums?fields=photos — You can no longer get the following fields on Photos in Albums returned by this edge:

    • from
    • likes
    • name_tags
    • reactions
    • tags
  • GET /group/docs — You can no longer get the from field on Docs returned by this edge.

  • GET /group/files — You can no longer get the from field on Files returned by this edge.

  • GET /group/feed — You can no longer get the following fields and edges on Posts returned by this edge:

    • admin_creator
    • from
    • likes
    • message_tags
    • reactions
    • to
    • with_tags
  • GET /group/feed?fields=comments — You can no longer get the following fields and edges on Comments on Videos returned by this edge:

    • admin_creator
    • from
    • likes
    • message_tags
    • reactions
  • GET /group/events — You can no longer get the following fields and edges on Events returned by this edge:

    • admins
    • attending
    • declined
    • interested
    • live_videos
    • maybe
    • noreply
    • owner
    • pictures
    • posts
    • roles
    • videos
  • GET /group/videos — You can no longer get the following fields and edges on Videos returned by this edge:

    • from
    • tags
    • likes
    • reactions

Invitable Friends API

GET operations on the /user/invitable_friends edge will now return an empty data set. The edge will be removed entirely in the near future.

Messenger Platform

Customer Matching via the Send API is now in closed beta, and is no longer accepting applications for new Pages. Pages that have previously been approved to use customer matching via the Send API and the Customer Matching API may continue to use the feature.

Mutual Friends

The Mutual Friends API is no longer available.

Open Graph

The following Open Graph Action types will no longer return information:

  • books.rates
  • books.reads
  • books.quotes
  • books.wants_to_read
  • fitness.bikes
  • fitness.runs
  • fitness.walks
  • music.listens
  • music.playlists
  • news.reads
  • videos.rates
  • videos.wants_to_watch

Pages API

App Review — All new apps must undergo App Review in order to gain access to the API. App Review will resume in the coming weeks. Once App Review resumes, formerly approved apps or apps that have not been reviewed must undergo App Review or lose access until they are approved.

The /page/checkin-post endpoint and checkins Webhooks has been deprecated.

New scoped_thread_key as the thread identifier for the /page/conversations endpoint and conversation Webhooks payloads. Both scoped_thread_key and thread_id values will work for all related endpoints. After 90 days, the scoped_thread_key and thread_id values will be the same.

The following Social Context Elements have been removed:

  • /open-graph-context-id/friends_who_like
  • /open-graph-context-id/friends_tagged_at
  • /open-graph-context-id/video_watch_friends
  • /open-graph-context-id/music_listen_friends

GET /pageGET operations on the following fields and edges now require a Page Access Token of the page:

  • /page/agencies
  • /page/canvases
  • /page/instagram_accounts
  • /page/leadgen_forms
  • /page/page_backed_instagram_accounts
  • /page/promotable_posts
  • /page/userpermissions

POST /pagePOST operations on the following fields and edges now require a Page Access Token of the page:

  • /page/agencies
  • /page/page_backed_instagram_accounts
  • /page/userpermissions

Search API

You can no longer use the /search endpoint with the following object types:

  • event
  • group
  • page
  • user

Taggable Friends API

All endpoints for the Taggable Friends API will now return an empty data set:

  • /user/taggable_friends edge
  • /user-taggable-friend node

These endpoints will be deprecated in the near future.

Tagged Users

Apps can no longer get photo, video, or post objects for non-app Users who have been tagged by an app User, even if the non-app Users have previously enabled the Posts on my timeline sharing setting in the Apps others use section of their Facebook profile's App Settings. This affects GET operations on these objects, as well as any edges that may return these objects.

User Node

  • The following User node fields will no longer return information:

    • about
    • education
    • friendlists
    • interested_in
    • political
    • relationship_status
    • religion
    • website
    • work
  • GET /user/groups and GET /me/groups — This edge no longer returns any fields that contain User identifying information. This applies to all app Users, even app Admins querying their own User ID. For a list of these fields, please refer to the Groups API section of the changelog.


Facebook Login

The user_friends permission is now a reviewable permission and must go through the Login Review process.

Event Ads, Link Ads not Associated with Valid Page

We recently announced an initiative to make the Facebook Advertising platform more transparent to Facebook users. Read more about this in the Facebook press release

To support this initiative, we are deprecating deprecating Event Ads and Link Ads that are not connected to a valid page from Marketing API.

This breaking change impacts all supported API versions, including the upcoming Marketing API version v2.11, and v2.10 and v2.9 which are available but will be deprecated. This breaking change will take effect the second week of November 2017.

You will no longer be able to create or edit Event Ads and Link Ads that are not connected to a valid page. Requests will do so return the error: ErrorCode::ADPRO2__AD_MUST_HAVE_PAGE (1885833)

The following ad options used together will fail:

  • Event Ads
  • Objective: EVENT_RESPONSES
  • Creative fields: body, object_id
  • Link Ads
  • Objective: LINK_CLICKS
  • Creative fields: title, body, object_url containing image_file or image_hash

You can still create Event Ads and Link Ads if you provide a valid actor_id in the ad creative's object_story_id or object_story_spec fields

These options used together are valid:

  • Event Ads
  • Objective: EVENT_RESPONSES
  • Creative fields: object_story_id or object_story_spec
  • Link Ads
  • Objective: LINK_CLICKS
  • Creative fields: object_story_id or object_story_spec

The nodes, edges and requests impacted are:

Any pre-existing Event or Link Ads continue to run but you cannnot modify these ad's creatives or create new ads with the invalid options once the change goes in effect.


Marketing API, Insights

We will deprecate these metrics in July of 2018.

  • actions:mention
  • action_values:app_custom_event
  • cost_per_action_type:mention
  • actions:tab_view
  • cost_per_action_type:tab_view
  • canvas_avg_view_percentage_per_component:canvas_view
  • call_to_action_clicks
  • cost_per_total_action
  • relevance_score:negative_feedback
  • relevance_score:positive_feedback
  • social_reach
  • social_impressions
  • social_clicks
  • unique_social_clicks
  • today_spend
  • total_actions
  • total_unique_actions


Removed Targeting Availability for 'Interested In' in Ads

As of February 7, 2018, we've removed “Interested in” targeting, which applies to all advertisers who use or have used 'Interested in Men', 'Interested in Women', 'Interested in Men and Women', or 'Interested in Unspecified' for targeting options. Learn more


Marketing API, Product Catalog Permissions

The release of Facebook Graph API, v2.12 is scheduled for January 30, 2018 and does not contain any versioned breaking changes for Facebook Marketing APIs, except for the following scenario:

If you're using Product Catalog as part of your application, you may be affected by a couple of security-related breaking changes. Technically, these are not Marketing API endpoints. However, these are used by some marketing applications, and hence can be considered breaking changes for such applications. Read further below for details.

  • Marketing API, v2.11 will continue to be the latest version and it will not enter deprecation mode on January 30, 2018.
  • Marketing API, v2.10 will continue to be in deprecated state, as it is currently, and will end of life on May 8, 2018.
  • After Graph API v2.12 is released, any calls made to Marketing APIs with the version set as 2.12, will be treated as v2.11 calls.
  • Marketing API, v2.11 and v2.12 will be deprecated and end of life at the same time, at a later date.

As of May 8, 2018, we'll limit permissions to catalogs managed under the same Business Manager account to only users who have explicitly been assigned the ADMIN or ADVERTISER role on that catalog owned by a business, as follows:

  • Only users with the catalog ADMIN role can create and edit the catalog. Business Admins only have read access. This change applies to calling POST {product-catalog-id}.
  • Only users with the catalog ADVERTISER role can't edit the catalog, but have read and write access to catalogs managed under the same Business Manager account.
  • Only users with catalog ADMIN or ADVERTISER role can read the catalog.

For more details, see Implications of Graph API 2.12 Release and Facebook Graph API, v2.12.


Removed Exclusion Targeting of Multicultural Affinity Segments for Ads

We're actively working to strengthen our review process and continue to enforce our ad policies against discriminatory behavior on Facebook. On December 1, 2017, we removed the ability to exclude multicultural affinity segments during ads creation. We've since expanded this to no longer allow advertisers to exclude segments related to other potentially sensitive areas.

In parallel, we're working to help advertisers understand why we're making these changes, and how they can be better informed about their responsibility as an advertiser. These updates are in the process of being built and are slated to launch this year.

We understand that marketers often use exclusion targeting to create refined audiences within a larger targeting audience, and that exclusion targeting can help businesses reach just the right audience; for example, not showing ads to an audience that has already purchased a product or removing specific locations where a business does not operate. Those types of exclusion targeting will still be available for ad creation.


Removal of Self-Reported Terms for Ads Targeting

The week of September 10, 2017, we removed more than 3 million self-reported terms related to education and employment as targeting options in our ads interfaces. We did this after discovering a small percentage of people had entered offensive responses, in violation of our policies. After a thorough review, we are making additional changes to improve our policies, enforcement practices, and also adding back ~5,000 commonly used targeting terms that meet our Community Standards. For more information see Ads Developer Blog, Update to Self-Reported Profile Targeting Options.


Conversation ID

The user/conversations and page/conversations edges along with their associated Webhoooks will change the identifiers they use on July 4th. The IDs will still be prefixed with 't_' but what follows the prefix will change.

Graph API Conversation

The 'id' for the GraphAPI Conversation type will change. Messenger is migrating to a new database with enormous benefits to the Messenger product. The current GraphAPI 'id' is an identifier that won't be migrated to the new database. This will apply to all APIs that expose conversations, including Webhooks. Both old and new 'id' are currently accepted as valid IDs on all our GraphAPIs for Conversations.

To ease the transition, we're adding a new field to all the Webhooks that exposes the new identifier alongside the current identifier. This allows developers to map the current identifier to the new identifier and vice versa. We're also adding two new fields to the Conversation GraphAPI object to allow developers to map the current identifier to the new identifier. Lastly, the boolean parameter 'use_thread_key' on /page/conversations and /conversation allows developers to see the effect of this migration before it takes place.

Thread IDs are not globally unique. Just like thread_id, thread_key is unique per page, not across multiple pages.


The Webhooks expose the current identifier in the thread_id field. There will be a new thread_key field that will contain the new Conversation identifier, allowing developers to map the new identifier to the current identifier in updates from Webhooks. For the {page_id}/conversations Webhook, developers will now get updates in the following payload:

  field: 'conversations',
  values: {
    thread_id: 't_id.290234844429376',
    thread_key: 't_554591851336367',
    page_id: '554591851336367'

thread_key field contains the value that will populate the thread_id after the change has happened. To be clear, developers can expect the following Webhook payload after the change:

  "field": "conversations",
  "values": {
    "thread_id": "t_554591851336367",
    "thread_key": "t_554591851336367",
    "page_id": "6367185133"

There will be a new thread_key field on all Webhooks that currently expose the Conversation identifier as thread_id.

Graph API

On the Conversation GraphAPI type, there will be two new fields. The thread_key field will contain the new identifier. The new field thread_id field will contain the current identifier. Before this change the id for Conversation will be the same as the thread_id field, but after the change the id will be the same as the thread_key field. Developers can see the new response by setting the use_thread_key parameter to true.

Before Change:{page_id}/conversations?limit=10&fields=thread_id,thread_key&access_token={access_token}
  "data": [
      "thread_id": "t_id.450736921798255",
      "thread_key": "t_450736921798255",
      "id": "t_id.450736921798255"
  "paging": {
  "data": [
      "thread_id": "t_id.450736921798255",
      "thread_key": "t_450736921798255",
      "id": "t_450736921798255"
  "paging": {
After Change:{page_id}/conversations?limit=10&fields=thread_id,thread_key&access_token={access_token}
  "data": [
    "thread_id": "t_450736921798255",
    "thread_key": "t_450736921798255",
    "id": "t_450736921798255"
  "paging": {


Marketing API, Budget Limits Enforcement

Starting from Wednesday, March 8th, 2017, we start enforcing a budget validation to prevent creation and editing of ads with lifetime budgets exceeding 1 million USD. Reach-Frequency assets are exempt from this limit and validation. There is no change to the daily budget limit, and it was already enforced at 1 million USD.

When a life budget for an Ad exceeds this cap, you see an error: ErrorCode::ADPRO2__CAMPAIGN_BUDGET_TOO_HIGH (1885261).