Marketing API, v3.3

By Niti Hantaweepant

We've released Marketing API, version 3.3. Below is a highlight of updates. To learn more about new features, updates, deprecations, and impacts, see the Marketing API v3.3 changelog.

Ads Management

Deprecated custom_overlay_spec field in link_data, photo_data and video_data in the object_story_spec field for ad creatives. Text overlays on top of images and videos resulted in poorer ad performance compared to ads without text overlays. As of November 2018, you could no longer create image or video ads with this feature. As of this release, if you have ads with text overlays specified in your object_story_spec, we deliver your ads without the overlay.
Deprecated VIDEO_VIEWS as a valid optimization for ad campaigns with the APP_INSTALL or POST_ENGAGEMENT objective. This optimization goal is also commonly known as 10-second video views.

Catalog

We now require ads_management permissions scope for all users trying to create, update or delete product catalogs and any objects related to a product catalog, such as a hotel. We require this as of v3.3 and any public version of the API will require this in 90 days time. This impacts Product Catalog and all Dynamic Ads which rely on catalogs such as Hotel Ads, Dynamic Automotive Ads and Dynamic Ads for Real Estate. See the Marketing API v3.3 changelog for details.
Deprecated user permissions endpoints for managing access to product catalogs. See the Marketing API v3.3 changelog for details.

We replace these endpoints with new endpoints:

GET catalog_ID/assigned_users?business={business_id} to read permissions granted to users to access this catalog,
POST {catalog_id}/assigned_users?business={business_id} to grant permissions,
DELETE {catalog_id}/assigned_users?business={business_id} to revoke permissions.

Deprecated Batch API v2.8 for catalogs. This goes into effect in early Q3, 2019. To keep your current upload feed structure, you can continue using /batch instead of moving to /items_batch and keep your field names consistent. To do so, switch to API version 2.9 or above. For more information, see Catalog Batch API.

Ads Insights and Measurement

Deprecated several Insights API metrics, including action_type breakdowns. See the following table lists deprecated metrics and breakdowns plus some recommended alternates:

Metric	Deprecated `action_type`	Alternate Metric and Breakdown
`actions`	`offline_conversion`	No replacement metric or breakdown. We recommend you customize a composite metric based on conversion events that matter to you.
`action_values`	`offline_conversion`	No replacement metric or breakdown. We recommend you customize a composite metric based on conversion events that matter to you.
`cost_per_action_type`	`offline_conversion`	No replacement metric or breakdown. We recommend you customize a composite metric based on conversion events that matter to you.
`actions`	`onsite_conversion.` `messaging_reply`	Replacement metric: `actions` Replacement breakdowns: `onsite_conversion.` `messaging_conversation_start` `onsite_conversion.` `messaging_first_reply`
`cost_per_action_type`	`onsite_conversion.` `messaging_reply`	Replacement metric: `cost_per_action_type` Replacement breakdowns: `onsite_conversion.` `messaging_conversation_start` `onsite_conversion.` `messaging_first_reply`
`actions`	`receive_offer`	Replacement metric: `actions` Replacement breakdowns: `onsite_conversion.` `post_save`
`cost_per_action_type`	`receive_offer`	Replacement metric: `cost_per_action_type` Replacement breakdowns: `onsite_conversion.` `post_save`
`mobile_app_purchase_roas`	`app_custom_event.` `fb_mobile_purchase`
`website_purchase_roas`	`offsite_conversion.` `fb_pixel_purchase`

Upgrading to Marketing API v3.3

A few key reminders for our developer community:

All versions prior to Marketing API v3.2 will be deprecated at May 14, 2019.
Developers should specify /v3.3/ in your URLs when you call the API.
To see details of changes in v3.3, see the Graph API v3.3 Changelog.
SDK developers should view our latest Java SDK, PHP SDK, Python SDK, or Ruby SDK.

Explore more

October 2, 2024

Introducing Graph API v21.0 and Marketing API v21.0

October 1, 2024

Introducing new features for the Threads API

September 30, 2024