Facebook Marketing API Release Notes

Marketing API

October 8, 2025 | Available until TBD | Blog

Ad Creative

Website destination optimization

Applies to v24.0+.
When you optimize your website destination, you allow Meta to determine which landing page on your website to send a customer to based on which URL we believe is most likely to result in a conversion. Using Optimize website destination means we may direct a customer to a page on your website that's most relevant to them, like your homepage, product page, collection page or another page on your website depending on where they're likely to convert.
The following endpoints are affected:

• POST /{ad-account-id}/adcreatives
• GET /{ad-creative-id}/?fields=destination_spec

Ads that Click to Messenger

Messenger ads for leads deprecation
Applies to v24.0+.
The ability to create lead ads that generate leads in Messenger with the API is being deprecated. You will still be able to create Messenger ads for leads using Ads Manager.
The following endpoints are affected:

• POST /{page-id}/messenger_lead_forms
• POST /{ad-account-id}/adcreatives
• GET /{messenger-lead-gen-template-id}

Advantage+ Campaigns

Advantage+ shopping campaigns and Advantage+ app campaigns deprecation
Applies to v24.0+.
We are introducing a new, unified, and streamlined process for creating campaigns that will replace the existing workflows.
Beginning with v24.0, creation, duplication, and updates to Advantage+ shopping campaigns and Advantage+ app campaigns will no longer be allowed.
Refer to the Advantage+ Campaigns documentation to learn how to migrate your campaigns, or create new Advantage+ campaigns to avoid disruption.
The following endpoints are affected:

• POST /{ad-account-id}/campaigns
• POST /{campaign-id}/copies

Audiences

Customer file custom audiences

Applies to v24.0+. Will apply to all versions January 6, 2026.
Updating customer file custom audiences that are flagged custom audiences will fail. Creating and updating lookalike audiences using flagged seed audiences will fail.
More information on this update and how to resolve flagged custom audiences can be found here.
The following endopints are affected:

• POST {ad-account-id}/customaudiences
• GET {custom-audience-id}
• POST {custom-audience-id}
• POST {custom-audience-id}/users
• POST {custom-audience-id}/usersreplace
• DELETE {custom-audience-id}/users

Lookalike audience field type enforcement

Applies to v24.0+. Will apply to all versions January 6, 2026.
When creating new lookalike audiences, the lookalike_spec field is now required to match the valid types. Requests with a lookalike_spec field containing invalid subfields may fail to create a new lookalike audience.
The following endpoints are affected:

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

Budgeting

Ad set budget sharing field conditionally required

Applies to v24.0+.
Ad set budget sharing allows you to share up to 20% of your budget with other ad sets in the same campaign. This is designed to improve performance for campaigns that are not using a campaign budget.
Beginning with v24.0, the is_adset_budget_sharing_enabled field is now required if you are planning to set a budget at the ad set level. Setting it to true is recommended in order to turn on this optimization.
The following endpoints are affected:

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

Increasing daily budget flexibility

Applies to v24.0+.
Daily budget flexibility is increasing from 25% to 75%. This means up to 75% over your daily budget may be spent on days when better opportunities are available, and less on others.
Your daily budget is used as an average over a seven-day calendar week from Sunday through Saturday. Your weekly spend will not change, and will not be greater than 7 times your daily budget.
The following endpoints are affected:

• POST /{ad-account-id}/adsets
• POST /{ad-account-id}/campaigns
• POST /ad-set-id
• POST /{campaign-id}

Conversions

Custom conversions

Applies to v24.0+. Will apply to all versions January 6, 2026.
Updating custom conversions that are flagged custom conversions will fail.
More information on this update and how to resolve flagged custom conversions can be found here.
The following endpoint is affected:

• POST /{custom-conversion-id}

Campaigns

Campaign restrictions for custom conversions and audiences

Applies to v24.0+. Will apply to all versions January 6, 2026.
Creating and updating campaigns that are using flagged custom conversions or audiences will fail.
More information on this update and how to resolve flagged custom conversions and audiences can be found here.
The following endpoints are affected:

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

Catalog

New batch API payload request limit

Applies to v24.0+.
We’ve added a new limit to the size of request payloads for the Catalog Items Batch API. Starting with v24.0, payload requests will be limited to 30 MB. Note that in terms of the number of items per request, the current limit of 5,000 items remains unchanged.
The following endpoint is affected:

• POST /{product-catalog-id}/items_batch

Product Item endpoint supports allow_upsert

Product Item endpoint supports allow_upsert
Applies to v24.0+.
The allow_upsert flag is now supported for the Product Item POST endpoint. That means users can now not only create product items using the Product Item POST endpoint, but also update existing items.
The following endpoint is affected:

• POST /{product-catalog-id}/products

Placements

Advantage+ placements limited spend

