Released October 29, 2019 | Available until February 3, 2022

This change applies to v5.0+.
The following endpoints are deprecated:

• GET /{application-id}/objects
• POST /{application-id}/objects

Marketing API

Released October 29, 2019 | Available until September 28, 2020

Messenger

New Features

These changes apply to all versions.

• Click to Messenger Ads support for Handover protocol. Ads can now indicate the app id that will have control over the thread once a user clicks on the ad.
• Replies and Reactions Webhooks. It is now possible to receive webhook events when users react or reply to messages from businesses.
• POST / GET / DELETE /{page-id}/messenger_profile — Ice Breakers. Apps can now set icebreakers on the Messenger profile via the API to provide a set of common questions that users can use to start a conversation.
• GET /{thread-id} — Admin Messages Filter. Apps can now filter out admin messages to just get messages between the Page and the user.

Deprecations

These changes apply to various versions.
The following endpoints are deprecated for versions v5.0+. They supported plain text only private replies. Use the New Private Replies instead.

• POST /{comment-id}/private_replies
• POST /{post-id}/private_replies

The following endpoints wil be deprecated for all versions on March 4, 2020.

• POST /{ad-account-id}/sponsored_message_ads
• POST /{broadcast-id}
• POST /{page-id}/broadcast_messages
• POST /{page-id}/broadcast_reach_estimations
• POST /{page-id}/message_creatives

Pages

Error Messages

This change applies to all versions.
Endpoints that require manage_pages or Page Public Content Access and return an error code 10 when both permissions are missing will now return a new error message:
This endpoint requires the 'manage_pages' permission or the 'Page Public Content Access' feature. Refer to https://developers.facebook.com/docs/facebook-login/permissions#reference-manage_pages and https://developers.facebook.com/docs/apps/review/feature#reference-PAGES_ACCESS for details.

Page Public Content Access

This change applies to v5.0+
Requests made to endpoints that require the Page Public Content Access feature must be made with either an App Access Token or include the app's App Secret. If the calling app has been granted the manage_pages permission however, an app access token or app secret is not required.

Original source

Released February 3, 2020 | Available until May 5, 2022

In addition to the changes described below, we are deprecating a number of endpoints as part of our ongoing commitments to privacy and security. These deprecations apply to version 6.0+ immediately and will apply to all versions on May 5, 2020.

Messenger

This change applies to v6.0+
Webhook Event: messages - Adjusted the way attachments type fallback and image with a sticker are sent.

Breaking Change

This change applies to v6.0+ and will apply to all versions on June 30, 2020.
/{conversation-id}/messages - This endpoint is being deprecated. For sending messages use the Send API.

Page Public Metadata Access

This change applies to all versions.
We have introduced a new reviewable feature named Page Public Metadata Access. Page Public Metadata Access allows read-only access to the Pages Search API as well as a set of Page fields and edges that would normally require the Page Public Content Access feature. Apps that have requested only these fields and edges on Pages in the past have been automatically approved for Page Public Metadata Access and will lose approval for Page Public Content Access on May 3, 2020.
Apps affected by this change will not lose any functionality and will not require any code changes.

Pages

This change applies to all versions.
The GET /{page-id}/upcoming_changes endppoint has been deprecated.

SDKs

Facebook SDK for Android v6.0 and Facebook SDK for iOS v6.0 call version 6.0 of the Graph and Marketing APIs by default.

User Node

This change applies to v6.0+.
The GET /{user-id}/promotable_domains edge has been deprecated.

Marketing API

Released February 3, 2020 | Extended to February 8, 2021
For Marketing API, v6.0, there are no new features or deprecations. We continue to encourage ads developers to migrate calls to version 6.0 in advance of the version 5.0 deprecation on September 28, 2020.

Original source

Graph API

Released May 5, 2020 | Available until August 4, 2022 | Blog post

Facebook Business Extension, v2

This change applies to all versions.
Two new fields have been added to the Facebook Business Extension, v2.

• Ad Account ID (ad_account_id) — Represents the ad account ID selected by the user inside FBE. This ad account can be used to manage ads if your app has ads_management permissions.
• Catalog ID (catalog_id) — The catalog ID selected by the user inside FBE. This ID can be used to manage their product catalog.

Instagram

Hashtag Search

This change applies to v7.0+.
You can now request the timestamp field on IG Media returned by GET /{ig-hashtag-id}/top_media and GET /{ig-hashtag-id}/recent_media Hashtag Search queries. For example: GET /{ig-hashtag-id}/top_media?fields=timestamp.

Messenger

Customer Chat Plugin

This change applies to v7.0+ and will apply to all versions on Nov 2, 2020.
When a new conversation is started or an existing conversation continued via the Customer Chat Plugin, the initial messaging_postbacks and messaging_referrals webhook notifications will contain an anonymous user_ref ID for the user instead of the user's Page-Scoped ID (PSID). Once the user sends a message, subsequent webhook notifications will contain the user's PSID.

Page Messenger Profiles

This change applies to v7.0+.
The home_url property on Page Messenger Profiles has been deprecated for all operations (GET, POST, and DELETE).

Open Graph

Deprecations

This change applies to v7.0 and will apply to all versions on Aug 3, 2020.

• GET /{open-graph-action-type-id}
• POST /{user-id}/{open-graph-action-type-id}

Pages

App-Scoped User IDs

These changes apply to v7.0+ and will apply to all version on May 5, 2021.
On May 1st, 2018, the Pages API began returning Page-Scoped User IDs (PSID) instead of App-Scoped User IDs (ASID) for all new apps. Apps created before this date continued to receive ASIDs unless they opted-in to receive PSIDs. All apps will now receive PSIDs from the Pages API.
The Page-Scoped ID API allows you to map ASIDs to their PSID equivalents. The API is deprecated in v7.0+, but can be used with older versions until May 5th, 2021.

Deprecations

These changes apply to v7.0+ and will apply to all versions on Aug 3, 2020.

• GET /{page-id}/featured_videos_collection
• POST /{page-id}/albums

Permissions

The manage_pages permission has been deprecated and replaced with 4 new permissions:

• pages_manage_ads
• pages_manage_metadata
• pages_read_engagement
• pages_read_user_content
  The publish_pages permission has been deprecated and replaced with 2 new permissions:
• pages_manage_posts
• pages_manage_engagement
  Apps that have already been approved for manage_pages or publish_pages, or both, will be migrated to the new permissions by June 1, 2020.
  For apps that have been submitted but not yet reviewed for manage_pages or publish_pages, or both, the review process will continue as normal. Once approved, apps will be migrated to the new permissions by June 1, 2020.
  To apply, or resubmit, for Page permissions before June 1, 2020, select the permissions you see in your app dashboard, either manage_pages or publish_pages, or both, or the new permissions. Your app will automatically be migrated to the new permissions by June 1, 2020, if necessary.
  After June 1, 2020, manage_pages and publish_pages will no longer be available in the App Review > Permissions and Features selection in the App Dashboard.
  The manage_pages and publish_pages permissions will be fully deprecated in May of 2022. Changes to your code must be applied before this date.

SDKs

Please visit the iOS SDK Changelog and the Android SDK Changelog to learn of important upcoming changes to these SDKs.

User

Deprecations

These changes apply to v7.0+ and will apply to all versions on Aug 3, 2020.
The following endpoints are deprecated:

• GET /{user-id}/books
• GET /{user-id}/games
• GET /{user-id}/movies
• GET /{user-id}/television

Marketing API

Released May 5, 2020 | Available until March 3, 2021 | Blog post

Ad Campaigns

Campaign Budget Optimization

This change applies to v7.0+.
For a specific ad campaign, you can no longer set both lifetime_budget and spend_cap at the same time. You can only select lifetime_budget.
A campaign lifetime budget is spread out over the course of your campaign. When you use lifetime_budget at the campaign level, the spend cap information is already included. Therefore, there is no reason to add a second spend cap.
You can continue using spend_cap for campaigns not using Campaign Budget Optimization.

Special Ad Category

This change applies to v7.0+.
The special_ad_category parameter on the POST /act_/campaigns endpoint has been deprecated and replaced with a new special_ad_categories parameter.
The new special_ad_categories parameter is required and accepts an array. If you get the special_ad_category parameter, it will still return a string, but you should use GET /{campaign-id}?fields=special_ad_categories to get an array back.
For details, see Special Ad Category.
Learn more about Special Ad Categories, Ads Help Center.

Deprecations
This change applies to v7.0+.
The budget_rebalance_flag parameter has been deprecated. We recommend that you use Campaign Budget Optimization instead.

Atlas Ad Campaigns

Deprecations

This change applies to v7.0+.

• GET /{atlas-ad-campaign-id}/cumulative_edited_date

Product Catalog

Deprecations

This change applies to v7.0+.
The cpas_parent_catalog_settings parameter on the POST /PRODUCT_CATALOG_ID edge is deprecated for third-party apps.

Original source

Graph API

Released August 4, 2020 | Available until November 1, 2022 | Blog post

Access Tokens

Deprecated Endpoints

Deprecated in v8.0+. Will be deprecated in all versions Nov 2, 2020.

