Bing Ads API Release Notes

See below for information about changes to Bing Ads API Version 13 by month.

March 2020

See below for Bing Ads API updates during this calendar month.

Ad Scheduling by Account Time Zone

Ad scheduling by account time zone is available for customers in the pilot (GetCustomerPilotFeatures returns 655). Later this year it will be available in all customers.

The AdScheduleUseSearcherTimeZone element is available in the Campaign and Ad Group Campaign Management objects. The Ad Schedule Use Searcher Time Zone field is available in the Campaign and Ad Group Bulk records.

The new property for each campaign and ad group determines whether to use the account time zone or the time zone of the search user where the ads could be delivered.

Note

If you do not specify this element or leave it null, the default value of true will be set and the search user's time zone will be used. Towards the end of Q2 or the beginning of Q3 Calendar Year 2020 and going forward, the new default value of false will be set and the account time zone will be used.

February 2020

See below for Bing Ads API updates during this calendar month.

Goal and Goal Type in Reports

The Goal and GoalType columns are added to the following value sets.

These columns were already available in the GoalsAndFunnelsReportColumn value set.

The goal is the name of the goal you set for the conversions you want, meaning actions customers take after clicking your ad. The goal type is the type of conversion goal. Possible values include AppInstall, Duration, Event, InStoreTransaction, OfflineConversion, PagesViewedPerVisit, and Url.

January 2020

See below for Bing Ads API updates during this calendar month.

Deprecating Accelerated Budget Delivery

As of January 2020 the budget type for shared and unshared budgets are read-only for all DynamicSearchAds, Shopping, and Search campaigns, and any budget type value that you attempt to set will be ignored without returning an error. Previous budget settings will be migrated from accelerated to standard, and the API will only return "DailyBudgetStandard" for DynamicSearchAds, Shopping, and Search campaigns, as well as for all shared budgets. You can still use accelerated budgets with Audience campaigns. The budget type data is not migrated for Audience campaign level unshared budgets. However, the budget delivery might change as described above if the Audience campaign uses a shared budget.

The accelerated budget deprecation phases started in November 2019. For more information, please see Deprecating Accelerated Budget Delivery.

Action Ad Extension Types

Starting January 2020, nine action types are deprecated. For example, if you set the action type to "Browse" no error will be returned, but "LearnMore" is the effective value that will be stored and returned when retrieving the action ad extension. Your application should use the replacement values instead of the deprecated values.

Deprecated Action Type Replacement Action Type
Browse LearnMore
Explore LearnMore
Message ContactUs
NewCars ViewCars
SeeMore LearnMore
StartFree FreeTrial
UsedCars ViewCars
ViewNow LearnMore
VisitSite LearnMore

Also starting January 2020 two new action types are added i.e., RenewNow and Reorder. Please note that if you use the version 12 Campaign Management API, by default the action type returned is Unknown. (The design goal is to avoid a breaking change for clients with strict value set dependencies.) To determine the effective action type i.e., RenewNow or Reorder, include ActionTypesPhase3 when calling the GetAdExtensionsAssociations and GetAdExtensionsByIds operations.

One final update starting in January 2020, only the localized text for Sale and Coupon are updated to "See Sale" and "Get Coupon" respectively for all supported languages. The API value sets are unchanged for these action types. For the current localized text please see Action Text for Action Ad Extensions.

December 2019

See below for Bing Ads API updates during this calendar month.

Bing Ads API SDK Updates

The Bing Ads .NET, Java, Php, and Python SDKs are updated. For details please see release notes for Microsoft Advertising .NET, Java, Php, and Python SDK version 13.0.2.

November 2019

See below for Bing Ads API updates during this calendar month.

Final Url Suffix and Custom Parameter Expansion

Final URL suffix is now available at the account, campaign, ad group, ad group criterion, ad, and keyword level for all customers. Final URL suffix is available at the action, price, and sitelink ad extension level for Phase 3 pilot customers (GetCustomerPilotFeatures returns 636).

Up to 8 custom parameters and longer custom parameter values are now available at the account, campaign, ad group, ad group criterion, ad, and keyword level for all customers. Up to 8 custom parameters and longer custom parameter values are available at the action, price, and sitelink ad extension level for Custom Parameters Limit Increase Phase 3 pilot (GetCustomerPilotFeatures returns 635).

For more information see URL Tracking with Upgraded URLs.

Bing Ads API SDK Updates