Applies to v24.0+.
This update allows you to allocate up to 5% of your spend to specific placements you would otherwise exclude when it's likely to improve performance.
During ad set creation, you can now apply a limited spend using the new placement_soft_opt_out parameter. There is no change in how placements are fully opted out with Placement Targeting.
Note: This feature works with the Sales and Leads objectives.
The following endpoints are affected:

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

Facebook video feeds ads placement deprecation

Applies to v24.0+.
Delivery of Facebook video feeds ad placements will be stopped and campaign spending will be shifted to other placements automatically. Attempting to create or update an ad campaign with the Facebook video feeds ad placement will produce an error.
The Facebook Reels placement is the recommended replacement.
The following endpoints are affected:

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

Targeting

Detailed targeting

Applies to v24.0+. Will apply to all versions January 6, 2026.
We are combining some of the interests currently available in Detailed Targeting into relevant groupings.
Certain detailed targeting interest options will not be supported for new campaigns. When creating new or updating existing campaigns with affected interest options, you will encounter an error preventing you from publishing your changes. If an interest option has been combined, the search results will show the new, consolidated option.
Ad campaigns created before October 8, 2025 can continue to run, but will stop being delivered by January 15, 2026, unless removed or updated with suggested combined options.
Beginning October 8, 2025, duplicated campaigns using the affected interest options will automatically be replaced with suggested combined options for Marketing API v24.0 calls.
The following endpoints are affected:

• POST /{ad-account-id}/adsets
• POST /{ad-set-id}
• POST /{ad-set-id}/copies
• GET /{ad-account-id}/delivery_estimate
• GET /{ad-set-id}/delivery_estimate
• GET /{ad-account-id}/reachestimate
• GET /{ad-account-id}/targetingsearch
• GET /{ad-account-id}/targetingsuggestions
• GET /{ad-account-id}/targetingvalidation
• GET /search

Original source Report a problem

Marketing API

May 29, 2025 | Available until June 9, 2026 | Blog

Ad Campaigns

Advantage+ Shopping Campaigns and Advantage+ App Campaigns
Applies to v23.0.+ Will apply to all versions with the release of v25.0.
The advantage_state field in advantage_state_info is a read-only field that indicates if a campaign has reached an optimal level of automation. Beginning with v25.0, the smart_promotion_type field will no longer be available for creating ad campaigns.
The following endpoints are affected:

• GET /{ad-campaign-id}
• GET /{ad-account-id}/campaigns

Audiences

Advanced Targeting

Applies to v23.0+.
Age range and gender settings can now be used as suggestions in ad sets using individual_setting's age and gender parameters inside targeting_automation.
Note: When using suggestions, your ads will reach people outside of the setting when it's likely to improve performance of the ads.
The following endpoints are affected:

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

Advantage+ Audience

Applies to v23.0+.
Ad sets are now opted-in to Advantage+ audience by default if you're using the default or relaxed setup. You can opt-out in the audience settings when creating or updating an ad set.
This behavior applies only when creating a new ad set; updating an existing ad set will not exhibit this behavior on any version.
The following endpoints are affected:

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

Bidding

Reservation

Applies to v23.0+.
Beginning with v23.0, the instagram_destination_id field will return the ig_user_id rather than the instagram_actor_id. The instagram_actor_id is also no longer supported in the destination_ids parameter; update your API calls to use the ig_user_id instead.
The following endpoints are affected:

• GET /{rf-prediction-id}
• GET /{ad-account-id}/reachfrequencypredictions
• POST /{ad-account-id}/reachfrequencypredictions

Product Item

Videos

Applies to v23.0+.
The videos field has been added to allow for querying of the properties of videos associated with product items.
The following endpoints are affected:

• GET /{product-item-id}

Special Ad Catagories

Ad Sets for Special Ad Category Campaigns

Applies to v23.0. Will Apply to all versions August 27, 2025.
The is_sac_cfca_terms_certified field should no longer be added to an ad set as the rollout of these requirements will not proceed.
The following endpoints are affected:

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

Custom Audiences

Applies to v23.0. Will Apply to all versions August 27, 2025.
The is_eligible_for_sac_campaigns field should no longer be added to an ad set as the rollout of these requirements will not proceed.
The following endpoints are affected:

• GET /{custom_audience_id}

Original source Report a problem

Marketing API

January 21, 2025 | Available until February 10, 2026 | Blog

Ad Creatives

Applies to v22.0+. Will apply to all versions September 9, 2025.

Field Deprecations

The instagram_actor_id field for the following endpoints is deprecated:

• POST /{ad-account-id}/adcreatives
• POST /{ad-account-id}/ads
• POST /{ads-id}
• POST /{ad-account-id}/asyncadrequestsets
• GET /{ad-account_id}/generatepreviews
• GET /generatepreviews
• GET /adcreative
• GET /adcreative/object_story_spec