• GET /token_deprecation_check

Albums

Reinstated Endpoints
Applies to all versions.

• GET /{album-id}/likes

App Configuration

App Types

This change applies to all versions.
Newly created apps can now choose an App Type: Business, Gaming, or None. This simplifies the App Review interface by removing inappropriate Permissions and Features based on the chosen type. In addition, apps typed as Business apps use a new authorization mechanism, no longer use modes, and have access to a new Feature. Refer to the Business apps changelog entry for details.

Business Apps

Apps typed as Business apps use a new authorization mechanism called Access Levels. Access Levels replace the functionality provided by Development Mode and Live Mode, which have been removed for Business apps, and make the App Review process simpler and more intuitive. In addition, a new Business Asset User Profile Access Feature has been released, which allows Business apps to read a small set of public User fields. These changes are described in more detail below.

Access Levels

Applies to all versions.
Access Levels are a new Graph API authorization mechanism for Business apps that apply to Permissions and Features on an individual basis. Standard Access only allows access to data owned by users who have a Role on the app, or a Role in a Business that has claimed the app. Advanced Access allows access to data owned by any app user, but requires App Review. Business apps are auto-granted Standard Access for all Permissions and Features available to their type.

Development and Live Mode Removal

Applies to all versions.
Development Mode and Live Mode have been removed for apps typed as Business apps. These modes have been replaced by Access Levels, which provide the same functionality and more versatility — since Business apps have Standard Access for all available Permissions and Features, any user with a Role on the app, or a Role in a Business that has claimed the app, can grant the app any available Permission at any time. This eliminates the need for App Review or having to switch between modes during development.

New Business Asset User Profile Access Feature

Applies to all versions.
The new Business Asset User Profile Access Feature allows Business apps to read a small set of public Fields on a User, as long as the User has engaged with assets owned by a Business that has claimed the app. Refer to the Business Asset User Profile Access reference for a list of readable User Fields.

Comments Reinstated Endpoints

Applies to all versions.

• GET /{comment-id}/likes

Devices

Deprecated Endpoints

Deprecated in v8.0+. Will be deprecated in all versions Nov 2, 2020.

• POST /device/share

Groups

Deprecated Endpoints

Deprecated in v8.0+.

• GET /{group-id}/posts
  Deprecated in v8.0+. Will be deprecated in all versions Nov 2, 2020.
• GET /{group-post-id}/likes

Instagram

New Instagram oEmbed Endpoint

Applies to all versions.
A new GET /instagram_oembed endpoint has been introduced. It provides the same functionality as Instagram's Legacy oEmbed endpoints, which will be deprecated on Oct 24, 2020. The new endpoint requires an access token, so you will need a Facebook Developer account and registered app to access it. Refer to the Instagram oEmbed document for usage instructions and additional details.

Life Events

Deprecated Endpoints

Deprecated in v8.0+.

• GET /{life-event-id}
• GET /{life-events-id}/photos

Links

Deprecated Endpoints

Deprecated in v8.0+.

• GET /{link-id}/reactions

Live Videos

Deprecated Endpoints

Deprecated in v8.0+.

• GET /{live-video-id}/likes
  Use the GET /{live-video-id}/reactions endpoint to get likes for a LiveVideo.

save_vod Parameter

Applies to v8.0+. Will apply to all versions on Nov 2, 2020.
The save_vod parameter is deprecated for the following edges:

• POST /{user_id}/live_videos
• POST /{group_id}/live_videos
• POST /{page_id}/live_videos
• POST /{event_id}/live_videos

Messenger Platform

Deprecated Endpoints

Deprecated in v8.0+.

• GET /{page-id}/thread_settings
• POST /{page-id}/thread_settings
• DELETE /{page-id}/thread_settings

App Review

Applies to all versions.
App Review for Messenger has been moved from Products > Messenger > Settings to App Review in the app dashboard. To request Messenger specific permissions, pages_messaging, pages_user_gender, pages_user_locale, and pages_user_timezone, go to App Review > Permissions and Features. See the Messenger App Review documentation for more details.

Messenger Profile Edge

Applies to v8.0+.
The nested persistant menu type has been deprecated for POST /{page-id}/messenger_profile.

New Feature: Messenger for Shops

Applies to v8.0+.
Support for sending and receiving products on Messenger for Shops. This includes the Product Template that can be used to send products in messages, Webhooks for messages with product template and messages from Facebook Shops Product Detail Page, and echo Webhooks for messages with products.

• GET /{message_id}/access_requests
• POST {page_id}/message
• message_echo Webhook
• messages Webhook

Native Offers

Deprecated Endpoints

Deprecated in v8.0+.

• GET /{native-offer-id}/nativeofferviews?photos

Open Graph

Deprecated Endpoints

Deprecated in v8.0+. Will be deprecated in all versions on Nov 2, 2020.

• GET /{open-graph-action-id}/comments
• POST /{open-graph-action-id}/comments

Pages

Deprecated Endpoints

Deprecated in v8.0+.

• DELETE /{page-id}/tabs
• GET /{group-id}/posts
• GET /{page-id}/place_topics
• GET /{page-about-story-id}
• POST /{page-about-story-id}
• POST /{page-id}/page_about_story

Page Post

Deprecated in all versions.
The Page Post comment ID format, {page-id}{post_id}{comment-id}, has been deprecated. Use the {pagepost-id}_{comment-id} format instead.

Photos Deprecated Endpoints

Deprecated in all versions.

• GET /{photo-id}/sharedposts

Places

Deprecated Endpoints

Deprecated in v8.0+.

• GET /{place-information-id} (see Corrections)

Posts

Deprecated Endpoints

Deprecated in v8.0+. Will be deprecated in all versions on Nov 2, 2020.

• GET /{post-id}/likes
  Use the GET /post/reactions endpoint to get likes for a post.

Search

Deprecated Endpoints

Deprecated in v8.0+. Will be deprecated in all versions Nov 2, 2020.

• GET /search?type=place
• GET /search?type=audience_interest

Security Settings

Deprecated Fields

Deprecated in v8.0+. Will be deprecated in all versions on Nov, 2020.

• secure_browsing

Social Plugins

Facebook oEmbed Endpoints

This change will apply to all versions on October 24, 2020.
Facebook oEmbed Endpoints, which allow apps to get embed HTML for public Facebook posts and videos, will be deprecated on October 24, 2020. Three new endpoints have been introduced which provide the same functionality as the old endpoints they are replacing:

• GET /oembed_page
• GET /oembed_post
• GET /oembed_video
  The new endpoints require an Access Token and requests will be subject to rate limiting. Please refer to the new oEmbed endpoint documenation for usage details and additional information.

Users

Deprecated Endpoints

Deprecated in v8.0+.

• GET /{user-id}/taggable_friends

Deprecated Fields

Deprecated in v8.0+. Will be deprecated in all versions on Nov, 2020.

• security_settings
• test_group
• viewer_can_send_gift
• is_shared_login
  Deprecated in all versions.
• can_review_measurement_request
• is_famedeeplinkinguser

Reauthorization

This change applies to all versions.
Starting Oct 24, 2020, the following fields will require Data Access Reauthorization after 90 days of inactivity:

• is_eligible_promo
• payment_mobile_pricepoint
• payment_pricepoints

User Picture

Applies to all versions on Oct 24, 2020.
Starting October 24, 2020, the GET /{user-id}/picture endpoint (GET /{user-id}?fields=picture) will require an App-Scoped User ID (ASID) for tokenless requests. If you query the User with a non-ASID, you must include an App, Client, or User Access Token in the request. Refer to the User Picture reference for details.

Video Questions Deprecated Endpoints

Deprecated in v8.0+.

• GET /{question-id}
• GET /{question-id}/options
• GET /{question-id}/votes
• GET /{question-option-id}

Workplace

Deprecated Endpoints

Deprecated in v8.0+. Will be deprecated in all versions on Nov 2, 2020.

• GET /{company-id}/access_requests
• GET /access_requests

Marketing API

Released August 4, 2020 | Available until May 4, 2021 | Blog post

Ad Accounts

Deprecated Endpoints

Deprecated in v8.0+.

• GET /AdReportSchedule
• DELETE act_{ad-account-id}/adsets

Permissions

Applies to v8.0+. Will apply to all versions on Nov 2, 2020.
Apps need granular permissions to access the business fields of an Ad Account. Permissions should be granted for a specific Business object.

Asset Customization Rules Validation

Applies to v8.0+.
All ads using asset_feed_spec must contain at least two target customization rules. If your creative uses asset_feed_spec and includes less than two rules, you will not be able to create that ad.
This change affects Placement Asset Customization, Multi-Language Ads, and Segment Asset Customization.

Segment Asset Customization

Applies to v8.0+. Will apply to all versions on Nov 2, 2020.
All use cases unrelated to geolocation have been deprecated for Segment Asset Customization users. With this change, all targeting rules must contain geolocation information inside their customization spec. There is an exception for the default rule, which does not need to include geolocation.

Bidding Target Cost Bid Strategy

Applies to v8.0+
The TARGET_COST bid strategy is deprecated. To continue controlling cost, we recommend using cost cap bidding. See all available bid strategies.

