Deprecation and sunset

With the release of a new version, a deprecated version is given a sunset date, after which that version will no longer be available. Here are some other guidelines to keep in mind:

  • At most, three major versions are available at any one time.
  • Major versions have a lifespan of around 12 months—minor versions: 10 months.
  • You'll have to perform at most two upgrades per year, and you don't have to upgrade in strict sequential order—for instance, you can upgrade from version (N) directly to version (N+2).
  • The overlap between the date when all client libraries are released for the latest version and the version to be sunset is at least 20 weeks.

Our client libraries support any available versions of a service, so you can gradually upgrade by specifying different versions of used services.

Timetable

The following table lists the specific deprecation and sunset dates for each available version, and projected release dates for future versions. We encourage you to upgrade to the latest version as soon as feasible after its release.

API version Release date Deprecation date Sunset date Upgrade guide
v18 October 16, 2024 February 2025 September 24, 2025
v17.1 August 7, 2024 October 16, 2024 June 4, 2025 Upgrade from v17 to v18
v17 June 5, 2024 October 16, 2024 June 4, 2025 Upgrade from v17 to v18
v16.1 April 24, 2024 June 5, 2024 February 5, 2025 Upgrade from v16 to v17
v16 February 21, 2024 June 5, 2024 February 5, 2025 Upgrade from v16 to v17

View the versions your project is using

You can view a list of methods and services your project has recently called using the Google Cloud Console:

  1. Open the APIs & Services in the Google Cloud Console.
  2. Click Google Ads API in the table.
  3. On the METRICS subtab, you should see your recent requests plotted on each graph. You can see which methods you've sent requests to in the Methods table. The method name includes a Google Ads API version, a service, and a method name, such as google.ads.googleads.v18.services.GoogleAdsService.Mutate.
  4. (Optional) Choose the timeframe you want to view for your requests.

Differences between deprecation and sunset

TermDeprecationSunset
Definition The deprecated version is a version that is not the latest one. Once a new version is released, all previous versions will be marked deprecated. The sunset version can no longer be used. Requests sent to this version will fail on or after the sunset date.
Implication You can still use the deprecated versions until they're sunset, but the references of the deprecated versions are de-highlighted to show that they're not the latest version anymore.

We encourage you to upgrade to the latest version as soon as possible to benefit from new features.

 You need to upgrade from the sunset versions immediately in order to use the Google Ads API.

We highly recommend that you upgrade to the latest version, using the upgrade guide.
Timing On average, we release a new version every 3 to 4 months, so the given version will be deprecated after approximately 3 to 4 months. We aim to sunset a version 1 year after its release.
API API endpoints for the deprecated versions still function as usual.

You can access our API endpoints using our client libraries, REST, and so on; however, new features are not added to deprecated versions.

 API endpoints for the sunset versions stop working after the sunset dates. The Google Ads API will throw an error if you try to access the API endpoints of the sunset versions.
Client libraries For purposes of providing compact client libraries, we will stop including deprecated API versions in a new client library version after the deprecation date. This helps you save space when incorporating our client libraries in your projects. Client libraries no longer support the sunset API versions in any new client library versions after the sunset dates.
Support We provide regular support for the deprecated versions. The sunset versions are no longer supported after the sunset date.

Supported client library versions

The table shows which client libraries work with which API versions.

Java

Client library for Java
v18 Min: 34.0.0
Max: -
v17 Min: 32.0.0
Max: -
v16 Min: 30.0.0
Max: -

C#

Client library for .NET
v18 Min: 21.1.0
Max: -
v17 Min: 20.1.0
Max: -
v16 Min: 18.1.0
Max: -

PHP

Client library for PHP
v18 Min: 25.0.0
Max: -
v17 Min: 23.1.0
Max: -
v16 Min: 22.1.0
Max: -

Python

Client library for Python
v18 Min: 25.1.0
Max: -
v17 Min: 24.1.0
Max: -
v16 Min: 23.1.0
Max: -

Ruby

Client library for Ruby
v18 Min: 31.0.0
Max: -
v17 Min: 29.0.0
Max: -
v16 Min: 27.0.0
Max: -

Perl

Client library for Perl
v18 Min: 25.0.1
Max: -
v17 Min: 23.0.0
Max: -
v16 Min: 21.0.0
Max: -

Feature deprecations

Regularly monitor the Google Ads developer blog to be the first to hear about upcoming feature deprecations.

The following table lists the specific feature deprecations that are planned for the Google Ads API. More details for each deprecation can be found in the linked blog posts.

Feature Description Effective date Additional notes
Upcoming changes to page size in the Google Ads API When v16 is sunset, you will no longer be able to set the page_size field when making GoogleAdsService.Search requests. February 2025 When v16 is sunset, then all GoogleAdsService.Search requests will assume a fixed page size of 10,000 rows.
Enhanced CPC bidding strategy The Google Ads API no longer supports setting eCPC as a bidding strategy for Search and Display campaigns. October 2024 Requests to set the enhanced_cpc_enabled field to TRUE in a bidding strategy will result in a BiddingStrategyError.BIDDING_STRATEGY_NOT_SUPPORTED error. Existing campaigns with the eCPC bidding strategy will continue to run until March 15, 2025. After this day, they will be automatically migrated to Manual Cost-Per-Click (CPC).