Please migrate your API calls to use the new instagram_user_id field.
The effective_instagram_story_id field has been deprecated for the GET /adcreative endpoint. Use the effective_instagram_media_id field instead.
The instagram_story_id field has been deprecated for the GET /adcreative endpoint. Use the source_instagram_media_id field instead.

Advantage+ Creative

Standard Enhancements

Applies to v22.0+.
Opting ads in to and previewing ads using the STANDARD_ENHANCEMENTS bundle is no longer supported.
The following endpoints are affected:

• POST /{ad-account-id}/adcreatives
• POST /{ad-account-id}/ads
• GET /{ad-id}/previews
• GET /{ad-account-id}/generatepreviews

Asset Feed Spec

Segment Asset Customization

Applies to v22.0+.
Segment Asset Customization is no longer supported.

Audiences

Detailed Targeting - Employer Exclusions

Applies to all versions.
An employer exclusion can now be created at the ad account level, which will be applied to all active campaigns.
The following endpoints are affected:

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

Detailed Targeting - Exclusions

Applies to v22.0+. Will apply to all versions April 21, 2025.

• When creating or updating an ad set, an error message will be shown when adding any new detailed targeting exclusions that are not within audience control exclusions at the account level.
• When duplicating an ad set, detailed targeting exclusions (except audience control exclusions at the account level) will be removed in the new campaign.
• When trying to get a delivery estimate, only employer exclusions will be allowed for detailed targeting.
  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. For more details see Advanced Targeting: Custom Audiences.
  The following endpoints are affected:
• POST /{ad-account-id}/adsets
• POST /{adset-id}
• POST /{adset-id}/copies
• GET /{ad-account-id}/delivery_estimate

Reach People Interested in Selected Cities and Regions

Applies to v22.0+.
Expands location targeting beyond an ad campaign's target cities or regions to deliver ads to people who have shown interest in a location.
The following endpoints are affected:

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

Commerce Platform

Promotions API – field deprecation

Applies to v22.0+.
The promotions field has been deprecated and replaced by the promotion_details field. Please discontinue using the promotions field, as it does not contain complete information. Please migrate your API calls to the new promotion_details field.
The following endpoint is affected:

• GET /{commerce-order-id}/promotion_details

Instagram Endpoints

Applies to v22.0+. Will apply to all versions April 21, 2025.
The Instagram endpoints supported by the Marketing API have been deprecated.
The following endpoints are affected:

• DELETE /{instagram-comment-id}
• GET /{instagram-carousel-id}
• GET /{instagram-carousel-id}/comments
• GET /{instagram-comment-id}
• GET /{instagram-comment-id}/replies
• GET /{instagram-media-id}
• GET /{instagram-media-id}/comments
• GET /{instagram-user-id}
• GET /{instagram-user-id}/agencies
• GET /{instagram-user-id}/ar_effects
• GET /{instagram-user-id}/authorized_adaccounts
• GET /{instagram-user-id}/upcoming_events
• POST /{instagram-user-id}/authorized_adaccounts
• POST /{instagram-carousel-id}/comments
• POST /{instagram-comment-id}
• POST /{instagram-comment-id}/replies
• POST /{instagram-media-id}
• POST /{instagram-user-id}/upcoming_events

Please migrate your API calls to use the following Instagram Platform endpoints:

• IG User
• IG Media
• IG Media Children
• IG Comment
• IG Comment Replies

Special Ad Categories

We are providing an update regarding the previously considered restrictions on customer list custom audiences (CLCAs) for advertisers offering housing, employment, and financial products and services in or targeting audiences in the United States.
The rollout of these previously announced restrictions will not proceed.
Certain customer list custom audiences will become ineligible for usage in ad sets of housing, employment, and financial products and services, including credit, campaigns beginning March 2025. Learn more about the update here and whether the restrictions apply to you.

Ad Sets for Special Ad Category Campaigns

Applies to v22.0+. Will apply to all versions March 2025.
Starting with v22.0, you will be unable to create or update ad sets if their targeting options contain one or more ineligible customer list custom audiences. You will need to either certify if eligible or remove any such audiences to successfully create or update the ad set. 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 is_sac_cfca_terms_certified field will be added to the ad set API. You will be required to use this field to certify that any customer list custom audiences being used in an ad set of a housing, employment, and financial products and services, including credit, campaign comply with Meta’s CLCA certification.
This change affects the following endpoints when creating or updating ad sets:

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

Custom Audiences

Applies to all versions.
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 using the audience, as well as the ad_account_id which will use the audience to create or edit the ad set.
This change affects the following endpoints:

• GET /{custom-audience-id}

See Special Ad Categories for more information about these changes.

Original source Report a problem

Marketing API

October 2, 2024 | Available until September 9, 2025 | Blog post

Objectives

Outcome-Driven Ad Experiences