Business Manager Deprecated Endpoints

Deprecated in v8.0+.

• GET {system-user-id}/updated_by

Reintroduced Sharing Agreements Endpoints

Applies to all versions
The following endpoints have been reintroduced:

• /{business-id}/received_sharing_agreements
• /{business-id}/initiated_sharing_agreements
  Both endpoints had previously been deprecated with the launch of Graph API V6.0.

Canvas Deprecated Endpoints

Deprecated in v8.0+.

• /{canvas-id}/collection_hero_image
• /{canvas-id}/collection_hero_video
• /{canvas-id}/collection_thumbnails

Catalog API Permissions

Applies to v8.0+. Will apply to all versions on January 31, 2021.
You no longer need the ads_management permission to access product catalog endpoints. Moving forward, you will need the catalog_management permission to call those endpoints. Developers who have had access to catalog endpoints via ads_management in the last 90 days will be automatically migrated to catalog_management permissions by August 14, 2020.
From now until February 28, 2021, developers using prior versions of the API are still able to call product catalog endpoints with the ads_management permission. If you are using v8.0, you must have catalog_management permission.
After the February deadline, the catalog_management permission will no longer be associated with ads_management, so users will have to explicitly grant catalog_management permission for your app.

Authentication

Applies to v8.0+. Will apply to all versions on Nov 2, 2020.
[UPDATED] The following Catalog API endpoints now respect two-factor authentication Business settings. Any app calling this endpoint will receive an error if the Business that owns the catalog requires two-factor authentication for the current app user and the app user has not authenticated via two-factor.
When the current app user has access to the catalog through a partner business, we respect the authentication requirements from the partner’s Business Manager. System users do not have to authenticate via two-factor.

• POST /{business-id}/owned_product_catalogs
• POST /{destination-id}
• POST /{home-listing-id}
• DELETE /{home-listing-id}
• POST /{hotel-id}
• DELETE /{hotel-id}
• POST /{hotel-id}/hotel_rooms
• POST /{hotel-room-id}
• DELETE /{hotel-room-id}
• POST /{page-id}/product_catalogs
• POST /{product-catalog-id}
• DELETE /{product-catalog-id}
• POST /{product-catalog-id}/agencies
• DELETE /{product-catalog-id}/agencies
• POST /{product-catalog-id}/assigned_users
• DELETE /{product-catalog-id}/assigned_users
• POST /{product-catalog-id}/batch
• POST /{product-catalog-id}/categories
• POST /{product-catalog-id}/destinations
• POST /{product-catalog-id}/external_event_sources
• DELETE /{product-catalog-id}/external_event_sources
• POST /{product-catalog-id}/flights
• POST /{product-catalog-id}/home_listings
• POST /{product-catalog-id}/hotel_rooms_batch
• POST /{product-catalog-id}/hotels
• POST /{product-catalog-id}/items_batch
• /{product-catalog-id}/pricing_variables_batch
• POST /{product-catalog-id}/product_groups
• POST /{product-catalog-id}/product_feeds
• POST /{product-catalog-id}/product_sets
• POST /{product-catalog-id}/products
• POST /{product-catalog-id}/vehicles
• POST /{product-feed-rule-id}
• DELETE /{product-feed-rule-id}
• POST /{product-feed-id}
• DELETE /{product-feed-id}
• POST /{product-feed-id}/rules
• POST /{product-feed-id}/uploads
• POST /{product-feed-schedule-id}
• DELETE /{product-feed-schedule-id}
• POST /{product-feed-upload-id}/error_report
• POST /{product-group-id}
• DELETE /{product-group-id}
• POST /{product-group-id}/products
• POST /{product-item-id}
• DELETE /{product-item-id}
• POST /{product-set-id}
• DELETE /{product-set-id}
• POST /{vehicle-id}

Reporting

Deprecations
Applies to v8.0+

• GET /{ad-study-id}?fields=split_test_config
• GET /{ad-study-id}?fields=iterative_split_test_config

Targeting

Deprecation
Applies to v8.0+

• GET /search?type=adzipcode

Corrections

• September 28, 2020 — Updated the Catalog API authentication entry for clarity.
• October 23, 2020 — Updated the Catalog API entry :
  • We extended the deadline when developers using prior versions of the API are still able to call product catalog endpoints with the ads_management permission. The new deadline is February 28, 2021.
  • We added clarification about system user authentication.
• May 17, 2021 — Changed deprecated endpoint from GET /{place-id} to GET /{place-information-id}. GET /{place-id} was not deprecated.

Original source

Graph API

Released November 10, 2020 | Available until February 23, 2023 | Blog post

Groups

Deprecated endpoints
Deprecated in v9.0+. Will be deprecated in all versions February 9, 2021.

• GET /{group-id}?fields=owner

Instagram

Ads

Applies to v9.0+
IG Media IDs and IG User IDs can now be used with the Instagram Ads API to create ads. See the Instagram Ads API changelog entry for more information.

Insights

Applies to v9.0+. Will apply to all versions on May 9, 2021.
IG User follower_count values now align more closely with their corresponding values displayed in the Instagram app. In addition, follower_count now returns a maximum of 30 days of data instead of 2 years.

Marketing API

Released November 10, 2020 | Available until August 25, 2021 | Blog post

Asset Customization Rules

Deprecated Endpoints

Deprecated in v9.0+.

• GET /{asset_customization_rule_id}/
  Note: You can still query individual asset customization rules via the asset_feed_spec field on the ad creative node.

Bidding

Deprecated Bid Strategy

Applies to v9.0+
The target_cost bid strategy has been deprecated. Starting with v9.0, you can no longer create or update ad sets or ad campaigns with this setting. Instead, we recommend using cost cap bidding.

Deprecated Billing and Optimization Option

Applies to v9.0+
Starting with v9.0, CPA billing for app ads is deprecated, you cannot set both billing event and optimization goal to APP_INSTALLS. Instead, we recommend using the impression billing events.
You can still specify APP_INSTALLS under billing_event or optimization_goal, but not both at the same time.

Business

Endpoint Access Restrictions

Applies to all versions.
Access to the following endpoints is temporarily limited to apps that have queried them within the last 90 days:

• POST //access_tokens
• POST /{business-id}/business_users
• POST /{business-id}/system_users

Catalog API

Product Sets

Applies to v9.0+. Will apply to all versions February 9, 2021.
By default, the DELETE /{product_set_id} endpoint can no longer delete product sets while they are being used in active ads, shop collections or other usages. To override this behavior, include the new allow_live_product_set_deletion=true parameter in the request.

Instagram Ads API

Applies to v9.0+
Starting with v9.0, you can use the Marketing API to create Instagram ads from existing Instagram posts. See Use Posts as Instagram Ads, Instagram Posts. As part of this change, we have updated the following endpoints and fields, as described below.
These endpoints can now return Instagram User ID (IG User), if available:

• GET //connected_instagram_accounts
• GET //instagram_business_accounts
• GET /
  These endpoints now accept Instagram Media ID (IG Media) and Instagram User ID (IG User) as a parameter:
• POST //adscreatives
• POST //ads
  This endpoint now accepts Instagram Media ID (IG Media) as a parameter:
• POST //advideos
  This field can now return an Instagram User ID (IG User), if available:
• GET /?fields=connected_page_backed_instagram_account

Lead Ads

Lead Retrieval for Dev Mode Apps

Applies to v9.0+. Will apply to all versions February 9, 2021.
Starting in v9.0, you will not be able to retrieve leads if your app is in Dev Mode. For testing purposes, Dev Mode app users can access leads submitted by someone with a role in that same app. See App Roles. Apps in Live Mode continue to have access to all leads.
The rules are different for business apps, since they do not have Dev and Live modes. If you are running a business app, you must request Advanced Access for the leads_retrieval permission to be able to retrieve leads.

Original source

Graph API

Released February 23, 2021 | Available until June 8th, 2023 | Blog post

Business Apps

Access Levels

Applies to all apps created after February 16, 2021.
All Business type apps created after February 16, 2021 will automatically be granted Standard access to the email and public_profile permissions.
Applies to all existing apps created after February 16, 2021.
All Business type apps created before February 16, 2021 will automatically be granted Advanced access to the email and public_profile permissions. Apps that are not using the email or public_profile permissions will be downgraded to Standard access for these two permissions.
Business type apps can upgrade to Advanced access for the email and public_profile permissions without going through App Review.

Groups

Applies to v10.0+. Will apply to all versions on May 25, 2021.

• To align with other Facebook data retention policies, the Groups API will only include data created within the last 90 days of your queries. The data returned is dependent on the access level or mode of your app and your role on the app.
• Groups API will now use a 2 tiered API access level system, Standard level and Privileged level, instead of Dev mode and Live mode access. Standard level access will only allow you to get data for users that have a role on your app, while Privileged level access will allow you to get data from all users in the group that the app is installed in.

Pages

Reinstated endpoint
Applies to v10.0+. Will apply to all versions on May 25, 2021.
The DELETE /{page-id}/tabs endpoint that was deprecated in v8.0 has been reinstated in v10.0 and will be reinstated in all versions on May 25, 2021.