The Bing Ads .NET, Java, Php, and Python SDKs are updated. For details please see release notes for Microsoft Advertising .NET, Java, Php, and Python SDK version 13.0.1.

October 2019

See below for Bing Ads API updates during this calendar month.

Include View Through Conversions

View-through conversions are conversions that people make after they have seen your ad, even though they did not click the ad.

If you are in the feature pilot (GetCustomerPilotFeatures returns 616) this feature is enabled by default, meaning that the values in the "All" conversions columns of your performance reports will include view-through conversions. You can choose to disable it if you don't want to include view-through conversions.

You can enable or disable the feature for each account via Bulk and Campaign Management API.

You can manage the view through conversion window with the Campaign Management API i.e., get or set the ViewThroughConversionWindowInMinutes property of the DurationGoal, EventGoal, PagesViewedPerVisitGoal, or UrlGoal. Be sure to explicitly request ViewThroughConversionWindowInMinutes as an additional field when calling GetConversionGoalsByIds and GetConversionGoalsByTagIds.

Note

View-through conversions require a UETTag, so this property is not applicable for the AppInstallGoal, InStoreTransactionGoal, and OfflineConversionGoal.

Profile Expansion Enabled

Determines whether to expand LinkedIn profile targeting across your account to reach additional customers similar to the ones you currently target.

Enabling profile targeting expansion allows Microsoft Advertising to show your ads to additional customers similar to the ones you currently target. For example, if you target a specific LinkedIn audience segment, we will also target Bing users who don't have a confirmed LinkedIn account but who share the same characteristics as LinkedIn users in that segment.

You can enable or disable the feature for each account via Bulk and Campaign Management API.

Bing Ads API SDK Updates

The Bing Ads .NET, Java, Php, and Python SDKs are updated. For details please see release notes for Microsoft Advertising .NET, Java, Php, and Python SDK version 12.13.6.

September 2019

See below for Bing Ads API updates during this calendar month.

Experiment Type

You can now set the experiment split type via the ExperimentType element in the Experiment Campaign Management object or via the Experiment Type field in the Experiment Bulk record.

The experiment split type determines whether to show individual customers ads from the experiment and the original campaign randomly, or only from one or the other.

The possible values include TrafficBased and CookieBased.

TrafficBased: This is also known as the search-based option. Every time customers search, they are randomly shown either ads from your experiment or ads from your original campaign. This means that individual customers could see ads from both sources if they search multiple times.

CookieBased: When individual customers search, we show ads from either your experiment or your original campaign, and use a cookie to ensure that, going forward, they will only see ads from this source. The cookie-based option has an important trade-off to consider: On one hand, you may get more accurate data, since you're ensuring that an individual customer is only responding to one source or the other. On the other hand, it may take you longer to build up statistically significant comparison data than with the search-based option.

Final Url Suffix in Reports

The FinalUrlSuffix column is added to the AdPerformanceReportColumn value set. The FinalUrlSuffix column is also available via the AdGroupPerformanceReportColumn, CampaignPerformanceReportColumn, DestinationUrlPerformanceReportColumn, and KeywordPerformanceReportColumn value sets.

The final URL suffix is a place in your final URL where you can add parameters that will be attached to the end of your landing page URL.

Product Negative Keyword Report

The ProductNegativeKeywordConflictReportRequest is added for Microsoft Shopping Campaigns. Use this report to confirm that negative keywords applied to your Shopping campaigns are not excessively restricting campaign performance. You can request negative keywords and the corresponding products which they're preventing from showing in your Shopping campaigns.

Bing Ads API SDK Updates

The Bing Ads .NET, Java, Php, and Python SDKs are updated. For details please see release notes for Microsoft Advertising .NET, Java, Php, and Python SDK version 12.13.5.

August 2019

See below for Bing Ads API updates during this calendar month.

Audience Association Level in Reports

The AssociationLevel column is added to the AudiencePerformanceReportColumn value set.

Bing Ads API SDK Updates

The Bing Ads .NET, Java, Php, and Python SDKs are updated. For details please see release notes for Microsoft Advertising .NET, Java, Php, and Python SDK version 12.13.4.

July 2019

See below for Bing Ads API updates during this calendar month.

Include in Conversions

Customers who are enabled for the Include in Conversions feature (GetCustomerPilotFeatures returns 574) can choose to exclude specific conversion goals from conversions report data.

