Upgrade to the latest version

  • The Google Ads API encourages upgrading to the newest version for optimal functionality and to avoid sunsetting issues.

  • Refer to the deprecation schedule to strategically plan upgrades to newer versions and the versioning guide to understand the process.

  • When upgrading, remember to update client libraries and endpoints, review release notes for changes, and consult version-specific tables for areas to focus on.

  • The upgrade process may involve changes to services, components, and fields within the Google Ads API.

  • Version-specific tables outline key changes, like resource usage policy updates, campaign type and ad type renames, and field modifications.

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:

  1. Your endpoint will change when you change major versions. Update your client libraries to use the newest endpoint.
  2. Go through the release notes to see changes that were introduced in each release.
  3. Check out the tables below for specific areas to focus on for the version you're upgrading to.

For a comprehensive overview of changes based on a diff between the protos from the two versions, look at the diff table. The release notes provide details on features that changed during versions.

v21 to v22

  • Renamed the field BudgetPerDayMinimumErrorDetails.minimum_bugdet_amount_micros to minimum_budget_amount_micros.

  • New limits are enforced for batch jobs.

    • Added a limit of 10,000 operations per AddBatchJobOperations request.
    • Updated handling for the page_size field in ListBatchJobResultsRequest:
      • If page_size is not set or is 0, it now defaults to the maximum of 1,000 (previously returned INVALID_PAGE_SIZE).
      • If page_size exceeds 1,000, the API now returns an INVALID_PAGE_SIZE error (previously silently capped at 1,000).

  • Removed AssetPerformanceLabel for Performance Max campaigns.

  • The functionality of the removed Campaign.url_expansion_opt_out is now managed by setting the AssetAutomationType FINAL_URL_EXPANSION_TEXT_ASSET_AUTOMATION in AssetAutomationSetting.

  • In ReachPlanService, added the field trueview_views, which replaces the views field.

  • Renamed several video-views related metrics:

    • average_cpv is now trueview_average_cpv
    • video_view_rate is now video_trueview_view_rate
    • video_views is now video_trueview_views
    • video_view_rate_in_feed is now video_trueview_view_rate_in_feed
    • video_view_rate_in_stream is now video_trueview_view_rate_in_stream
    • video_view_rate_shorts is now video_trueview_view_rate_shorts

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.

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.

v18 to v19

Changes to services and their components
API-wide

All feed-related entities are removed from the API. Feeds have been deprecated for some time, replaced with assets.

Removed entities and their associated services:

  • AdGroupExtensionSetting
  • AdGroupFeed
  • CampaignExtensionSetting
  • CampaignFeed
  • CustomerExtensionSetting
  • CustomerFeed
  • ExtensionFeedItem
  • Feed
  • FeedItem
  • FeedItemSet
  • FeedItemSetLink
  • FeedItemTarget
  • FeedMapping

Removed enums:

  • FeedOrigin
  • PlaceholderType

Removed fields:

  • ChangeEvent.{feed,feed_item,feed_origin}
  • ChangeEvent.ChangedResource.{feed,feed_item,campaign_feed,ad_group_feed}
  • ChangeStatus.{feed,feed_item,ad_group_feed,campaign_feed,feed_origin}
  • Campaign.DynamicSearchAdsSetting.feeds
  • LocationGroupInfo.feed
  • Segments.placeholder_type

Removed views:

  • FeedPlaceholderView
AudienceInsightsService Submessage types AudienceInsightsAttribute, AudienceInsightsTopic, AudienceInsightsEntity, AudienceInsightsCategory, AudienceInsightsDynamicLineup, AudienceInsightsAttributeMetadata, YouTubeChannelAttributeMetadata, DynamicLineupAttributeMetadata, LocationAttributeMetadata, and UserInterestAttributeMetadata have been migrated out of the "resources" folder into the "common" folder so that they can be reused with the ContentCreatorInsightsService. These types work the same way, but you may need to import them from a different location, depending on your implementation.
AdGroupType, AdType, and AdvertisingChannelSubType The VIDEO_OUTSTREAM ad type has been removed.
DemandGenVideoResponsiveAdInfo When specifying the Campaign.asset_automation_settings or AdGroupAd.ad_group_ad_asset_automation_settings, omitting a setting for AssetAutomationType.GENERATE_SHORTER_YOUTUBE_VIDEOS for the DemandGenVideoResponsiveAdInfo ad type will result in being opted in for this feature. Previously, when omitting this setting, they were opted out.