Threat Exchange

Deletion of expired data
Will apply to all versions on May 25, 2021.
Data uploaded to ThreatExchange with a non-zero expire_time will be permanently deleted at the expiration time indicated. If you wish to delete data that is no longer valid, set the expired_on field to the current time to have the data deleted immediately.
Additionally, all non-Facebook ThreatDescriptors will be permanently deleted once they reach the expiration date set by the creator. If your application currently has expired ThreatDescriptors that you don’t want deleted, you must extend the expiration date or set it to ‘0’ to ensure that the data never expires.

URL

Applies to v10.0+. Will apply to all versions on May 25, 2021.

Engagement

• Due to privacy concerns, counts returned by a GET /?id={url}/engagement request may not match raw counts.
• Requests for the GET /?id={url}/engagement field for the same URL will be limited to 10 requests per hour.

Marketing API

Released February 23, 2021 | Available until October 4, 2021 | Blog post

Ad Account

Field changes
Applies to v10.0+. Will apply to all versions May 25, 2021.
The agency_client_declaration field on the AdAccount node now requires Admin privileges for all operations.

Ads Insights API

Updated date_preset parameter
Applies to v10.0+.

• The lifetime parameter (date_preset=lifetime) is disabled and replaced with date_preset=maximum, which can be used to retrieve a maximum of 37 months of data. The API will return an error when requests contain date ranges beyond the 37-month window.
• For v9.0 and lower, there will be no change in functionality until May 25, 2021. At that time, date_preset=maximum will be enabled and any lifetime calls will default to maximum and return only 37 months of data.

Business

Easing of Previous Endpoint Access Restrictions

Applies to 10+.
In v9.0, access to the endpoints below was restricted. Access has been restored to all apps, but apps can now only target businesses (or child businesses of those businesses) that have claimed them:

• POST //access_tokens
• POST /{business-id}/business_users
• POST /{business-id}/system_users

Targeting

Connections Targeting

Will apply to all versions May 24, 2021.
The following endpoints will no longer accept connections targeting when creating or editing ad campaigns:

• POST //adsets
• POST /
  This change will not affect any existing running campaigns.

Lookalike Audiences

UPDATED APRIL 28, 2021: The removal of the location_spec and country parameters from lookalike audience creation is currently delayed. Updates on when this change will go into effect will be forthcoming.
The location_spec and country parameters will be removed from lookalike audience creation. The location for the lookalikes will be defined by the country location in the campaign’s targeting specification.
There will be no impact on existing campaigns given this change. This requirement will only impact new and edited campaigns.
The following endpoints and fields will be affected:

• POST //customaudiences
• POST //adsets
• POST //adaccounts?adaccounts=
• GET //reachestimate
• GET //delivery_estimate
• GET /?fields=approximate_count
• GET /?fields=delivery_status
• GET /?fields=operation_status
  See Lookalike Audiences: Upcoming Lookalike Changes for more information on these updates.

Original source

Graph API

Released June 8, 2021 | Available until September 14, 2023 | Blog post

Consumer Apps

Access Levels

Applies to all versions.
In the coming weeks, access levels will apply to all existing Consumer apps. For these apps, permissions and features already approved through the App Review process will be automatically approved for Advanced Access. All other permissions and features will automatically be approved for Standard Access.
Access levels will also apply to all newly created apps in the coming weeks. Newly created apps will automatically be approved for Advanced Access for the email and public_profile permissions. However, both permissions will be set to Standard Access by default and must manually be set to Advanced Access before they can be requested from app users who do not have roles on the apps.

Developer Support

We have released the Facebook for Business Status tool to monitor the health of platform and business products such as Ads Manager, WhatsApp Business, and Facebook Developer Platform.

Facebook Analytics

Deprecation

Applies to all versions.
Facebook Analytics will no longer be available after June 30, 2021. Additionally, we are deprecating the App Dashboard Plugin for Marketing API. For more information visit the Business Help Center.
The following Application Node fields are no longer available:

• analytics_config
• analytics_platform_metrics_config
• permissible_ad_accounts
  The following endpoints are no longer available:
• GET Application/analytics_cohort_query
• GET Application/analytics_entity_user_config
• GET Application/analytics_event_types
• GET Application/analytics_funnel_query
• GET Application/analytics_query
• GET Application/analytics_segments

Instagram Basic Display API

Access Token Debugger

Applies to all versions.
The access token debugger tool now only returns an app-scoped ID when debugging a token.

API Versioning

Applies to all versions.
The API now supports versioned calls. To query a specific API version include the version number in the query path after the base URL. For example:
https://graph.instagram.com/v11.0/{node-id}/{edge-name}
Un-versioned requests (missing the version number) resolve to the version specified in the calling app's App Dashboard > Settings > Advanced > Upgrade API Version setting.

App Scoped User IDs

Applies to version 11.0+.
App-scoped user IDs (ASIDs) have been introduced. ASIDs will replace raw user IDs in approximately two years, when version 10.0 is deprecated, so we recommend that you begin mapping your app users' raw IDs to their ASID equivalents.

• All versions support raw user ID based queries.
• Only version 11.0+ calls support ASID based queries.
• Version 11.0+ calls will receive ASIDs in responses, even when querying raw user IDs.

Time-based Pagination

Applies to v11.0+.
Added since and until parameters to the GET /{user-id}/media endpoint to support time-based pagination.

Instagram Graph API

Like Counts

Applies to v11.0+. Will apply to all versions September 7, 2021.
If indirectly querying an IG Media through another endpoint or field expansion, the like_count field will be omitted from API responses if the media owner has hidden like counts on it. Directly querying the IG Media (which can only be done by the IG Media owner) will return the actual like count, however, even if like counts have been hidden.

Time-based Pagination

Applies to v11.0+.
Added since and until parameters to the GET /{ig-user-id}/media endpoint to support time-based pagination.

Instant Experiences Templates

Applies to v11.0+.
Instant Experience Templates have moved out of of beta and are now available to all developers.

Messenger Platform

Messaging Postbacks Webhook

Applies to v11.0+.
The mid field has been added to the messaging_postbacks webhook to allow apps to get the Message ID.

Deprecation of Airline Templates

Applies to v11.0+. Will apply to all versions on Dec 6, 2021.
Calls to POST /{page-id}/messages that include any airline templates (template_type of types airline_boardingpass, airline_checkin, airline_itinerary, airline_update) will fail.

oEmbed

New oEmbed Read Feature

Applies to all versions.
The oEmbed product has been replaced with a new oEmbed Read feature. If you implemented the oEmbed product before June 8, 2021, you have until September 7, 2021 to complete App Review for the oEmbed Read feature. If you have not been approved for the oEmbed Read feature by September 7, 2021, your oEmbed implementations will fail to load.

Pages API

Comment IDs

Applies to v11.0+. Will apply to all versions on September 7, 2021.
The id field for comments will not be returned for any apps that only use the Page Public Content Access feature to query Pages endpoints. These include the id fields /PAGEPOST-ID/comments or /COMMENT-ID/comments. To get the id fields for comments for comments on Page posts the app user must be able to perform the MODERATE task on the Page being queried.

New Page Experience

Over the coming months, all classic Pages will be migrated to the New Pages Experience. Use the has_transitioned_to_new_page_experience Page field to determine if a Page has been migrated. After all Pages have been migrated, the classic Pages experience will no longer be available.
Most Pages API endpoints support both classic and NPE Pages. Endpoints that support NPE Pages display a "New Pages Experience" section in their references.
The following endpoints do not support NPE pages:

• /PAGE-ID/likes
• /PAGE-ID/global_brand_children
• /PAGE-ID/locations
• /PAGE-ID/tabs
• /PAGE-ID/visitor_posts
  Several Page fields are not available for NPE and will return null, a different data set or an error when called. Please visit our New Pages Experience Overview for a list of these Page fields.

Permissions user_likes

Applies to all versions.
The allowed usage for the user_likes permission has been updated. Starting September 7, 2021, apps that have already been approved for this permission but that violate its new usage description will have their approval revoked.

• Old allowed usage: Meaningfully improve the quality of a user's experience in your app (must be clear to the user how their data is used to provide that experience).
• New allowed usage: Provide a personalized experience by correlating or surfacing content related to the person’s likes. This includes curating content at scale to customize apps with large amounts of content and to enable people to share their likes with others, such as in the case of dating and music apps.

user_posts

Applies to all versions.
The allowed usage for the user_posts permission has been updated. Starting September 7, 2021, apps that have already been approved for this permission but that violate its new usage description will have their approval revoked.

• Old allowed usage: Meaningfully improve the quality of a user's experience in your app (must be clear to the user how their data is used to provide that experience).
• New allowed usage: Enable people to create physical or digital books or albums of their timelines, and to share memories from their timeline on Facebook or on other social apps.

SDK

Please visit the iOS SDK Changelog, Android SDK Changelog, and Unity SDK Changelog to learn about important upcoming changes to these SDKs.

Marketing API

Released June 8, 2021 | Available until February 23, 2022 | Blog post Audiences Custom Audiences, Lookalike Audiences, and Saved Audiences Deletion

