Upcoming change in Marketing API version deprecation to enable version auto-upgrade

To enhance the overall API experience by making it more seamless and efficient, we are excited to announce the upcoming launch of the MAPI version auto upgrade feature. Starting from May, 2024, we will enable the auto-version upgrade feature for Marketing API endpoints that are not affected between versions. This means between a version to be deprecated and the next available version, if an endpoint is not affected, the platform will automatically upgrade the call to the next available version, rather than directly failing the request.

Versioning an API is a common way of handling changes to the API, most commonly it is used for shipping breaking changes. As new versions get released, older versions are deprecated. During API deprecation, if an app is calling a deprecated API version, it will receive an error ‘(#2635) You are calling a deprecated version of the Ads API. Please update to the latest version: vXXX’.

On May 14th, 2024, v17.0 will be deprecated. According to the changelog of v18.0, the following endpoints will be affected:

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

If your app is calling POST /{adset-id} with v17.0 after it has been deprecated on May 14th, 2024, this api request will fail as the auto-upgrade is not applied to endpoints affected by the next available version v18.0.

If your app is calling GET /{ad-account-id}/insights with v17.0 after it has been deprecated, the platform will upgrade your call to the next available version v18.0.

If your app is already making calls with versions higher than v17.0, nothing would be changed on the version deprecation date.

To opt-out version auto-upgrade, please check Settings > Ads API Version Settings under the Marketing API App Product card to disable this feature.

To confirm if a call has been auto-upgraded, please check the API response header for more detail.

• Example notification header: ‘X-Ad-Api-Version-Warning:‘ The call has been auto-upgraded to v17.0 as v16.0 has been deprecated’’

To learn more about the behavior, refer to the Marketing API Versioning.

To check endpoints affected at each version, please refer to the Changelog.

Impacted endpoints

• All MAPI endpoints

Link to developer documentation

• https://developers.facebook.com/docs/marketing-api/versions#version_auto_upgrade

Link to help article on feature

• https://developers.facebook.com/docs/marketing-apis