Version 3.0

Marketing API

Released May 1, 2018 | Available Until February 1, 2019 | Blog Post

• New Features
• Breaking Changes
• Deprecations
• Immediate Deprecations

New Features

Lowest-Cost Bid Strategy, bid_strategy Field

We introduced the new field bid_strategy for {account-id}/adsets which enables you to select an ads bidding strategy based on your business goals. Each strategy has advantages and tradeoffs. Options include:

• LOWEST_COST - Get the most results based on your ad set budget and delivery optimization_goal. Facebook will automatically bid more as needed to spend your budget. You can provide a maximum for your bid or provide no limit with this option.

• TARGET_COST - Provides stable average costs for your ads as you increase your ad set budget.

For more information, see Ads Buying and Optimization, Bid Strategy

Collection Ads, Creating

New API for Creating Collection Ads - In the past, Facebook created a canvas in the background each time you created a collection ad. This limited your access to the underlying canvas; you could not use it to retarget audiences with canvas engagement audiences. Now when you create a collection ad from product sets, you must also explicitly create a canvas with the correct elements. When you use this canvas in a collection ad, Facebook automatically generates the collection ad. For more details, see Collection Ads from Product Sets.

Breaking Changes

Ads Management

• Right-hand Column Invalidation - We invalidate ads that only target the Facebook position, right_hand_column with invalid objectives for right_hand_column on {ad_account_id}/adsets. We now only support right-hand-side placement for supported ad formats with these objectives: Traffic, Conversions, and Product Catalog Sales.

• is_autobid and is_average_price_pacing is deprecated in both GET and POST in v3.0 and later.

Audiences and Ads Targeting

• Changed Rules Syntax for Custom Audiences - We updated the structure for rules used for creating website custom audiences, mobile app custom audiences, page engagement custom audiences, lead ads engagement audiences, canvas engagement audiences and offline custom audiences. This enables you to create rules based on aggregate behavior, rules from different event sources and to exclude rules. See:

  • Custom Audiences from Your Website, Audience Rules,

  • Custom Audiences from your Mobile App, Audience Rules,

  • Page Engagement Custom Audiences,

  • Engagement Audiences for Lead Ads,

  • Engagement Audiences for Canvas and

  • Custom Audiences from Offline Conversions.

Dynamic Ads

• Product Catalog Access - To access catalog items you must specify the correct catalog vertical. If your request does not match the correct vertical for your catalog, you will get an error. For example, if you have an ecommerce catalog you should access it with the corresponding /products endpoint such as GET {catalog_id}/products, GET {product_feed_id}/products, or GET {product_set_id}/products. You cannot access the catalog with endpoints for other verticals such as GET {catalog_id}/autos, GET {product_feed_id}/hotels, or GET {product_set_id}/flights.

• Empty String in Template Tags - We no longer allow empty strings as parameters for Dynamic Ads, template tag options. For example, if you pass an empty string to {{trip.checkin_date date_format:}} you get an error. For background information, see Dynamic Ads, Ads Management.

Ads Insights and Measurement

• Insight Timeouts - If we expect an Insights API request results in a timeout before completion, we return an error with error code 100 and subcode 1504033. We estimate this based on request size and processing progress made relative to the timeout limits. If you get this error, you should make an asynchronous Insights API request for this data. See Insights API Asynchronous Jobs.

• Negative Values in Event Data - If you post event data to {data_set_id}/events with a negative value, it fails. This impacts the data field for POST /{data_set_id-id}/events.

• Insights on Campaign Budget Optimization - adset_budget_value now returns using campaign budget when your ad campaign uses campaign budget optimization. This impacts:

  • GET {adaccount-id}/insights,

  • GET {campaign-id}/insights,

  • GET {adset-id}/insights,

  • GET {ad-id}/insights,

  • POST {adaccount-id}/insights,

  • POST {campaign-id}/insights,

  • POST {adset-id}/insights,

  • POST {ad-id}/insights.

• Default Sorting for Pixel - If you call the GET {account_id}/adspixel edge on either a business account or ad account we return results, sorted by default, by pixel name instead of last pixel fire time.