Applies to all versions.
Beginning June 8, 2021 and going forward, any Custom Audience, Lookalike Audience, or Saved Audience that has not been used in any active ad set in over two years will be flagged as an "Expiring Audience". Then, the audience is scheduled to be deleted 90 days after being marked as an "Expiring Audience".
Developers will be able to filter for the "Expiring Audience" status using the operation_status field and see the audience's estimated time deletion in the system using the delete_time field. Developers can choose to either proactively delete the audience or use the audience in an active ad set to prevent deletion. Once an audience is deleted, advertisers will not be able to reactivate the audience.
For Custom Audiences (except Customer List Custom Audiences), Lookalike Audiences, or Saved Audiences:

• If advertisers wish for the flagged audiences to be automatically deleted beginning Sept 6, 2021 there is no action they need to take. However, if advertisers wish, they can also proactively delete the audience prior to the automatic deletion date.
• For flagged audiences advertisers wish to maintain, they should plan to use these in an active ad set prior to Sept 6, 2021 to prevent the audience from being deleted.
  For Customer List Custom Audiences:
• We store these on behalf of advertisers in accordance with their instructions. If advertisers do not take any action to use flagged audiences in an active ad set before Sept 6, 2021, we will consider this an instruction for us to delete the flagged audience.
  The following endpoints and fields will be affected:
• GET /{custom-audience-id}
• GET /act_{ad-account-id}/customaudiences?filtering
• GET /act_{ad-account-id}/saved_audiences?filtering
• GET /{saved-audience-id}
  See Audiences Overview: Custom Audiences Deletion Changes for more information on these updates.

Business API

Applies to all versions.
We are temporarily limiting access to the following endpoints. Only apps that have successfully called these endpoints within the last 30 days will continue to have access.

• POST /BUSINESS-ID/client_ad_accounts
• POST /ADACCOUNT-ID/agencies
  All other apps will receive an error when making calls to these endpoints.

Catalog API Deprecation of Product Inventory Field

Applies to 11.0+.
The inventory field will be deprecated and replaced with a new quantity_to_sell_on_facebook field. While we will continue to support the inventory field for the near term, we recommend that you use the new quantity_to_sell_on_facebook field instead.
The following endpoints are affected:

• GET /{product-item-id}
• GET /{catalog-id}/products
• POST /{product-item-id}
• POST /{catalog-id}/items_batch
  See Quantity to Sell and Supported Fields for Products - Dynamic Ads & Commerce for more information on this update.

Deletion of Non-Empty Product Groups

Applies to 11.0+. Will apply to all versions on Sept. 7, 2021.
We will no longer allow deletion of non-empty product groups by default. Non-empty product groups can be deleted by applying deletion_method=delete_items to the deletion request. This will delete both the product group and its items.
The following endpoint is affected:

• DELETE /

Deletion of Live Product Sets

Applies to 11.0+. Will apply to all versions on Sept. 7, 2021.
We will no longer allow deletion of a catalog with live product sets by default. To enable deletion of a catalog that contains a live product set, set the catalog's allow_delete_catalog_with_live_product_set parameter to true.
This change affects the following endpoint:

• DELETE /

New Diagnostics Endpoint

Applies to 11.0+.
We have added a new endpoint GET /{product_catalog_id}/diagnostics. This endpoint can be used to retrieve diagnostics data for a given catalog, such as issues that prevent products from showing in channels and opportunities that could improve product discoverability.

Commerce API Order Total Estimated Payment Details

Applies to 11.0+. Will apply to all versions on Sept. 7, 2021.
We are changing the way estimated payment details are reported in order totals for calls to the {commerce-order-id}/?fields=estimated_payment_details endpoint. Previously, if an order was not fulfilled, an estimated tax was used, and for fulfilled orders, the fulfilled tax was used. Starting with version 11.0, this endpoint will always use the estimated tax. Note that details about the fulfilled tax can be accessed using {commerce-order-id}/items?fields=tax_details.

Conversion Lift Metrics Changes

Applies to v11.0+. Will apply to all versions on Sept. 7, 2021.
Metrics returned from the GET /{objective-id}/?fields=result field have changed.
The following metrics have been added:

• conversions_incremental_share
• conversions_CPiC
• conversions_multicell_confidence
• conversions_multicell_rank
• sales_incremental_share
• sales_multicell_confidence
• sales_multicell_rank
• buyers_incremental_share
• buyers_CPiB
• buyers_multicell_confidence
• buyers_multicell_rank
  The following metrics have been removed:
• advancedBuyers.control
• ancedBuyers.informativeMultiCellBayesianConfidence
• advancedBuyers.lift
• advancedBuyers.test
• advancedConversions.control
• advancedConversions.informativeMultiCellBayesianConfidence
• advancedConversions.lift
• advancedConversions.test
• advancedSales.control
• advancedSales.informativeMultiCellBayesianConfidence
• advancedSales.lift
• advancedSales.test
• buyers.baseline
• buyers.bayesianCILower
• buyers.bayesianCIUpper
• buyers.control
• buyers.delta
• buyers.incremental
• buyers.isStatSig
• buyers.lift
• buyers.multiCellBayesianConfidence
• buyers.reachedPercent
• buyers.singleCellBayesianConfidence
• conversions.baseline
• conversions.bayesianCILower
• conversions.bayesianCIUpper
• conversions.control
• conversions.delta
• conversions.incremental
• conversions.isStatSig
• conversions.lift
• conversions.multiCellBayesianConfidence
• conversions.reachedPercent
• conversions.singleCellBayesianConfidence
• frequency
• incrementalROAS
• sales.baseline
• sales.bayesianCILower
• sales.bayesianCIUpper
• sales.control
• sales.delta
• sales.incremental
• sales.isStatSig
• sales.lift
• sales.multiCellBayesianConfidence
• sales.singleCellBayesianConfidence
  The following metrics have been renamed:
  Old Name | New Name
  advancedBuyers.baseline | buyers_not_exposed
  advancedBuyers.bayesianCILower | buyers_incremental_lower
  advancedBuyers.bayesianCIUpper | buyers_incremental_upper
  advancedBuyers.incremental | buyers_incremental
  advancedBuyers.informativeMultiCellPairwiseBayesianConfidence | buyers_multicell_confidence
  advancedBuyers.informativeSingleCellBayesianConfidence | buyers_confidence
  advancedBuyers.scaled | buyers_control_scaled
  advancedConversions.baseline | conversions_not_exposed
  advancedConversions.bayesianCILower | conversions_incremental_lower
  advancedConversions.bayesianCIUpper | conversions_incremental_upper
  advancedConversions.incremental | conversions_incremental
  advancedConversions.informativeMultiCellPairwiseBayesianConfidence | conversions_multicell_confidence
  advancedConversions.informativeSingleCellBayesianConfidence | conversions_confidence
  advancedSales.baseline | sales_not_exposed
  advancedSales.bayesianCILower | sales_incremental_lower
  advancedSales.bayesianCIUpper | sales_incremental_upper
  advancedSales.incremental | sales_incremental
  advancedSales.informativeMultiCellPairwiseBayesianConfidence | sales_multicell_confidence
  advancedSales.informativeSingleCellBayesianConfidence | sales_confidence
  advancedSales.scaled | sales_control_raw_scaled
  buyers.pValue | buyers_raw_pValue
  buyers.reached | buyers_exposed
  buyers.scaled | buyers_control_raw_scaled
  buyers.test | buyers_test
  conversions.pValue | conversions_raw_pValue
  conversions.reached | conversions_exposed
  conversions.scaled | conversions_control_raw_scaled
  conversions.test | conversions_test
  IncrementalROAS | sales_ROAS
  sales.pValue | sales_raw_pValue
  sales.reached | sales_exposed
  sales.scaled | sales_control_raw_scaled
  sales.test | sales_test
  A complete list of the available metrics can be seen in the Facebook Lift Metrics Glossary.

Insights API

Deprecation of Store Visit Metrics

Applies to 11.0+. Will apply to all versions on Sept. 6, 2021.
The store_visits_actions and cost_per_store_visit_actions metrics are deprecated.
The following endpoints are affected:

• GET /{adaccount-id}/insights
• GET /{campaign-id}/insights
• GET /{adset-id}/insights
• GET /{ad-id}/insights
• POST /{adaccount-id}/insights
• POST /{campaign-id}/insights
• POST /{adset-id}/insights
• POST /{ad-id}/insights

Offer Ads API

Deprecation of Offer Ads API Endpoints

Applies to v11.0+. Will apply to all versions on Sept 7, 2021.
As part of our ongoing effort to increase product stability, Facebook will be ending its support for our Offer Ads product on June 8, 2021. Standard Facebook Ads are the recommended substitute for distributing your in-store and or online discounts. Discount information, redemption location(s), expiration date, and promotional codes are advised to be placed directly in the Ad Level creative.
The following endpoints are deprecated:

• GET /{page-id}/nativeoffers
• POST /[page-id}/nativeoffers
• GET /pagename/nativeoffers
• GET /{native-offer-id}
• GET /{native-offer-id}/views
• POST /{native-offer-id}/codes
• POST /{native-offer-id}/nativeofferviews
• GET /{offer-id}/comments
• GET /{offer-id}/sharedposts
• GET /{offer-id}/likes

