Home
Blog
Introducing Graph API v22.0 and Marketing API v22.0

January 21, 2025

Introducing Graph API v22.0 and Marketing API v22.0

By Ayyad Farah

Today, we are releasing Graph API v22.0 and Marketing API v22.0. As part of this release, we are highlighting changes below that we believe are relevant to parts of our developer community. These changes include announcements, product updates, and notifications on deprecations on relevant application(s) integrations with our platform.

For a complete list of all changes and their details, please visit our changelog.

General Updates

Marketing API v22 changes to the use of customer list custom audiences in housing, employment, and financial products and services (including credit) campaigns

Applies to ‘v22.0+’ and will rollout to all versions in March 2025

Certain customer list custom audiences will become ineligible for usage of housing, employment, and financial products and services (including credit) campaigns. Learn more about the update here and whether the restrictions apply to you. Additionally, the field is_sac_cfca_terms_certified will be added to the ad set level, see example. You will be required to use this field to certify that any customer list custom audiences being used in an Ad Set of housing, employment, and financial products and services (including credit) campaigns comply with Meta’s CLCA certification. Starting early April 2025, existing campaigns/ad sets using customer list custom audiences which do not follow the requirements may be paused. If this happens, you will see errors in Ads Manager and the Marketing API with instructions.

The following endpoints will be affected:

Custom Audience API v22

Starting on January 6, 2025, you can use the new is_eligible_for_sac_campaigns field to identify whether a custom audience can be used in ad sets of Special Ad Category campaigns. You must provide the intended special_ad_categories and special_ad_category_countries of the Special Ad Category campaign going to use the audience, as well as the ad_account_id which will use the audience to create or edit the ad set.

The following endpoints will be affected:

Reach People Interested In Your Selected Cities And Regions

We’re excited to share the launch of a new feature for location targeting that helps advertisers drive increased performance by expanding beyond your target cities or regions, giving our ads system the flexibility to deliver ads to people who have shown interest in a location.

This feature expands upon our existing location targeting feature, by enabling you to reach people who have shown intent to travel to, make purchases in, or general interest in the cities and regions you're targeting, within the same country.

During testing, clients who used the new location targeting feature saw a 6.7% decrease in cost per result.

For more information please click here.

Deprecations & Breaking Changes

Replacing Instagram User, Instagram Media, Instagram Carousel, and Instagram Comment endpoints with IG User, IG Media, and IG Comment endpoints

We’re making changes to the Instagram Graph API and the Marketing API to make it easier for developers to build solutions for businesses. With these changes, we are deprecating the Instagram User, Instagram Media, Instagram Carousel, and Instagram Comment objects in Graph API v22 in favor of the existing IG User, IG Media which includes carousels, and IG Comment objects. We’ve also added functionality to these newer objects to provide parity for most use cases.

Developers will have until January 21, 2026 to update their usage of impacted Marketing API endpoints and until April 21, 2025 to update their usage of impacted Graph API endpoints. If you are automatically updating your Graph API versions in your API calls, we recommend you review these changes as they apply immediately for developers using Graph API v22.

See the developer blog for more details about this change including which endpoints are changing, which use cases are no longer supported, and what timeline applies.

Removal of Detailed Targeting exclusions

As part of our continued efforts to help advertisers drive performance, we are removing Detailed Targeting exclusions. As part of this process, we will continue to support the ability to exclude your employers within Audience controls at the account level. For more information on account controls please see here.

We believe this change will help improve campaign performance. An advertiser test showed that the median Cost per Conversion was 22.6% lower when not using Detailed Targeting Exclusions vs using Detailed Targeting Exclusions.

As a result of this change, custom audiences will be deprecated within the exclusions field. You can still continue using custom audience exclusions by using the excluded_custom_audiences field instead.

Beginning January 21, 2025 developers can start to implement the code changes, and will have until April 21, 2025 to make these updates. This change will be released in v22. Please refer to the developer blog for a list of impacted endpoints related to this change.

Deprecate Standard Enhancements Bundle from the Marketing API

Marketing API v22.0 Impacts to Advantage+ Creative Enhancements

In this new Marketing API version, we will deprecate the Advantage+Creative Standard Enhancements bundle, replacing it with individual creative enhancements opt-in. You can learn more about Advantage+ Creative here.

Here you can learn more information that is relevant to the developer community, and additional details can be found in our developer documentation here.

Standard enhancements will no longer be supported with these endpoints:

  • POST /{ad_account_id}/adcreatives
  • POST /{ad_account_id}/ads
  • GET /{ad_id}/previews

Introducing the Instagram Views Metric and Deprecation for Impressions and Plays Metrics

To continue aligning the functionality of Instagram API with that of the Instagram app, we are introducing the `views` metric on all API versions for both media and user insights. For media insights, Feed, Story and Reels objects will return views. For user insights, the API will support the `views` metric with multi-dimensional breakdowns for follower type and media product type.

In addition, the following metrics will be deprecated starting in v22:

  • plays (media insights): Number of times the reels start to play after an impression is already counted.
  • clips_replays_count (media insights): The number of times your reel starts to play again after an initial play of your reel. This is defined as replays of 1ms or more in the same reel session.
  • ig_reels_aggregated_all_plays_count (media insights): The number of times your reel starts to play or replay after an impression is already counted.
  • impressions (media & user insights): Total number of times the Instagram Media object has been seen.

The media insights `impressions` metric will only be deprecated for media created on or after July 2, 2024. For media created before this date, the API will continue to return values as usual across all versions.

More information can be found in our developer documentation for Instagram User Insights and Instagram Media Insights. Please encourage your developers to make updates by April 21, 2025 to avoid issues.

Meta Business SDK

Meta Business SDK v22 Release

The Meta Business SDK v22 release will be published shortly after the release of Graph API v22. This release will include bug fixes, dependency upgrades, new features, and most importantly, an updated API interface to match Graph API v22.

In this release, we also aim to provide sample code for additional scenarios. These files are available in all five languages and cover more than 30 scenarios. We hope this will greatly enhance the onboarding experience while offering richer guidance to support your integration with the Business SDK.

As part of our 2-year deprecation schedule for Platform SDKs, please note the upcoming deprecations and sunsets:

  • May 2025: Facebook Platform SDK v17.0 or below will be deprecated.

API Version Deprecations:

As part of Facebook’s versioning schedule for Graph API and Marketing API, please note the upcoming deprecations:

Graph API

  • May 14, 2025: Graph API v.16 will be deprecated and removed from the platform
  • September 12, 2025: Graph API v.17 will be deprecated and removed from the platform

Marketing API

  • Feb 4, 2025: Marketing API v19.0 will be deprecated and removed from the platform
  • May 6, 2025: Marketing API v20.0 will be deprecated and removed from the platform

To avoid disruption to business, we recommend migrating all calls to the latest API version that launched today.


Get our newsletter

Sign up for monthly updates from Meta for Developers.

Sign up