Introducing Graph API v23.0 and Marketing API v23.0

Here are the highlights of the new GAPI/MAPI changes below for V23. Please visit our changelog for a complete list of changes and details.

General Updates

Insights GraphAPI: Introducing the Content Monetization Earnings metric for Creators

We are introducing a new insights metric, content_monetization_earnings,for Creators onboarded to Content Monetization. This new metric displays their earnings at a page or post level over a customizable time period. For page level earnings, an additional breakdown is available for the content types that contributed to the overall earnings.

The metric, content_monetization_earnings represents the money you may have earned from content monetization. The final amount may differ, depending on content reviews, reporting data and copyright claims.

Approximate earnings are based on the following and solely determined by Meta:

• Qualified views for eligible public videos.
• Total plays for eligible public reels.
• Views on eligible public stories.
• Reach, comments, reactions and shares for all of your other eligible public posts excluding Stories.

New Endpoints:

• POST /{page_id}/content_monetization_earnings
• POST /{page_id}_{asset_id}/content_monetization_earnings

Graph API: Increasing daily budget flexibility

We are gradually introducing greater daily budget flexibility to some Meta Ads Manager accounts. This means on days when better opportunities are available for you, we may spend up to 75% over your daily budget on some days and less on others. On a weekly basis, we won’t spend more than 7 times your daily budget. If your campaign is less than 7 days, the total spend will not exceed your daily budget, multiplied by the campaign duration.

Key Updates:

• We are increasing daily budget flexibility from 25% to 75%. This means we may spend up to 75% over your daily budget on days when better opportunities are available, and less on others.
• Your daily budget is used as an average over the 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.

Updating existing endpoints:

• POST /act_{ad_account_id}/adsets
• POST /act_{ad_account_id}/campaigns
• POST /{ad_set_id}/
• POST /{campaign_id}/

Insights Graph API: Introducing the Monetization Approximate Earnings Metric for Creators

We are introducing a `monetization_approximate_earnings` metric for both page and content earnings. If you are a Creator, you can use this new metric to view your earnings from these revenue sources, excluding Bonuses.

Your actual payout may be higher or lower due to pending reviews, content ownership claims or other adjustments.

This endpoint also provides optional breakdown for earning from each monetization tool.

New Endpoints:

• POST /{page_id}/monetization_approximate_earnings
• POST /{page_id}_{asset_id}/monetization_approximate_earnings

Advantage+ Campaign Experience for Sales and App

Now, instead of having to select between running an Advantage+ shopping campaign (ASC) or a manual campaign, advertisers have the option to now leverage the performance of Advantage+ with the complete range of ad features to meet specific business goals, all in one experience. This will also be the case for Advantage+ app campaigns (AAC) and manual app campaigns. We have also introduced a new indicator that will signal if the sales and app campaigns are Advantage+ ON, which will be reflected in the field advantage_state set to a value other than DISABLED.

Affected API Endpoints (api reference)

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

Age and Gender Automation with Individual Settings

Meta’s Marketing API now offers a powerful feature that allows advertisers to set age and gender as suggestions, unlocking relaxation and automation benefits. This is available only for OUCTOME_SALES and APP_INSTALLS objectives. As of now this feature will only be available to selected advertisers but will be gradually rolled out to all advertisers in the coming months. This enhancement builds upon the existing age and gender feature, enabling your ads to reach people outside that setting when it’s likely to improve performance.

Affected API Endpoints (api reference)

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

Marketing API Changes to Advantage+ audience behaviours

Changes to Advantage+ audience behaviours.

• Prior to API version V23.0, the advantage_audience parameter within targeting_automation was optional and wasn’t explicitly required to be set in the targeting spec when creating a new ad set or updating an existing one.
• Starting from API version V23.0, the advantage_audience parameter within targeting_automation will automatically default to 1 (for fully default or relaxed setup of audience) or require explicit setting to either 1 or 0 in the spec (for constrained audience setup). This behavior applies only when creating a new ad set; updating an existing ad set will not exhibit this behavior on any version.

Affected API Endpoints (api reference)

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

New ‘videos’ field added to Catalog’s Product Item Graph API