Original source

Graph API

Released September 14, 2021 | Available until TBD | Blog post

App Insights

Endpoint Deprecation

Applies to v12.0+.
The App Insights API is deprecated. Affected endpoints:

• GET /{application-id}/app_insights

Errors

Endpoints that now throw errors
Applies to v12.0+. Will apply to all versions December 13, 2021.
The Graph API default behavior is to throw an error when an app requests a field or edge that returns an associated node or nodes, but lacks the appropriate permissions required by the associated nodes. Fields and edges on the endpoints listed below did not follow this protocol and instead were omitted from API responses when the calling app lacked appropriate permissions. Starting with version 12.0, these fields and edges will now conform to the default behavior. This change will apply to all versions on December 13, 2021.

• GET /{application-id}/authorized_adaccounts
• GET /{atlas-fb-conversion-event-id}/fb_ads_conversion
• GET /{business-unit-id}/ad_accounts
• GET /{business-unit-id}/atlas_sales_accesses
• GET /{canvas-product-set-id}/storefront_setting
• GET /{commerce-merchant-settings-id}/instagram_channel
• GET /{commerce-store-id}/merchant_settings
• GET /{destination-id}/augmented_realities_metadata
• GET /{destination-id}/videos_metadata
• GET /{event-id}/ticket_tiers
• GET /{flight-id}/augmented_realities_metadata
• GET /{flight-id}/videos_metadata
• GET /{live-encoder-id}/current_broadcast
• GET /{live-video-id}/copyright
• GET /{page-id}/admin_notes
• GET /{page-id}/businessprojects
• GET /{page-id}/connected_instagram_account
• GET /{page-id}/connected_page_backed_instagram_account
• GET /{page-id}/insights_exports
• GET /{page-id}/instagram_business_account
• GET /{ig-comment-id}/user
• GET /{ig-media-id}/owner
• GET /{ig-user-id}/mentioned_comment
• GET /{user-id}/adaccounts
• GET /{user-id}/assigned_ad_accounts
• GET /{user-id}/context
• GET /{user-id}/personal_ad_accounts
• GET /{video-copyright-id}/update_records

Instagram Messaging API

New User Profile Fields

Applies to v12.0+
Added four new fields to the GET /{ig-scoped-id} endpoint:

• is_verified_user
• follower_count
• is_user_follow_business
• is_business_follow_user

Live Video API

Scheduled Live Videos

Will apply to all versions December 13, 2021.
UPDATE: This deprecation has been delayed.
Scheduling live videos is no longer available. The planned_start_time parameter for the POST /ID/live_videos endpoint is deprecated. Calls using this parameter will return an error._
Affected endpoints:

• POST /{group-id}/live_videos
• POST /{page-id}/live_videos
• POST /{user-id}/live_videos

Messenger Platform

Multiple changes have been introduced that affect several Messenger APIs and webhooks. Please refer to the Messenger Platform changelog for a summary of these changes.

Video API

New Fields

Applies to v12.0+.
Added two new fields to the GET /{video-id} endpoint:

• post_views
• views

Workplace

Reported Content

Applies to v12.0+.
The reported_object_id field for the GET /company/reported_content endpoint is deprecated. Calls to this field will return no data. Use the new GET /reported_content/reporters endpoint instead.
Added six new endpoints:

• /REPORTED-CONTENT-ID
• GET /reported_content/reporters
• POST /REPORTED-CONTENT-ID/allow_content
• POST /REPORTED-CONTENT-ID/delete_content
• POST /REPORTED-CONTENT-ID/quarantine_content
• POST /REPORTED-CONTENT-ID/unquarantine_content

Marketing API

Released September 14, 2021 | Available until August 9, 2022 | Blog post

Ad Sets Targeting

Applies to v12.0+. Will apply to all versions December 13, 2021.
When optimizing for Value, Conversions, or App Events, detailed targeting inclusions will not affect the potential reach and may go beyond detailed targeting inclusions to improve performance. The new targeting_optimization_types parameter will indicate which targeting options are used as a signal for optimization.
The following endpoints will be effected:

• GET /{adset-id}
• GET /{adset-id}/delivery_estimate
  The POST /{adset-id} endpoint will return an error for updates to newly created ad sets with Value, Conversions or App Events as the optimization goals within Conversions objective campaigns using the targeting_optimization field. Existing ad sets will continue allowing changes to the field.
  The POST /{ad-account-id}/adsets endpoint will return an error if the targeting_optimization field is passed when creating a new ad set using Value, Conversions, or App Events as the optimization goals within Conversions objective campaigns. The targeting_as_signal field will be ignored when passed during ad set creation.

Business Management API

System User App Role Requirements

Applies to v12.0+. Will apply to all version December 13, 2021.
A system user can now only be granted a role on app if both the system user and the app belong to the same business. On December 13, 2021, app roles will be revoked for any system user who has a role on an app that does not belong to the same business as the system user.
If your app needs to access data using a system user and access token belonging to another business, use the Business On Behalf Of API instead.

Errors

Endpoints that now throw errors
Applies to v12.0+. Will apply to all versions December 13, 2021.
The Marketing API default behavior is to throw an error when an app requests a field or edge that returns an associated node or nodes, but lacks the appropriate permissions required by the associated nodes. Fields and edges on the endpoints listed below did not follow this protocol and instead were omitted from API responses when the calling app lacked appropriate permissions. Starting with version 12.0, these fields and edges will now conform to the default behavior. This change will apply to all versions on December 13, 2021.

• GET /{ad-account-id}/ad_saved_keywords
• GET /{ads-pixel-id}/shared_accounts
• GET /{ad-study-cell-id}/adaccounts
• GET /{business-id}/client_ad_accounts
• GET /{business-id}/collaborative_ads_managed_partner_business_info
• GET /{business-id}/extendedcreditapplications
• GET /{business-id}/owned_ad_accounts
• GET /{business-user-id}/assigned_ad_accounts
• GET /{custom-audience-id}/external_event_source
• GET /{custom-conversion-id}/pixel
• GET /{extended-credit-invoice-group-id}/ad_accounts
• GET /{hotel-id}/augmented_realities_metadata
• GET /{hotel-id}/videos_metadata
• GET /{instagram-user-id}/authorized_adaccounts
• GET /{lead-gen-data-id}/context_card
• GET /{lead-gen-data-id}/thank_you_page
• GET /{offline-conversion-data-set-id}/adaccounts
• GET /{offline-conversion-data-set-upload-id}/pull_sessions
• GET /{product-catalog-id}/auto_markets
• GET /{product-catalog-id}/autos
• GET /{product-catalog-id}/commerce_merchant_settings
• GET /Produ{product-catalog-id}ctCatalog/media_titles
• GET /{product-catalog-id}/services
• GET /{product-feed-id}/auto_markets
• GET /{product-feed-id}/autos
• GET /{product-feed-id}/media_titles
• GET /{product-set-id}/media_titles
• GET /{system-user-id}/assigned_ad_accounts
• GET /{vehicle-id}/augmented_realities_metadata
• GET /{vehicle-id}/videos_metadata

Conversions API

Change to access tokens

Applies to v12.0+
Access tokens generated under the Conversions API settings tab in Events Manager are no longer restricted to using the newest Graph API version that was available at the time of token generation. Starting with v12.0, newly created access tokens can be used with all available Graph API versions.
Please note that calls made with these tokens to a deprecated Graph API version will automatically resolve to the oldest available version. This behavior only applies to Graph API endpoints. Marketing API endpoints, including the Conversions API, will not resolve to the oldest available version and will instead throw an exception.

Catalog API

Deprecation of review_status field

Applies to v12.0+
The review_status field on the Product Item node is deprecated. This field has been unreliable and is no longer used in our internal system. Starting with version 12.0, review_status will not be accepted as a valid field. We recommend that you use the channels_to_integrity_status field instead. Please note that for version 11.0 and earlier, the review_status field will always return an empty string.
This change affects the following endpoints:

• GET /{catalog_id}/products?filter={"review_status":{"eq":{enum}}}
• GET /{catalog_id}/products?fields=["name","review_status"]

Catalog permissions

Applies to v12.0+. Will apply to all versions December 13, 2021.
If a user does not have business administrator permissions on the business associated with a catalog, they will not be able to modify catalog permissions.
The following edges are affected:

• POST /{product-catalog-id}/assigned_users
• DELETE /{product-catalog-id}/assigned_users
• POST /{product-catalog-id}/agencies
• DELETE /{product-catalog-id}/agencies

Original source

Graph API

Released February 8, 2022 | Available until TBD | Blog post

Instagram Graph API

IG Media

Version 13 will be the last version to allow video_title field requests on IG Media without returning an error. As a reminder, the current API behavior outlined in our October 5th, 2021 blog post is as follows:

• media_product_type field returns FEED for all versions
• video_title field is omitted from responses for all versions
• Instagram Webhooks comments and mentions fields are supported for all versions

