Upgrading to the newest version

Periodically, you will upgrade from an older major version of 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 upgrade to the newest version when going through the migration process.

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.

Migrating from v2 to v3

Changes to Services and their Components

Renamed shopping objects including:

  • ListingBrandInfo to ProductBrandInfo
  • ListingCustomAttributeInfo to ProductCustomAttributeInfo
  • ListingCustomAttributeIndex to ProductCustomAttributeIndex
BiddingStrategyService Removed BiddingStrategy.target_outrank_share and BiddingStrategy.page_one_promoted. This was already sunset in this blog post. Please see the blog post for alternatives.

Removed the following unused enum values:

  • BudgetPeriod.CUSTOM
  • BudgetPeriod.FIXED_DAILY

Removed the following unused errors:

GoogleAdsService Introduced multiple ways of returning summaries in results when retrieving data from GoogleAdService.Search() by setting summary_row_setting. Previous versions had the setting return_summary_row, which has been removed in this version.
GoogleAdsService Introduced returning total results count when retrieving data from GoogleAdService.Search() by setting return_total_results_count to true in the request. In previous versions, the total result count is always returned.
PaymentsAccountService Updated PaymentsAccountService.ListPaymentsAccounts() to return PaymentsAccountError.NOT_SUPPORTED_FOR_MANAGER_CUSTOMER when making a request to a manager account. The previous behavior in v1 and v2 was to return an empty list.

Migrating from v1 to v2

Changes to Services and their Components
AdGroupAdService Introduced companion_banner in VideoBumperInStreamAdInfo and VideoNonSkippableInStreamAdInfo. Note that this is a breaking change for some as this introduced a new field in an empty object.
CampaignService Renamed LOCATION_OF_PRESENCE to LOCATION in NegativeGeoTargetType and PositiveGeoTargetType.
Updated the Campaign GeoTargetTypeSetting to default to PRESENCE_OR_INTEREST for NegativeGeoTargetType and PositiveGeoTargetType.
ExtensionFeedItemService Removed review extensions by removing ExtensionType.REVIEW. This was already deprecated in AdWords API.
FeedItemService Introduced PlaceholderType, and renamed placeholder_type field to placeholder_type_enum, using an enum rather than an integer.
GeographicView Replaced country_geo_target_constant with country_criterion_id in GeographicView.
GoogleAdsFieldService Set an error on the limit. The page size that can be passed in must be 1 to 10,000 inclusive. Any other number now results in an INVALID_PAGE_SIZE error.
GoogleAdsService Removed:

For other available metrics, refer to this blog post.

Updated segments.click_type to NOT be compatible with: