Version 3.3

Marketing API

Released April 30, 2019 | Available Until - Deprecation Extension - January 13, 2020

New Features

We made Marketing API improvements for STORE_VISITS, which is also known as Store Traffic in Facebook UIs. With this optimization_goal, we deliver your ads with the goal of driving store traffic to locations you specify by given Facebook Pages. Note: This API is under limited availability. Please contact your Facebook Representative for access.

• You can now use an asynchronous request to create a Page Set. This enables you to create large page sets with more than 1,000 locations without experiencing timeouts. Previously, you could only make synchronous requests.

• We now include a metadata field. With this field, you can specify fixed_radius to provide absolute distances from your locations. Or, you can specify audience and Facebook automatically calculates a radius around your location to reach this number of people. Facebook tries to deliver your ad to an audience in this radius.

For more details, see Store Visits, Create a Pageset.

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. This impacts:

  • POST /{ad_account_ID}/creatives

  • GET /{creative-id}?fields=object_story_spec

• Default use_flexible_image_aspect_ratio to true. This field is only for single image ads, not for carousel ads. If you set this to true, when the image's aspect ratio, or width:height ratio, is between 1.91:1 and 1:1, we render the entire image. If the image is taller than the aspect ratio of 1:1, we automatically crop it to 1:1 and render the cropped image.

  If the image is wider than the aspect ratio 1.91:1, we automatically crop it to 1.91:1 and render the cropped image.

  If you set this to false, or provide no value, when the image's aspect ratio, or width:height ratio, is 1.91:1, we render the entire image. If the image aspect ratio is not 1.91:1, we automatically crop it to the 1.91:1 aspect ratio and render the cropped image.

  This field only applies to images if you don't provide a cropping_spec. If you do provide a cropping_spec, we ignore this field. We don't support this for Event ads, Offer ads, dynamic ads, ads with image overlays, and ads using stock images. This impacts:

  • POST /{ad_account_ID}/creatives

  • GET {ad_creative_ID}

  • POST {ad_account_ID}/ads

  • POST {ad_ID}

• Deprecated 191x100 cropping_spec for all placements. The recommended crop key will be 100x100. This impacts:

  • POST /{ad_account_ID}/creatives

  • GET {ad_creative_ID}

  • POST {ad_account_ID}/ads

  • POST {ad_ID}

• Default optimization for campaigns with VIDEO_VIEWS objective is THRUPLAY. This impacts:

  • POST {ad_account_ID}/adsets

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

• Added event to the pixel automatic event /stats response. This provides an additional way to group response data with stats based on the detection method for an event. This impacts GET {ads-pixel-ID}/stats/aggregation=event_detection_method.

Catalog

• We now require ads_management permissions scope for all users trying to create, update, or delete catalogs and any objects related to a catalog, such as a hotel. As of v3.3, we require this and any public version of the API will require this in 90 days. This impacts Catalog and all dynamic ads that rely on catalogs, such as Hotel ads, Automotive Inventory ads and Real Estate ads. This impacts:

  • POST {catalog_ID}/batch

  • GET {catalog_ID}/check_batch_request_status

  • GET {catalog_ID}/product_feeds

  • POST {catalog_ID}/product_set_batch

  • GET {catalog_ID}/home_listings

  • GET {catalog_ID}/hotels

  • GET {catalog_ID}/hotel_rooms_batch

  • POST {catalog_ID}/hotel_rooms_batch

  • GET {catalog_ID}/pricing_variables_batch

  • POST {catalog_ID}/pricing_variables_batch

  • GET {catalog_ID}/products

  • GET {catalog_ID}/vehicles

  • GET requests for all other vertical-specific catalog objects

    
    

  • GET {product_set_ID}/products

  • GET {product_set_ID}/home_listings

  • GET {product_set_ID}/hotels

  • GET {product_set_ID}/vehicles

  • GET requests for all other vertical-specific product set objects

    
    

  • GET {product_feed_ID}/products

  • GET {product_feed_ID}/home_listings

  • GET {product_feed_ID}/hotels

  • GET {product_feed_ID}/vehicles

  • GET requests for any other vertical-specific product feed objects

    
    

  • GET {business_ID}/owned_product_catalogs

  • GET {business_ID}/client_product_catalogs

    
    

  • GET {product_feed_upload_ID}/errors

  • GET {product_catalog_ID}/smart_pixel_settings

  • GET {product_feed_ID}/rules

  • POST {canvas_ID}/product_set

  • GET {application_ID}/da_checks

  • GET {pixel_ID}/da_checks

• Deprecated user permissions endpoints for managing access to catalogs. For background information, see Business Manager API, Product Catalogs:

  • GET catalog_ID/userpermissions to read permissions granted to people for the catalog

  • POST catalog_ID/userpermissions to grant permissions

  • DELETE {catalog_id}/userpermissions to revoke permissions

  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

• Changed rate limits at the ad account level to better reflect the actual volumne of API calls needed. We now compute the rate limit quota based on your Marketing API access tier and the business for your app. This goes into effect 90 days after the release of v3.3 for all public versions. See Marketing API, Access and Authentication. This change impacts all ads Insights API endpoints including:

  • GET {ad_account_ID}/insights

  • GET {ad_campaign_ID}/insights

  • GET {adset_ID}/insights

  • GET {ad_ID}/insights

  • POST {ad_account_ID}/insights

  • POST {ad_campaign_ID}/insights

  • POST {adset_ID}/insights

  • POST {ad_ID}/insights

• Deprecated several Insights API metrics, including action_type breakdowns. This impacts the following endpoints:

  • GET {ad_account_ID}/insights

  • GET {ad_campaign_ID}/insights

  • GET {adset_ID}/insights

  • GET {ad_ID}/insights

  • POST {ad_account_ID}/insights

  • POST {ad_campaign_ID}/insights

  • POST {adset_ID}/insights

  • POST {ad_ID}/insights

  The following are deprecated metrics and breakdowns plus some recommended alternates:

  • Deprecated app_custom_event.fb_mobile_purchase from the metric mobile_app_purchase_roas. You can find a replacement metric at omni_purchase, action type purchase_roas metric.

  • Deprecated offsite_conversion.fb_pixel_purchase from the metric website_purchase_roas. You can find a replacement metric at omni_purchase, action type purchase_roas metric.

  The following action types are entirely deprecated from all Insights API metrics:

  • offline_conversion

  • onsite_conversion.messaging_reply — You can replace with a custom formula as onsite_conversion.messaging_first_reply divided by onsite_conversion.messaging_conversation_started

  • receive_offer

  • commerce_event

  • commerce_event.add_to_cart

  • commerce_event.purchase

  • commerce_event.message_to_buy

  • commerce_event.other

  • commerce_event.view_content

Business Manager API

• Deprecated the role_based field permitted_role in Business Manager API. The following endpoint is impacted: POST {business-id}/owned_businesses.

• Deprecated {business_ID}/creditcards. Instead you should use GET {credit_card_ID}.

Upgrading to Marketing API v3.3

A few reminders for our developer community:

• All versions prior to Marketing API v3.2 will be deprecated on May 14, 2019.
• All apps need to be on at least v3.3.
• 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.