Back to News for Developers

Introducing Marketing API v3.1

July 26, 2018ByJia Chen

On July 26, 2018, 10:30 am PT, we're releasing Marketing API version 3.1, and also introducing a new permission system for Business Manager API. This new release provides developers greater control over Business Manager permissions, and updates several outdated endpoints and fields. We will deprecate all versions prior to v3.0 on Aug 7, 2018.

New Permission System for Business Manager API

We're introducing the new feature of task-based permissions to replace the current role-based permission. This feature affects access to ad accounts managed by the Business Manager API and Pages. Role-based access to ad accounts and Pages is still available but will be deprecated in the future.

For more details, see the Marketing API v3.1 changelog.

Breaking Changes for Marketing API

  • Deprecated PAGE_ENGAGEMENT as optimization_goal for ad campaigns. As of v3.1, you can no longer create, update, or duplicate ad campaigns with optimization_goal set to PAGE_ENGAGEMENT.
    • If you have existing ad campaigns created prior to v3.1, you can still run these campaigns with this setting.
    • You can still use PAGE_ENGAGEMENT as an Insights API breakdown for data on existing ad campaigns using optimization_goal.
  • Deprecated single-image Page Like Ads with no post. As of v3.1, you can no longer create single-image Page Like Ads without a page post. Instead, you should create a Page Like Ad with a post.
  • Renamed cost_per_store_visit and store_visits for the Insights API to cost_per_store_visit_actions and store_visit_actions.
  • No Lead Ads Retrieval via Webhooks for Dev Tier - We'll stop sending data collected in Lead Ads forms via webhooks to apps in Dev Mode. We begin enforcing this change on February 1, 2019.
    • If you subscribe to updates in v3.1, we will not send any updates, unless your app is in production and in Live Mode.
    • If you create a new app after v3.1 is available, we will not send any updates, unless your app is in production and in Live Mode.
    • If you have an existing app, it must be in Live Mode by February 1, 2019. Until that date, you will continue receiving updates in Dev Mode.

For more information about Marketing API access tiers and app modes, see New Structure for Marketing API Access and Marketing API, Access and Authentication.

Upgrading to Marketing API v3.1

A few key reminders for our developer community:

  • All versions prior to Marketing API v3.0 will be deprecated at Aug 7, 2018.
  • All apps need to be on at least v3.0.
  • Developers should specify /v3.1/ in your URLs when you call the API.
  • To see details of changes in v3.1, see the Graph API v3.1 Changelog.
  • SDK developers should view our latest Java SDK, PHP SDK, Python SDK, or Ruby SDK.