Applies to v21.0+.

Beginning with v21.0, you will no longer be able to create new ad sets or ads with non-Outcome-Driven Ad Experience (ODAX) objectives. Existing ad campaigns using older objectives can continue to run for now, but we encourage you to transition all your campaigns to the ODAX objectives. See the Simplifying campaign objectives with Outcome-Driven Ad Experiences blog entry and the Outcome-Driven Ad Experiences documentation for more information.

The following endpoints are affected:

• POST /{ad_account_id}/campaigns
• POST /{ad_account_id}/ads
• POST /{ad_account_id}/adsets
• POST /{campaign_id}
• POST /{ad_group_id}

Standard Enhancements

Image Expansion

Applies to v21.0+.

For single media ads, the Image Expansion feature will be included as part of Standard Enhancements. Therefore, if creating an ad or an ad creative opted-in to Image Expansion, please refer to this link for instructions to set standard_enhancements as a field inside the creative_features_spec.

The following endpoints are affected:

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

Version 22 Upcoming Change

Product Catalog — Enforcing Country Override Specific Fields

Applies to v22.0

This change applies to advertisers using country and language feeds to localize their product data. It standardizes which fields should be provided in a country feed versus a language feed (or a country and language feed via API) to help advertisers set up their product data in the most efficient way.

Price, sale price, unit price, base price, status (visibility), and availability must now only be provided in a country feed. This helps ensure customers see the correct localized product data.

If your language feed currently contains the price, sale_price, base_price, status, or availability fields, move them to your country feed before the Graph API v22.0 release in Q1 2025 to ensure that the localized data continues to be uploaded to your products past this date.

The following endpoints are affected:

• POST /{product-catalog-id}/localized_items_batch

Original source Report a problem

Marketing API

May 21, 2024 | Available until May 6, 2025 | Blog post

Instagram Graph API

Instagram User Insights

Applies to v20.0+. Will apply to all versions on August 19, 2024.
The last_14_days, last_30_days, last_90_days, and prev_month timeframes will no longer be supported for the reached_audience_demographics and engaged_audience_demographics metrics.
The following endpoints and metrics are affected:

• GET /{ig-user-id}/insights
  • engaged_audience_demographics
  • reached_audience_demographics

Auction Ads

Campaign Optimization of Impressions

Applies to v20.0+. Will apply to all versions August 19, 2024.
The optimization_goal parameter will no longer accept the impressions value in combination with:

• The legacy POST_ENGAGEMENT objective
• The ON_POST destination_type
  Note: Optimizing for reach is still available.
  The following endpoints are affected:
• POST /{ad-account-id}/adsets

Frequency Controls

Applies to v20.0+. Will apply to all versions August 19, 2024.
The frequency_control_specs parameter should no longer be sent in an API call if the optimization_goal is set to Ad Recall Lift, Link Click Optimization, Post Engagement, or 2-second Video Views. Any campaigns of this type that are still running will be disabled beginning August 19, 2024.
Writes to this field are only available in ad sets where REACH and THRUPLAY are the performance goal.
The following endpoints are affected:

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

Offline Conversions API

Deprecation of Remaining Endpoints

Applies to v20.0+.
The Offline Conversions API will be discontinued in May 2025. It was previously due to be deprecated in the third quarter of 2024. As we announced in the v17.0 changelog, the Offline Conversions API no longer supports offline events. Graph API v16.0 is the last version that supports offline events. The Offline Conversions API will be discontinued when v16.0 expires in May 2025.
Between now and May 2025, we will be deprecating the remaining Offline Conversions API endpoints on Marketing API v20.0.
The following endpoints are affected:

• POST/GET/DELETE /{offline_event_set_id}
• POST/GET /{offline_event_set_id}/uploads
• POST /{offline_event_set_id}/validate
• POST /{offline_event_set_id}/ad_account
• GET /{offline_event_set_id}/stats
• GET /{offline_event_set_id}/shared_agencies
• POST/GET /{offline_event_set_id}/agencies
• GET /{offline_event_set_id}/adaccounts
• GET /{offline_event_set_id}/customconversions
• GET /{offline_event_set_id}/audiences
• GET /{offline_event_set_id}/shared_accounts
• GET /{ad_account_id}/offline_conversion_data_sets
• POST/GET /{business_id}/offline_conversion_data_sets
• POST/GET/DELETE /{business_asset_group_id}/contained_offline_conversion_data_sets
  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 May 2025 and not update their Offline Conversions API until they have successfully done so. Learn more about the Conversions API.

Messaging Ads

Sponsored Messages

Applies to v20.0+. Will apply to all versions August 19, 2024.
Creation of the sponsored messages ad type will no longer be available. This change will not affect other messaging ads ad types.
The following endpoints are affected:

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

Original source Report a problem

Marketing API

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 Report a problem

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 Report a problem