The new videos field in Catalog’s Product Item Graph API provides an easy way for advertisers to view the properties of videos added by them to product items for use in Meta Catalogs. This allows advertisers to confirm that Meta has correctly received the videos as uploaded and the properties of the video are as expected, so that they can be used in ads right away.

The `videos` field will be available for all products as soon as they are ingested by Meta. This is an improvement over the existing `video_metadata_properties field`, which is only populated after Meta has performed a fetch and may not be performed for all products.

Introducing Version 3 for Embedded Signup

We are introducing versioning cadence to Embedded Signup that will align with Graph API, beginning with version 3. Version availability is not exclusive and will be giving partners sufficient time to move to the latest version.

Version 3 will be released on May 29th. More details about the changes we’re introducing for version 3 and version 2’s deprecation timeline can be found in the “versioning” section within the Embedded Signup documentation.

Graph API: Updating Error Codes for Cloud API and MM Lite Endpoints

We are improving the business experience on Cloud API and MM Lite API by providing more actionable and specific error codes and messages for commonly used scenarios, enabling businesses to troubleshoot and resolve issues more efficiently.

Key Updates:

• Cloud API & MM Lite joint error code updates:
  • Template parameter errors: We've introduced a new error code (132018) specifically for when there’s an issue with the parameters in your template message. Issues caused by invalid HSM parameters when using the Cloud API and MM Lite endpoint.
• MM Lite Error Codes updates: We're introducing a new range of error codes starting with "1341xx" for MM Lite API. These codes come with descriptive error messages to help you understand the reason for failure, providing greater clarity and accuracy for error scenarios previously bundled under:
  • "131009” - Parameter value is not valid
  • “131055” - Method not allowed

Updating existing endpoints:

• Cloud API Endpoint: POST /<BUSINESS_PHONE_NUMBER_ID>/messages
• MM Lite Endpoint: POST /<BUSINESS_PHONE_NUMBER_ID>/marketing_messages

Deprecations & Breaking Changes

Marketing API: Replacing Instagram User with IG User in Reachfrequencypredictions

We are making changes to Reservations in the Marketing API to make it easier for developers to build solutions for businesses. We are deprecating the legacy Instagram account ID from POST and GET endpoints, and introducing support for IG User ID.

Key Updates:

• POST /{ad_account_id}/reachfrequencypredictions
  • Starting from v23 onwards, instagram_actor_id is no longer supported in parameter destination_ids. Use ig_user_id instead.
  • The API user will receive an Instagram destination ID error if the input destination id contains an instagram_actor_id as destination_id in destination_ids field.
• GET /<rf_prediction_id>
  • instagram_destination_id fieldnow returns ig_user_id instead of instagram_actor_id for 23 onwards.
• GET /{ad_account_id}/reachfrequencypredictions
  • instagram_destination_id fieldnow returns ig_user_id instead of instagram_actor_id from v23 onwards.

Reference:

• Guide on creating a Reservation campaign
• Guide on generating a Reservation prediction
• Developer docs: Ad Account Reachfrequencypredictions

Marketing API: Ad Sets for Special Ad Category Campaigns

Ad Sets for Special Ad Category Campaigns

Beginning May 2025, this change will be applied to all versions.

The field is_sac_cfca_terms_certified should no longer be added to an ad set as the rollout of these requirements remains delayed.

This change affects the following endpoints and the field should be removed when creating or updating ad sets:

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

Custom Audiences

Applies to all versions

The field is_eligible_for_sac_campaigns should no longer be added to an ad set as the rollout of these requirements remains delayed.

This change affects the following endpoints:

• GET /custom_audience_id

Meta Business SDKs

Meta Business SDKs v23 Release

The Meta Business SDK v23 release will be published shortly after the release of Graph API v23. This release will include dependency upgrades, new features, and deprecation of few root Graph Instagram nodes.

In this release, we introduced version one of ThirdPartyAccount library in Python and Node.js SDKs to simplify the usage of the 2Tier APIs. Additionally, updated parameter list for the original_event_data parameter. We are planning to extend these features to other languages soon.

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

• Sept 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

• September 12, 2025: Graph API v.17 will be deprecated and removed from the platform.
• January 26, 2026: Graph API v.18 will be deprecated and removed from the platform.

Marketing API

• Sept 6, 2025: Marketing API v21.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.