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:

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 tables below for specific areas to focus on for the version you're upgrading to.

Migrating from v3 to v4

Changes to Services and their Components
`AdGroupAdAssetView`	Changed the format of `AdGroupAdAssetView.resource_name` from `customers/{id}/adGroupAdAssets/{id}` to `customers/{id}/adGroupAdAssetViews/{id}`.
`AdGroupCriterionError`	The following errors were moved to `CriterionError`: `INVALID_LISTING_GROUP_HIERARCHY` `LISTING_GROUP_UNIT_CANNOT_HAVE_CHILDREN` `LISTING_GROUP_SUBDIVISION_REQUIRES_OTHERS_CASE` `LISTING_GROUP_REQUIRES_SAME_DIMENSION_TYPE_AS_SIBLINGS` `LISTING_GROUP_ALREADY_EXISTS` `LISTING_GROUP_DOES_NOT_EXIST` `LISTING_GROUP_CANNOT_BE_REMOVED` `INVALID_LISTING_GROUP_TYPE` `LISTING_GROUP_ADD_MAY_ONLY_USE_TEMP_ID`
`CriterionError`	Renamed error enum values from `CriterionError:` `PRODUCT_FILTER_TOO_LONG -> LISTING_SCOPE_TOO_LONG` `PRODUCT_SCOPE_TOO_MANY_DIMENSIONS -> LISTING_SCOPE_TOO_MANY_DIMENSIONS` `PRODUCT_PARTITION_TOO_LONG -> LISTING_GROUP_TOO_LONG` `PRODUCT_PARTITION_TOO_MANY_DIMENSIONS -> LISTING_GROUP_TREE_TOO_DEEP` `INVALID_PRODUCT_DIMENSION -> INVALID_LISTING_DIMENSION` `INVALID_PRODUCT_DIMENSION_TYPE -> INVALID_LISTING_DIMENSION_TYPE`
KeywordPlanKeywordService	Removed `KeywordPlanKeywordService`. The replacement is `KeywordPlanAdGroupKeywordService`. Removed `KeywordPlanKeywordError`. The replacement is `KeywordPlanAdGroupKeywordError`.
KeywordPlanNegativeKeywordService	Removed `KeywordPlanNegativeKeywordService`. The replacement is `KeywordPlanCampaignKeywordService`. Removed `KeywordPlanNegativeKeywordError`. The replacement is `KeywordPlanCampaignKeywordError`.
MutateJobService	Renamed `MutateJobService` to `BatchJobService`. This service is not yet available for general use, but you can start coding against the service.

Migrating from v2 to v3

Changes to Services and their Components
AdGroupCriterionService	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.
CampaignBudgetService	Removed the following unused enum values: `BudgetPeriod.CUSTOM` `BudgetPeriod.FIXED_DAILY`
CampaignCriterionService CustomerNegativeCriterionService	Removed `GAME` from `ContentLabelType`.
CampaignService	Removed the following unused errors: `CampaignError.missing_universal_app_campaign_setting` `SettingError.UNIVERSAL_APP_CAMPAIGN_SETTING_DUPLICATE_DESCRIPTION` `SettingError.UNIVERSAL_APP_CAMPAIGN_SETTING_DESCRIPTION_LINE_WIDTH_TOO_LONG` `SettingError.UNIVERSAL_APP_CAMPAIGN_SETTING_APP_ID_CANNOT_BE_MODIFIED` `SettingError.TOO_MANY_YOUTUBE_MEDIA_IDS_IN_UNIVERSAL_APP_CAMPAIGN` `SettingError.TOO_MANY_IMAGE_MEDIA_IDS_IN_UNIVERSAL_APP_CAMPAIGN` `SettingError.MEDIA_INCOMPATIBLE_FOR_UNIVERSAL_APP_CAMPAIGN` `SettingError.TOO_MANY_EXCLAMATION_MARKS`
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`.
CampaignService	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: `metrics.average_frequency` `metrics.average_position` `metrics.impression_reach` For other available metrics, refer to this blog post.
GoogleAdsService	Updated `segments.click_type` to NOT be compatible with: `metrics.view_through_conversions`