The behavior above applies to all IG Media, including IG Media created with the Instagram TV app, regardless of creation date.

User Insights

Applies to v13.0+
The following IG User Insights metrics no longer support since and until parameters, and responses will not include the end_time JSON property.

• audience_city
• audience_country
• audience_gender_age
• audience_locale

Marketing API

Released February 8, 2022 | Available until January 25, 2023 | Blog post

Ad Creative Placement Asset Customization Ads

Applies to v13.0+.
The asset_feed_spec node of the POST /{ad-account-id}/adcreatives endpoint will now allow the creation of carousel ads with Placement Asset Customization ads.

Ads Library API Ads Archive

Applies to v13.0+.
The following query edges and fields on the GET /ads_archive endpoint have been deprecated and replaced:
Old Edge/Field -> New Edge/Field

• funding_entity -> bylines
• region_distribution -> delivery_by_region
• potential_reach_min -> estimated_audience_size_min
• potential_reach_max -> estimated_audience_size_max
• potential_reach -> estimated_audience_size

The following return parameters on the GET /ads_archive endpoint have been deprecated and replaced:

• ad_creative_body -> ad_creative_bodies
• ad_creative_link_caption -> ad_creative_link_captions
• ad_creative_link_description -> ad_creative_link_descriptions
• ad_creative_link_title -> ad_creative_link_titles
• funding_entity -> bylines
• region_distribution -> delivery_by_region

Ad Sets Lookalike Expansion

Applies to v13.0+. Will apply to all versions May 9, 2022.
For newly created ad sets that optimize for value, conversions, or app events, lookalike expansion will be turned on by default and cannot be disabled. When getting an ad set that optimizes for value, conversions, or app events, we will return a new lookalike property in the targeting_optimization_types map that indicates lookalike expansion is enabled and complements the existing detailed_targeting property for the detailed targeting expansion.
This change affects the following endpoints:

• POST /{ad-account-id}/adsets
• GET /{ad-account-id}/adsets

Conversions API Customer Information Parameters

Applies to v13.0+.
There are new requirements for the combinations of customer information parameters that are considered valid for an event. An event will be considered invalid if it only includes parameters consisting of one of the following combinations or a subset thereof:

• ct + country + st + zp + ge + client_user_agent
• db + client_user_agent
• fn + ge
• ln + ge
  To ensure your events do not throw an error, we recommend that you review the Conversions API Best Practices.
  This change affects the following endpoints:
• POST /{pixel-id}/events
• POST /{offline_dataset_id}/events

Commerce Platform Shipping Profiles API

Applies to v13.0+.
The handling_time field of the GET /{cms-id}/shipping_profiles endpoint has been moved from the shipping_profile object to the address_category object.

Catalog Feed API

Applies to v13.0+.
The product feed upload error code XML_JUNK_AFTER_DOCUMENT has been renamed to DATA_OUTSIDE_XML_TAGS. This is a name change only.
The following endpoint is affected:

• GET /{feed_upload_session_id}

Original source

Graph API

Released May 25, 2022 | Available until September 17, 2024 | Blog post

Instagram Graph API

Insights

Applies to v14.0+.
The end_time JSON property will not be returned for any audience_* metrics.

Instagram Messaging API

User Profile

Applies to v14.0+
You can now use the User Profile API to get an app user's username.

Payments Risk action type

Applies to v14.0+.
The risk action type of the actions field (GET /{payment-id}?fields=actions) has been removed and will not be returned.

Permissions

user_likes

Applies to all versions.
The user_likes permission's allowed usage has changed. The new allowed usage is:

• Provide a personalized experience by correlating or surfacing content related to the person’s likes. This includes curating content at scale to customize apps with large amounts of content and to enable people to share their likes with others, such as in the case of dating and music apps.
• Allow parental access controls and monitoring apps to analyze user likes for potential safety and wellbeing issues for people under 18 years old, as used solely by parents and guardians for under 18 year old dependents and limited to youth social media analysis as presented in the app’s user interface.

user_posts

Applies to all versions.
The user_posts permission's allowed usage has changed. The new allowed usage is:

• Enable people to create physical or digital books or albums of their timelines, and to share memories from their timeline on Facebook or on other social apps.
• Allow parental access controls and monitoring apps to analyze a post's content to detect potential risk to safety or wellbeing for people under 18 years old, as used solely by parents and guardians for under 18 year old dependents and limited to youth social media analysis as presented in the app’s user interface.

WhatsApp

See the Whatsapp changelog.

Marketing API

The expiration date for Marketing API v14.0 and v15.0 has been moved to September 20, 2023 from August 15, 2023 to provide more time for the platform integrating changes for DSA enforcement. Note v14.0 and v15.0 will expire on the same day. To avoid disruption to your apps, we recommend upgrading to our latest version before September 20.
Released May 25, 2022 | Available until September 20, 2023 | Blog post
No changes.

Original source

Graph API

Released September 15, 2022 | Available until November 20, 2024 | Blog post

Instagram Graph API

Story Webhooks

Applies to all versions.
Story insights webhooks notifications are now sent 1 hour after story expiration.

Pages API

Custom Page Tabs

Applies to v15.0+. Will apply to all versions December 14, 2022.
Custom Page Tabs are no longer available. The following endpoints are affected:

• POST /{page-id}/tabs
• DELETE /{page-id}/tabs

Marketing API

The expiration date for Marketing API v14.0 and v15.0 has been moved to September 20, 2023 from August 15, 2023 to provide more time for the platform integrating changes for DSA enforcement. Note v14.0 and v15.0 will expire on the same day. To avoid disruption to your apps, we recommend upgrading to our latest version before September 20.
Released September 15, 2022 | Available until September 20, 2023 | Blog post

Audiences

Special Ad Audiences

Applies to all versions.
Special Ad Audiences, which are similar to lookalike audiences for housing, employment, and credit advertisers, have been deprecated due to a settlement with the US Department of Housing and Urban Development. See the developer blog for more information about this announcement.
You can no longer create Special Ad Audiences. Special Ad Audiences endpoints will be removed no later than December 31, 2022.
The following endpoints and fields are affected:

• GET /{ad-account-id}/customaudiences?fields=operation_status
• POST /{ad-account-id}/adsets?fields=subtype
• POST /{ad-account-id}/customaudiences?fields=subtype
• POST /{ad-campaign-id}?fields=subtype
• POST /{custom-audience-id}

Advantage Custom Audiences

Applies to v15.0+. Will apply to all versions on December 14, 2022.
When creating an ad set with any objective and with a non-data file custom audience in inclusion, Advantage custom audiences will be turned on by default.
When creating an ad set with a non-Advantage lookalike objective (that is, Value Optimization, Offsite Conversion, App Installs and Messages) with lookalike in inclusion, Advantage lookalike will be turned on by default.
Advantage custom audience and Advantage lookalike can be enabled or disabled through the targeting_relaxation_types targeting spec parameter. targeting_relaxation_types accepts either custom_audience and lookalike as a key, and if a value of 0 is passed, it will be disabled. If a value of 1 is passed, it will be enabled. If no key/value pair is passed, it will be considered as enabled.
The following endpoints and fields are affected:

• GET /{ad-account-id}/adsets
• POST /{ad-account-id}/adsets
• GET /{ad-set-id}?fields=targeting

Advantage Detailed Targeting

Applies to v15.0+. Will apply to all versions on December 14, 2022.
When creating an ad set with the Messages or App Installs optimization goals, Advantage lookalike and/or Advantage detailed targeting will be turned on by default and cannot be disabled.
When querying ad sets with the Messages or App Installs optimization goals that have Advantage detailed targeting and/or Advantage lookalike enabled, a targeting_optimization_types map will be returned with the detailed_targeting and lookalike properties indicating that the expansion is enabled. When querying delivery estimates for ad sets with the Messages or App Installs optimization goals, the targeting_optimization field will no longer be accepted and an error will be thrown.
For existing ad sets, you will be able to pass the targeting_optimization field.
The following endpoints are affected:

• GET /{ad-account-id}/adsets
• POST /{ad-account-id}/adsets
• GET /{ad-set-id}/delivery_estimate

Campaigns

Deprecated optimization type
Applies to v15.0+. Will apply to all versions on December 14, 2022.
Beginning September 15, 2022, advertisers will no longer be allowed to create incremental conversion optimization campaigns. Existing conversion optimization campaigns will behave normally.
The following endpoint is affected:

• POST /{ad_account_id}/campaigns

Custom Conversions

Applies to v15.0+.
We now require new Custom Conversions to contain at least one rule when they are created. Otherwise, campaigns should optimize on the event directly.
The following endpoint is affected:

• POST /{ad_account_id}/customconversions

Original source

Graph API

Released February 2, 2023 | Available until May 14, 2025 | Blog post
Comment, Photo, Post, Video
Applies to v16.0+. Will apply to all versions May 3, 2023.

The following fields on comments, photos, posts, and videos created on a user profile will now return an empty data set:

• comments
• message_tags
• reactions
• sharedposts
• story
• story_tags
• to
• via

Encryption

Applies to v16.0+. Will apply to all version May 3, 2023.
TLS versions older than 1.2 and static RSA cipher suites are no longer supported. See Encryption.