Data will be excluded from the Conversions, ConversionRate, CostPerConversion, ReturnOnAdSpend, RevenuePerConversion, and Revenue report columns for any conversion goal that has its ExcludeFromBidding property set as true. Also, if you use an automated bidding bid strategy, setting this property true will result in the goal's conversions no longer factoring into automated bidding calculations.

The AllConversions, AllConversionRate, AllCostPerConversion, AllReturnOnAdSpend, AllRevenuePerConversion, and AllRevenue columns (NEW) will include data for all conversion goals regardless of their ExcludeFromBidding setting.

For more information, see the help article Conversion goals: "Conversions" versus "All conversions".

After the July service update, the table below summarizes all available conversion related report performance statistics per report type.

Reporting Value Set Available Conversion Columns
AccountPerformanceReportColumn AllConversions
AllRevenue
AllConversionRate
AllCostPerConversion
AllReturnOnAdSpend
AllRevenuePerConversion
Conversions
Revenue
ConversionRate
CostPerConversion
ReturnOnAdSpend
RevenuePerConversion
AdDynamicTextPerformanceReportColumn AllConversions
AllConversionRate
AllCostPerConversion
Conversions
ConversionRate
CostPerConversion
AdExtensionByAdReportColumn AllConversions
AllRevenue
AllConversionRate
AllCostPerConversion
AllReturnOnAdSpend
AllRevenuePerConversion
Conversions
Revenue
ConversionRate
CostPerConversion
ReturnOnAdSpend
RevenuePerConversion
AdExtensionByKeywordReportColumn AllConversions
AllRevenue
AllConversionRate
AllCostPerConversion
AllReturnOnAdSpend
AllRevenuePerConversion
Conversions
Revenue
ConversionRate
CostPerConversion
ReturnOnAdSpend
RevenuePerConversion
AdExtensionDetailReportColumn AllConversions
AllRevenue
AllConversionRate
AllCostPerConversion
AllReturnOnAdSpend
AllRevenuePerConversion
Conversions
Revenue
ConversionRate
CostPerConversion
ReturnOnAdSpend
RevenuePerConversion
AdGroupPerformanceReportColumn AllConversions
AllRevenue
AllConversionRate
AllCostPerConversion
AllReturnOnAdSpend
AllRevenuePerConversion
Conversions
Revenue
ConversionRate
CostPerConversion
ReturnOnAdSpend
RevenuePerConversion
AdPerformanceReportColumn AllConversions
AllRevenue
AllConversionRate
AllCostPerConversion
AllReturnOnAdSpend
AllRevenuePerConversion
Conversions
Revenue
ConversionRate
CostPerConversion
ReturnOnAdSpend
RevenuePerConversion
AgeGenderAudienceReportColumn AllConversions
AllRevenue
Conversions
Revenue
AudiencePerformanceReportColumn AllConversions
AllRevenue
AllConversionRate
AllCostPerConversion
AllReturnOnAdSpend
AllRevenuePerConversion
Conversions
Revenue
ConversionRate
CostPerConversion
ReturnOnAdSpend
RevenuePerConversion
CampaignPerformanceReportColumn AllConversions
AllRevenue
AllConversionRate
AllCostPerConversion
AllReturnOnAdSpend
AllRevenuePerConversion
Conversions
Revenue
ConversionRate
CostPerConversion
ReturnOnAdSpend
RevenuePerConversion
ConversionPerformanceReportColumn AllConversions
AllRevenue
AllConversionRate
AllCostPerConversion
AllReturnOnAdSpend
AllRevenuePerConversion
Conversions
Revenue
ConversionRate
CostPerConversion
ReturnOnAdSpend
RevenuePerConversion
DestinationUrlPerformanceReportColumn AllConversions
AllRevenue
AllConversionRate
AllCostPerConversion
AllReturnOnAdSpend
AllRevenuePerConversion
Conversions
Revenue
ConversionRate
CostPerConversion
ReturnOnAdSpend
RevenuePerConversion
DSAAutoTargetPerformanceReportColumn AllConversions
AllRevenue
AllConversionRate
AllCostPerConversion
AllReturnOnAdSpend
AllRevenuePerConversion
Conversions
Revenue
ConversionRate
CostPerConversion
ReturnOnAdSpend
RevenuePerConversion
DSACategoryPerformanceReportColumn AllConversions
AllRevenue
AllConversionRate
AllCostPerConversion
AllReturnOnAdSpend
AllRevenuePerConversion
Conversions
Revenue
ConversionRate
CostPerConversion
ReturnOnAdSpend
RevenuePerConversion
DSASearchQueryPerformanceReportColumn AllConversions
AllRevenue
AllConversionRate
AllCostPerConversion
AllReturnOnAdSpend
AllRevenuePerConversion
Conversions
Revenue
ConversionRate
CostPerConversion
ReturnOnAdSpend
RevenuePerConversion
GeographicPerformanceReportColumn AllConversions
AllRevenue
AllConversionRate
AllCostPerConversion
AllReturnOnAdSpend
AllRevenuePerConversion
Conversions
Revenue
ConversionRate
CostPerConversion
ReturnOnAdSpend
RevenuePerConversion
GoalsAndFunnelsReportColumn AllConversions
AllRevenue
Conversions
Revenue
KeywordPerformanceReportColumn AllConversions
AllRevenue
AllConversionRate
AllCostPerConversion
AllReturnOnAdSpend
AllRevenuePerConversion
Conversions
Revenue
ConversionRate
CostPerConversion
ReturnOnAdSpend
RevenuePerConversion
ProductDimensionPerformanceReportColumn AllConversions
AllRevenue
AllConversionRate
AllCostPerConversion
AllReturnOnAdSpend
AllRevenuePerConversion
Conversions
Revenue
ConversionRate
CostPerConversion
ReturnOnAdSpend
RevenuePerConversion
ProductPartitionPerformanceReportColumn AllConversions
AllRevenue
AllConversionRate
AllCostPerConversion
AllReturnOnAdSpend
AllRevenuePerConversion
Conversions
Revenue
ConversionRate
CostPerConversion
ReturnOnAdSpend
RevenuePerConversion
ProductPartitionUnitPerformanceReportColumn AllConversions
AllRevenue
AllConversionRate
AllCostPerConversion
AllReturnOnAdSpend
AllRevenuePerConversion
Conversions
Revenue
ConversionRate
CostPerConversion
ReturnOnAdSpend
RevenuePerConversion
ProductSearchQueryPerformanceReportColumn AllConversions
AllRevenue
AllConversionRate
AllCostPerConversion
AllRevenuePerConversion
Conversions
Revenue
ConversionRate
CostPerConversion
RevenuePerConversion
ProfessionalDemographicsAudienceReportColumn AllConversions
AllRevenue
Conversions
Revenue
PublisherUsagePerformanceReportColumn AllConversions
AllRevenue
AllConversionRate
AllCostPerConversion
AllReturnOnAdSpend
AllRevenuePerConversion
Conversions
Revenue
ConversionRate
CostPerConversion
ReturnOnAdSpend
RevenuePerConversion
SearchQueryPerformanceReportColumn AllConversions
AllRevenue
AllConversionRate
AllCostPerConversion
AllReturnOnAdSpend
AllRevenuePerConversion
Conversions
Revenue
ConversionRate
CostPerConversion
ReturnOnAdSpend
RevenuePerConversion
ShareOfVoiceReportColumn AllConversions
AllConversionRate
AllCostPerConversion
Conversions
ConversionRate
CostPerConversion
UserLocationPerformanceReportColumn AllConversions
AllRevenue
AllConversionRate
AllCostPerConversion
AllReturnOnAdSpend
AllRevenuePerConversion
Conversions
Revenue
ConversionRate
CostPerConversion
ReturnOnAdSpend
RevenuePerConversion

