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 monthsminor 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 table below 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 Sep/Oct 2024 Jan/Feb 2025 September 2025
v17.1 Jul/Aug 2024 Sep/Oct 2024 May 2025
v17 May/Jun 2024 Sep/Oct 2024 May 2025
v16.1 Apr/May 2024 May/Jun 2024 January 2025
v16 February 21, 2024 May/Jun 2024 January 2025
v15 October 18, 2023 February 21, 2024 September 25, 2024 Upgrade from v15 to v16
v14.1 August 9, 2023 October 18, 2023 June 5, 2024
v14 June 7, 2023 October 18, 2023 June 5, 2024 Upgrade from v14 to v15

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 8 to 10 months 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
v16 Min: 30.0.0
Max: -
v15 Min: 28.0.0
Max: -
v14 Min: 26.0.0
Max: -

C#

Client library for .NET
v16 Min: 18.1.0
Max: -
v15 Min: 17.1.0
Max: -
v14 Min: 16.1.0
Max: -

PHP

Client library for PHP
v16 Min: 22.1.0
Max: -
v15 Min: 21.1.0
Max: -
v14 Min: 19.2.0
Max: -

Python

Client library for Python
v15 Min: 22.1.0
Max: -
v14 Min: 21.2.0
Max: -

Ruby

Client library for Ruby
v16 Min: 27.0.0
Max: -
v15 Min: 25.0.0
Max: -
v14 Min: 23.0.0
Max: -

Perl

Client library for Perl
v16 Min: 21.0.0
Max: -
v15 Min: 19.0.0
Max: -
v14 Min: 17.0.0
Max: -

Feature deprecations

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

The table below lists the specific feature deprecations that are currently 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
Store Sales Direct uploads The Google Ads API no longer supports store sales direct uploads . October 2, 2023 You can no longer submit store sales direct uploads. Users who were previously allowlisted for this feature will now receive a CUSTOMER_NOT_ALLOWLISTED_FOR_THIS_FEATURE error. Refer to the store sales onboarding guide to determine your eligibility for ongoing store sales measurement. If eligible, work with your Google Ads account team, and refer to our updated upload store sales conversions guide.
Custom audiences types. The Google Ads API no longer supports changing the custom audience type. September 27, 2023 You can no longer update a custom audience type after you create the custom audience. For example, if you set the type to AUTO or INTEREST, then you cannot update it to the type SEARCH. This change ensures that your campaign continues to serve by making sure that your custom audience remains eligible. Modify your code so it avoids attempting to update the type of an existing CustomAudience. If your code attempts to update the type field after September 27, 2023 then the API returns a CustomAudienceError.INVALID_TYPE_CHANGE error.
Enhanced cost-per-click (eCPC) for Shopping campaigns Shopping campaigns using Enhanced cost-per-click (eCPC) will behave as if they are using Manual cost-per-click (CPC) bidding. Early October 2023 You can no longer use ManualCpc.enhanced_cpc_enabled to set the bidding strategy of Shopping campaigns to Enhanced CPC. Setting this field to true is ignored and the Shopping campaigns will behave as if they're using Manual CPC.
If you choose to not make changes to your campaign, it will operate as if it's using Manual CPC bidding. All your existing campaigns using eCPC will continue serving using the manual bids that you set.