Messenger Platform

See the Messenger Platform changelog.

WhatsApp Business Platform

See the WhatsApp Business Platform changelog.

Marketing API

Released February 2, 2023 | Available until February 6, 2024 | Blog post

Ads Placement

Instant Articles

Applies to v16.0+. Will apply to all versions on April 20, 2023.
Advertisers will no longer be able to target the Instant Article placement for ads creation.
The following endpoints will be affected:

• GET /{ad-account-id}/adsets
• POST /{ad-account-id}/adsets
• GET /{ad-set-id}?fields=targeting

Travel Ads

Flight Ad Prospecting

Applies to v16.0+.
Prospecting is no longer an available audience option when creating a flight ad. New campaigns will only including retargeting audiences and require a data source.
The following endpoints and fields are affected:

• POST /{ad-account-id}/adsets

Trip Consideration

Applies to v16.0+.
The Reach Potential Travelers option is no longer available. System improvements will automatically prioritize delivery to Account Center accounts that may be planning travel. Campaigns are expected to achieve similar performance.
The following endpoints are affected:

• POST /{ad-account-id}/adsets

Original source

This changelog was updated with the following changes:

• September 19, 2023: Added User Accounts entry
• December 19, 2023: Moved Offline Conversions API information from Marketing API to Graph API
• February 6, 2024: Added affected endpoints for Ad Strategies

Graph API

Released May 23, 2023 | Available until September 12, 2025 | Blog Post

Instant Articles

As of April 20, 2023, the Instant Articles API no longer returns data. All Instant Articles API endpoints are not available on v17 or later and will be removed for all versions on August 21, 2023.

Offline Conversions API

Deprecation of Offline Conversions API

Applies to v17.0+.
Starting with Graph API v17.0, the Offline Conversions API will no longer support offline events. Graph API v16.0 is the last version that supports offline events. We anticipate that the Offline Conversions API will be discontinued in the third quarter of 2024.
In February 2023, we announced that the Conversions API now fully supports offline events. We recommend that advertisers use the Conversions API for new integrations. We recommend that advertisers with Offline Conversions API integrations convert their integration into a Conversions API integration before the third quarter of 2024 and not update their Offline Conversions API until they have successfully done so. Learn more about the Conversions API.
The following endpoint is affected:

• POST /{offline_event_set_id}/events

ThreatExchange

The /malware_analyses endpoint is deprecated. It is not available on v17 or later and will be removed for all versions on August 21, 2023.

User Accounts

This entry was added on September 19, 2023.
Applies to v17.0 and later versions. Will apply to all versions on September 15, 2023 (UPDATE: No longer applies to all versions. See September 15, 2023 out-of-cycle change.)
The GET /{user-id}/accounts (aka GET /me/accounts) endpoint no longer returns Facebook pages that have been linked to a Meta business account, unless the app user has granted the business_management permission to the app and has a role on the linked business account.

WhatsApp

See the WhatsApp Business Platform changelog.

Marketing API

Released May 23, 2023 | Available until May 14, 2024 | Blog Post
Marketing API version auto-upgrade will release on May 14, 2024.

Original source

Graph API

Released September 12, 2023 | Available until January 26, 2026 | Blog Post

Instagram Graph API

Deprecation of Media and User Insights

Applies to v18.0+. Will apply to all versions on December 11, 2023.
Duplicative and legacy Instagram insight metrics are being deprecated. Please see documentation for the endpoints and Instagram Insights for more information on which metrics to use in their place.
The following endpoints and metrics are affected:

• GET /{ig-user-id}/insights
  • AUDIENCE_GENDER_AGE
  • AUDIENCE_LOCALE
  • AUDIENCE_COUNTRY
  • AUDIENCE_CITY
• GET /{ig-media-id}/insights
  • CAROUSEL_ALBUM_IMPRESSIONS
  • CAROUSEL_ALBUM_REACH
  • CAROUSEL_ALBUM_ENGAGEMENT
  • CAROUSEL_ALBUM_SAVED
  • CAROUSEL_ALBUM_VIDEO_VIEWS
  • TAPS_FORWARD
  • TAPS_BACK
  • EXITS
  • ENGAGEMENT
    Note: total_interactions, which is listed as an alternative for some of the deprecated metrics, is currently only available using version 18.0 and does not work with older versions. When querying older versions before Dec 11, 2023, please use the engagement metric.

Server-Sent Events

Server-Sent Events are deprecated and will be removed December 31, 2023.

WhatsApp

See the WhatsApp Business Platform changelog.

Marketing API

Released September 12, 2023 | Available until August 13, 2024 | Blog Post

Catalog API

Credit Cards

Applies to v18.0+.
The {ad-account-id}/credit_cards endpoint is no longer supported.

Reach and Frequency

Reach and Frequency Campaigns

Applies to v18.0+.

Objective

• Target frequency can now be used for REACH and VIDEO_VIEWS objectives in reach and frequency campaigns.
• The objective parameter will no longer accept TRAFFIC unless the rf_prediction_id_to_share parameter is set to a valid prediction ID.

Optimizations

• Reach and frequency campaigns can now use the REACH optimization.
• The optimization_goal parameter will no longer accept POST_ENGAGEMENT or LINK_CLICKS unless the rf_prediction_id_to_share parameter is set to a valid prediction ID.
• The frequency_cap parameter will no longer accept any value greater than 0 if the optimization_goal parameter is set to AD_RECALL_LIFT. AD_RECALL_LIFT predictions will be generated without applying any frequency cap.

The following endpoints are affected:

• POST /act_{ad-account-id}/reachfrequencypredictions

Targeting Location Targeting

Applies to v18.0+. Will apply to all versions December 11, 2023.
When no location_types is sent in the API call, it will default to ['home', 'recent'].
The following endpoints are affected:

• GET /act_{ad-account-id}/reachestimate
• GET /act_{ad-account-id}/delivery_estimate
• POST /act_{ad-account-id}/adsets
• POST /{adset-id}

Location Targeting Deprecation

Applies to v18.0+.
All options other than ['home','recent'] will be deprecated for location_types. Trying to use any options other than ['home', 'recent'] will result in an error.
The following endpoints are affected:

• GET /act_{ad-account-id}/reachestimate
• GET /act_{ad-account-id}/delivery_estimate
• POST /act_{ad-account-id}/saved_audiences
• POST /act_{ad-account-id}/adsets
• POST /{adset-id}
• POST /{saved-audience-id}

Original source

Graph API

Released January 23, 2024 | Available until May 21, 2026 | Blog Post

Groups API

Applies to v19.0. Will apply to all versions April 22, 2024.
Deprecated the following Groups API permissions and features:

• publish_to_groups
• groups_access_member_info
• Groups API
  You can verify if a given Groups API endpoint requires one of these permissions or features by making a version 19 request on the endpoint (https://graph.facebook.com/v19.0/...).
  In addition, we have deprecated the ability for group admins to install apps on the group, even if they have an admin or developer role on the app.
  These permissions, features, and abilities will be removed April 22, 2024.

WhatsApp Flows

See WhatsApp Flows changelog.

Marketing API

Released January 23, 2024 | Available until February 4, 2025 | Blog Post

Insights Ads Insights

Applies to v19.0+.

• The age_targeting, gender_targeting, labels, and location insights metrics will no longer be available.
• The estimated_ad_recall_rate_lower_bound, estimated_ad_recall_rate_upper_bound, estimated_ad_recallers_lower_bound, and estimated_ad_recallers_upper_bound insights metrics will no longer be available.
  The following endpoints are affected:
• GET /{ad-set-id}/insights
• GET /{ad-account-id}/insights
• GET /{ad-id}/insights
• GET /{campaign-id}/insights
• POST /{ad-set-id}/insights
• POST /{ad-account-id}/insights
• POST /{ad-id}/insights
• POST /{campaign-id}/insights

Objectives Ad Copies

Applies to v19.0+.
When creating a copy of an ad you must only use Outcome-Driven Ad Experience objectives. Attempting to use legacy objectives will result in an error.
The following endpoints are affected:

• POST /{adgroup-id}/copies
• POST /{ad-campaign-id}/copies
• POST /{ad-campaign-group-id}/copies

Targeting

####### Target Expansion

Applies to v19.0+. Will apply to all versions on April 22, 2024.

• The targeting_optimization field will not be accepted for campaigns that are optimized for link clicks or landing page views. This also applies to previous optimizations that were included in Advantage Detailed Targeting with no option to opt-out including conversions, value, app installs, app events and conversations.
• For all optimizations that are opted into Advantage Detailed Targeting with no option to opt-out we will automatically set the targeting_as_signal field to either 1 or 3 based on the set of objectives and optimizations.
• The targeting_as_signal field should be either null or 0 for campaigns that are optimized for impressions, video views, reach, engagement, ad recall lift or lead, otherwise an error will be received.
  The following endpoints are affected:
• POST /act_{ad-account-id}/adsets
• POST /{adset-id}
• GET /{adset-id}/delivery_estimate
• GET /act_{ad-account-id}/delivery_estimate

Original source