Base Campaign Id in Reports

The BaseCampaignId column is added to the following value sets.

Average Position in Reports

The AveragePosition column is added to the ProfessionalDemographicsAudienceReportColumn value set.

Audience Association ID in Reports

The AssociationId column is added to the AudiencePerformanceReportColumn value set.

June 2019

See below for Bing Ads API updates during this calendar month.

Bing Ads API SDK Updates

The Bing Ads .NET, Java, Php, and Python SDKs are updated. For details please see release notes for Microsoft Advertising .NET, Java, Php, and Python SDK version 12.13.3.

Final Url Suffix and Custom Parameters Update

Final URL suffix and custom parameter updates are now generally available at the account, campaign, ad group, and keyword level for all customers. Similar updates for ads, ad extensions, and ad group criterions are still only available for pilot customers.

  • Final URL suffix is now available at the account, campaign, ad group, and keyword level for all customers. Final URL suffix is available for ads, ad extensions, and ad group criterions for Phase 2 pilot customers (GetCustomerPilotFeatures returns 566). Later this year the Final URL suffix will be available for ads, ad extensions, and ad group criterions for all customers.
  • The custom parameter limit for all customers has been increased from 3 to 8 for campaigns, ad groups, and keywords. Microsoft Advertising will accept the first 8 custom parameter key and value pairs that you include, and if you include more than 8 custom parameters an error will be returned. For customers in the Custom Parameters Limit Increase Phase 2 pilot (GetCustomerPilotFeatures returns 565) for ads, ad extensions, and ad group criterions, Microsoft Advertising will accept the first 8 custom parameter key and value pairs that you include, and if you include more than 8 custom parameters an error will be returned. During calendar year 2019 the limit for ads, ad extensions, and ad group criterions will be increased from 3 to 8 for all customers.

