Periodically, you might want to upgrade from an older major version of the Google Ads API to a newer major version. It could be because a version is sunsetting, or it could be because you want to use a new feature. We recommend that you always upgrade to the newest version.
Check out our deprecation schedule to plan your upgrades. See our versioning guide to learn how versioning works.
Here's a checklist to help you get started with the process of upgrading:
- Your endpoint will change when you change major versions. Update your client libraries to use the newest endpoint.
- Go through the release notes to see changes that were introduced in each release.
- Check out the key changes lists, like Key changes from v22 to v23 , for specific areas to focus on for the version to which you are upgrading.
- Check out the proto difference tables, like Proto differences between v22 and v23.
v22 to v23
The following sections describe key changes and proto differences for upgrading from v22 to v23.
Key changes from v22 to v23
- Added
IncentiveServiceto allow partners to programmatically fetch and apply Google Ads incentives for their customers. - Sharing ads among multiple ad groups is no longer allowed. Attempting to do
so returns
AD_SHARING_NOT_ALLOWED. - Deprecated create and update operations for
CallAdandCallAdInfo. - Added read-only field
orientationto image and video assets inAsset. - Added support to retrieve
CampaignAssetwith afield_typeofHEADLINEandDESCRIPTION. - In
InvoiceService.ListInvoices, you can now request granular details, including campaign-level cost breakdown, by settinginclude_granular_level_invoice_detailsinListInvoicesRequest. - Added
Campaign.start_date_timeandCampaign.end_date_timeto replaceCampaign.start_dateandCampaign.end_date, allowing you to specify time components for certain campaign types. - In Demand Gen, added field
DemandGenVideoResponsiveAdInfo.companion_bannerand removed fieldDemandGenMultiAssetAdInfo.lead_form_only. - Enabled ad network type breakdown for Performance Max campaigns.
- Added
BenchmarksServiceto compare YouTube advertisement data against industry benchmarks. - Added
AudienceInsightsService.GenerateAudienceDefinitionto translate a free text description of a target audience into matching audience attributes using generative AI. - Removed aggregate asset performance label metrics from reports. The performance label enum is no longer returned for Search and Display campaigns.
- Added
PerStoreViewto query store location details andMatchedLocationInterestViewfor AI Max campaigns to view performance metrics broken down by geographic locations users showed interest in. ShoppingPerformanceViewnow supports metrics segmented by conversion date, and new competitive metrics:search_budget_lost_impression_share,search_rank_lost_impression_share,search_budget_lost_absolute_top_impression_share, andsearch_rank_lost_absolute_top_impression_share.- Added
ShoppingProduct.product_image_uri.
Proto differences between v22 and v23
This table shows the protos that were added, removed, and changed in the Google Ads API v23 release. You can click the links to view the protos in our GitHub repository
after they're released. You can view quick and full-context diffs in the Changed tab.
v21 to v22
The following sections describe key changes and proto differences for upgrading from v21 to v22.
Key changes from v21 to v22
Renamed the field
BudgetPerDayMinimumErrorDetails.minimum_bugdet_amount_microstominimum_budget_amount_micros.New limits are enforced for batch jobs.
- Added a limit of 10,000 operations per
AddBatchJobOperationsrequest. - Updated handling for the
page_sizefield inListBatchJobResultsRequest:- If
page_sizeis not set or is 0, it now defaults to the maximum of 1,000 (previously returnedINVALID_PAGE_SIZE). - If
page_sizeexceeds 1,000, the API now returns anINVALID_PAGE_SIZEerror (previously silently capped at 1,000).
- If
- Added a limit of 10,000 operations per
Removed
AssetPerformanceLabelfor Performance Max campaigns.The functionality of the removed
Campaign.url_expansion_opt_outis now managed by setting theAssetAutomationTypeFINAL_URL_EXPANSION_TEXT_ASSET_AUTOMATIONinAssetAutomationSetting.In
ReachPlanService, added the fieldtrueview_views, which replaces theviewsfield.Renamed several video-views related metrics:
average_cpvis nowtrueview_average_cpvvideo_view_rateis nowvideo_trueview_view_ratevideo_viewsis nowvideo_trueview_viewsvideo_view_rate_in_feedis nowvideo_trueview_view_rate_in_feedvideo_view_rate_in_streamis nowvideo_trueview_view_rate_in_streamvideo_view_rate_shortsis nowvideo_trueview_view_rate_shorts
Proto differences between v21 and v22
This table shows the protos that were added, removed, and changed in the Google Ads API v22 release. You can click the links to view the protos in our GitHub repository after they're released. You can view quick and full-context diffs in the Changed tab.
v20 to v21
The following sections describe key changes and proto differences for upgrading from v20 to v21.
Key changes from v20 to v21
| Changes to services and their components | |
|---|---|
ConversionUploadService
|
The debug_enabled field was removed from UploadClickConversionsRequest.
Refer to our
announcement
for more details. |
Proto differences between v20 and v21
This table shows the protos that were added, removed, and changed in the Google Ads API v21 release. You can click the links to view the protos in our GitHub repository after they're released. You can view quick and full-context diffs in the Changed tab.
v19 to v20
The following sections describe key changes and proto differences for upgrading from v19 to v20. Note that v19 is now sunset.
Key changes from v19 to v20
| Changes to services and their components | |
|---|---|
ContentCreatorInsightsService,
AudienceInsightsService
|
Added AudienceInsightsDimension.YOUTUBE_LINEUP to replace
AudienceInsightsDimension.YOUTUBE_DYNAMIC_LINEUP. This change
also affects related types such as AudienceInsightsAttributeMetadata
and AudienceInsightsDimension. Refer to the
diff table for more details.
|
Proto differences between v19 and v20
This table shows the protos that were added, removed, and changed in the Google Ads API v20 release. You can click the links to view the protos in our GitHub repository after they're released. You can view quick and full-context diffs in the Changed tab.