• Rename pixel stats field - We renamed the timestamp field on the pixel stats edge to start_time. This represents the start time when we begin aggregating hourly data on pixel fires. We now return this in ISO 8601 format and include the timezone offset. This fixes an issue where we returned invalid Unix timestamps. The following endpoints will be affected: GET {ads-pixel-id}/stats.

Deprecations

Business Manager

Deprecated POST {pixel-id}/shared_agencies endpoint. Please use Business Manager UI for sharing ads pixel with agencies.

Ads Management

• Deprecated kpi_custom_conversion_id, kpi_type, and kpi_results from /{ad_campaign_id} and /ad_account_ID/campaigns.

• Deprecated the `redownload` flag from the following endpoints to simplify the API:

  • POST {ad-id}/,

  • POST {adset-id}/,

  • POST act_{ad-account-id},

  • POST act_{ad-account-id}/ads,

  • POST act_{ad-account-id}/adsets

  You can still read this information with the `fields` parameter.

• Deprecated the field zipbytes from POST act_{ad-account-id}/adimages and removed the ability to upload ZIP files at that edge. Please use an image with the extensions: jpg, jpeg, gif, bmp, png, tiff, or tif.

• Deprecated the current method to create collection ads which used one API call with all required assets as parameters. Instead you now need to create a canvas first and then use the canvas link to create collection ad. This enables you to access to underlying canvas object so you can, for example, retarget audiences. See Collection Ads.

• Deprecated use of the Carousel ad format for ads with the Page Post Engagement objective. This combination is no longer valid. See Validation, Objectives and Creatives.

Ads Buying and Bidding

• Deprecated the fields is_autobid and is_average_price_pacing from endpoints: POST {ad-account-id}/adsets and POST {adset-id}. Instead use the new bid_strategy field to specify a particular bid strategy for the ad set. For more information, see Bidding and Optimization.

• Deprecated fields under delivery_estimate for ads and ad accounts. The results did not meet advertiser needs. Moreover, many advertisers have business goals that may not be best fulfilled by Facebook's suggested bid amount. Deprecated fields and parameters include:

  • bid_estimate field,

  • currency parameter,

  • daily_budget parameter,

  • optimize_for parameter

  We recommend you use the true, instrinsic business value you get from Facebook ads and bid based on this. If you do not yet know this value, we suggest you use auto-bid. For background see Ads Help Center, Ad Auctions and Ads Buying and Optimization.

• Deprecated returned result from curve_budget_reach field on GET /{rf-prediction-id}. We now return map, and deprecated the JSON serialized string return value. This impacts: GET /{rf-prediction-id}.

• Deprecated the edge GET /{ad-account-id}/ratecard.

• Deprecated several fields related to billing on /ad_accounts. This includes:

  • next_bill_date

  • active_billing_date_preference

  • pending_billing_date_preference

  • active_asl_schedule

  • salesforce_invoice_group_id

  • transactions

  • adspaymentcycle

  • show_checkout_experience

• Deprecated pixel_id and external_event_source fields GET /customaudience.

Ads Insights and Measurement

• Deprecated matched_unique_users on OFFLINE_EVENT_SET_ID returned by GET /{data-set-id} and GET /{data-set-upload-id}. See Offline Conversions API.

• Deprecated the attributed_events edge and attribute_stats field on the GET /{data_set_id} API. Use the GET /{data_set_id}/stats API to get attributed event stats.

• Deprecated the field matched_unique_users on OFFLINE_EVENT_SET_ID returned by GET /{data-set-id} and GET /{data-set-upload-id}.

• Deprecated default return values at GET {data_set_upload_id}. This no longer return these fields by default: first_upload_time, last_upload_time, api_calls, valid_entries, matched_entries, duplicate_entries, event_time_min, event_time_max, event_stats, and matched_unique_users.

• Deprecated default return values at GET {data_set_id}/stats. This now only return count stats by default. To specify which stats should be returned use the fields parameter or summary parameter for cumulative stats such as average_upload_delay.

• Deprecated default return values for GET {data_set_id}. This no longer returns these fields by default: attribute_stats, duplicate_entries, event_stats, event_time_max, event_time_min, matched_entries, matched_unique_users, usage, valid_entries.

• Deprecated the GET {data-set-upload-id}/stats edge. Please use valid_entries or matched_entries fields from GET {data-set-upload-id} instead.

• Deprecated canvas_component_avg_pct_view from the Insights API.