Monday to Sunday Report Aggregation

The Reporting API is updated to support Monday through Sunday weekly aggregation. Previously you could only aggregate weekly from Sunday through Saturday.

The WeeklyStartingMonday value is added to the ReportAggregation value set.

The ThisWeekStartingMonday, LastWeekStartingMonday, and LastFourWeeksStartingMonday values are added to the ReportTimePeriod value set.

Prominence Metrics

With new and improved prominence metrics, you may now take a more holistic view of where your ads are appearing on search results pages. These clearer insights can help you better optimize your bidding strategy.

The AbsoluteTopImpressionRatePercent, AbsoluteTopImpressionShareLostToBudgetPercent, AbsoluteTopImpressionShareLostToRankPercent, TopImpressionRatePercent, TopImpressionShareLostToBudgetPercent, TopImpressionShareLostToRankPercent, and TopImpressionSharePercent columns are added to the following report column value sets.

Change History Report by Tool

The Tool column is now available with the change history report. You can determine how changes were made to account, campaign or ad attributes e.g., whether via the Web client, Editor, Bulk upload, or Campaign Management API.

Feeds via Bulk API

The Feed and Feed Item Bulk records are added to support Bulk download and upload of both Ad Customizer Feeds and Page Feeds.

The Page Feed Ids field is added to the Campaign record for Page Feeds.

May 2019

See below for Bing Ads API updates during this calendar month.

Assisted Conversions

Assisted conversions are conversions resulting from the clicks on your ads that have received co-bids from your manufacturer partners. This performance statistic is only available for Sponsored Products in Microsoft Shopping Campaigns. The AssistedConversions column is added to the following report column value sets.

Dynamic Search Ads Text Part 2

Dynamic Search Ads Text Part 2 is available for pilot customers (GetCustomerPilotFeatures returns 600). Later this year it will be available in all customers.

The TextPart2 element is available in the DynamicSearchAd Campaign Management object. The Text Part 2 field is available in the Dynamic Search Ad Bulk record.

Bing Ads API SDK Updates

The Bing Ads .NET, Java, Php, and Python SDKs are updated. For details please see release notes for Microsoft Advertising .NET, Java, Php, and Python SDK version 12.13.2.

April 2019

See below for Bing Ads API updates during this calendar month.

New Production OAuth Endpoint

The Microsoft identity platform endpoint for developers is now available. The Microsoft identity platform endpoint allows both work or school accounts from Azure AD and personal Microsoft accounts (MSA), such as hotmail.com, outlook.com, and msn.com. The Live Connect endpoint only allows authentication with personal accounts.

Important

Even if your users do not have work or school accounts, and even if you do not use the Bing Ads API SDKs we encourage you to update the authorization URL during calendar year 2019, since the Live Connect endpoint is no longer the recommended approach for Microsoft Advertising users. For details see Upgrade to the Microsoft identity platform endpoint FAQ and Authentication with the Microsoft identity platform endpoint.

Bing Ads API SDK Updates

The Bing Ads .NET, Java, Php, and Python SDKs are updated with support for version 13. For details please see release notes for Microsoft Advertising .NET, Java, Php, and Python SDK version 12.13.1.

Version 13 General Availability

Bing Ads API version 13 is now generally available. With the availability of Bing Ads API version 13, version 12 is deprecated and will sunset by October 31, 2019. For more details, see Migrate to Version 13.

March 2019

See below for Bing Ads API updates during this calendar month.

Version 13 Preview

Bing Ads API version 13 is available for preview. For more details about migrating from version 12, see Migrate to Version 13.