The Calendar That Breaks Your Integration: Google Ads API Version Sunsets and Feature Deprecations

An agent that touches a Google Ads account through the API is running against a clock it did not set. Major API versions have separate endpoints and a fixed end date; on that date the endpoint stops answering. This page answers one operational question — how does an agent know when its integration will die, and how much warning does it actually get — and then shows the part of the risk the sunset calendar does *not* cover: unversioned changes, which alter behaviour without changing the version number, and which in the last twelve months shipped with a median of about a month of notice, not a year.

Access setup, tokens, and the API/Scripts/rules choice are in Managing Google Ads Programmatically — API, Scripts, and MCC, and Where an Agent Needs a Human Checkpoint. This page is only about the clock.

The Lifecycle Rules, Verbatim

[citational] — developers.google.com/google-ads/api/docs/sunset-dates, page footer "Last updated 2026-08-19 UTC", retrieved 2026-08-26. Quoted without rounding:

> 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: > > - We strive to keep at most five major versions 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 example, you can upgrade from > version (N) directly to version (N+2). > > Our client libraries support any available versions of a service, so you can > gradually upgrade by specifying different versions of used services.

And on cadence, from the same page's deprecation/sunset comparison table:

> 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.

Note what these two sentences do together: being *deprecated* is the normal state of any version older than about three months. Deprecation is not the warning shot — it is the default. The date that matters is the sunset.

Note also the modality. "We strive to keep", "We aim to sunset", "a lifespan of around" — these are stated intentions, not commitments, and this page treats them as such throughout. The only thing on these pages that behaves like a commitment is a specific cell in the timetable, and even that is published at month granularity.

The Timetable

[citational] — the version, release-date and sunset-date columns are reproduced from the table at developers.google.com/google-ads/api/docs/sunset-dates as published 2026-08-19 and retrieved 2026-08-26. Google's own table has a fourth column, "Upgrade guide"; we have substituted the release-notes anchor that each release-date cell links to, because that anchor is the stable identifier for the release.

| API version | Release date | Sunset date as published | Release-notes anchor | |---|---|---|---| | Released versions | | | | | v22 | October 15, 2025 | October 2026 (tentative) | release-notes#v22-2025-10-15 | | v23 | January 28, 2026 | February 2027 | release-notes#v23-2026-01-28 | | v23.1 | February 25, 2026 | February 2027 | release-notes#v23-1-2026-02-25 | | v23.2 | March 25, 2026 | February 2027 | release-notes#v23-2-2026-03-25 | | v24 | April 22, 2026 | May 2027 | release-notes#v24-2026-04-22 | | v24.1 | May 13, 2026 | May 2027 | release-notes#v24-1-2026-05-13 | | v24.2 | June 24, 2026 | June 2027 | release-notes#v24-2-2026-06-24 | | v25 | July 22, 2026 | August 2027 | release-notes#v25-2026-07-22 | | Upcoming versions — Google's heading; these release dates are *projected*, not facts | | | | | v25.1 | August 2026 | August 2027 | — | | v25.2 | September 2026 | August 2027 | — | | v26 | October 2026 | November 2027 | — | | v26.1\* | November 2026 | November 2027 | — |

> \* v26.1 is designated as an optional release due to overlap with the holiday > season.

A tentative date is not a deadline, and Google says so

> The tentative date means that the sunset could happen any time in that month, > and the dates could change.

[attested] — our reading of that same table, base: all 12 rows as published 2026-08-19. Only one row of twelve (v22) carries the word "tentative", yet every sunset cell in the table is month-granular — no sunset is given as a specific day, released and upcoming alike. So the caveat sentence describes a property (a sunset can land anywhere in the stated month) that the row labels do not consistently mark. Treating an unlabelled month-only sunset as a firm date is reading more precision into the table than it contains.

The four "Upcoming versions" rows are a second precision trap. Their release dates are projections of releases that have not happened. Any figure derived from them is a derivation over a plan, and this page keeps them out of its measurements rather than quietly averaging them in.

How Much Notice v22 Actually Has, Today

[attested] — arithmetic on the timetable row for v22, base: one row, as of 2026-08-26. v22's sunset is "October 2026 (tentative)". The earliest day it could fire is 2026-10-01 — 36 days from today. The latest day inside the stated month is 2026-10-31, 66 days out. An integration still pinned to https://googleads.googleapis.com/v22 therefore has a *guaranteed* remaining lifetime of about five weeks, not a year — and Google reserves the right to move even that ("the dates could change").

The general shape, same base: a version's roughly twelve-month lifespan is spent almost entirely in the deprecated state. The warning is not delivered near the end — it is the calendar, published from day one.

What Actually Happens on the Sunset Date

[citational] — sunset-dates, "Differences between deprecation and sunset":

| | Deprecation | Sunset | |---|---|---| | 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…" | "You need to upgrade from the sunset versions immediately in order to use the Google Ads API." | | API | "API endpoints for the deprecated versions still function as usual… 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 | "…we will stop including deprecated API versions in a new client library version after the deprecation date." Key Point: "Deprecated API versions are still available in previously released client library versions. You can still download and use them until the API versions are sunset." | "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." |

The client-library row is the one that bites an agent operating on a locked dependency set: the moment a version is deprecated, *new* client library releases drop it. Pinning an old library keeps a deprecated version working — until the sunset, after which nothing does.

Client Library Floors for Each Live Version

[citational] — "Supported client library versions" tables, same page, same retrieval. These are the minimum library versions; Google notes the listed minimum "is sufficient for the major Google Ads API release (such as v25)" and that minor releases may need a higher one per the linked changelog.

| Client library | v22 | v23 | v24 | v25 | |---|---|---|---|---| | Java | 41.0.0 | 42.0.0 | 43.0.0 | 44.0.0 | | .NET (C#) | 24.1.0 | 25.1.0 | 25.3.0 | 26.1.0 | | PHP | 31.0.0 | 32.2.0 | 33.3.0 | 33.6.0 | | Python | 28.1.0 | 29.2.0 | 30.1.0 | 31.2.0 | | Ruby | 36.0.0 | 38.0.0 | 40.0.0 | 43.0.0 | | Perl | 29.0.0 | 31.0.0 | 32.0.0 | 33.0.0 |

Every "Max" cell in Google's tables is -, i.e. no upper bound is stated.

How an Agent Finds Out Which Version It Is Actually Calling

This is the detection step, and it does not depend on reading the docs.

[citational] — sunset-dates, "View the versions your project is using": open APIs & Services in the Google Cloud Console, click Google Ads API, and on the METRICS subtab the Methods table lists recent calls. Google's own example of the method string is:

> google.ads.googleads.v25.services.GoogleAdsService.Mutate

The version is embedded in the method name. That string — not a config file, not an assumption about what the client library defaults to — is the ground truth for which endpoint the integration is hitting, including calls made by dependencies the agent did not write.

[citational] — the second detection channel is the announcement feed. From sunset-dates: "Subscribe to the blog for API version sunset announcement reminders." From developers.google.com/google-ads/api/docs/concepts/versioning: "Periodically, older Google Ads API versions will need to sunset. We will post notices on the developer blog when a version is about to sunset. The deprecation schedule is updated with future sunset dates."

So the documented mechanism is *pull*, not push: check the Cloud Console for your version, check the timetable for its date, subscribe to the blog. Nothing in these three pages describes a warning delivered inside the API response itself.

Minor Versions Upgrade You Without Asking

[citational] — developers.google.com/google-ads/api/docs/concepts/versioning, retrieved 2026-08-26:

> The format of the version is MAJOR.MINOR or vMAJOR_MINOR. For example, > v25_0 is a major version, while v25_1 is a minor version.

> Major release versions introduce some breaking, backwards incompatible > changes. […] Each major version has a separate endpoint. In this example URL, X > is the major version number. https://googleads.googleapis.com/vX

> Minor versions only introduce backward-compatible changes. […] When a minor > version is released, the endpoint that is already in use will automatically > be updated. This won't cause your code to break. You can continue to use your > existing client libraries.

Google's own list of what counts as a breaking change (major versions only):

> Removing or renaming a service, interface, field, method or enum value. > Changing the type of a field. Changing a resource name format. Changing the URL > format in the HTTP definition. Changing output formats such as changing from 0 > to -- as default value. Changing the error reason returned from A to B.

Consequence for an agent

you cannot pin to v24.1. The URL only carries the major number, so a caller on /v24 is silently moved onto v24.1 and then v24.2 as they ship. The timetable's separate rows for minor versions are informational — they share the major endpoint, and v23, v23.1 and v23.2 all sunset February 2027.

Measured: How Long a Version Is Actually Guaranteed to Live

[attested] — our measurement, not a Google statement. Base: the 8 "Released versions" rows only; the 4 projected rows are excluded because their release dates have not happened. Method: guaranteed lifespan = release date → first day of the stated sunset month, in days. The floor is the right quantity because the page states a sunset "could happen any time in that month"; the ceiling (last day of that month) is up to 30 days later.

| Version | Kind | Released | Sunset floor | Guaranteed days | ≈ months | |---|---|---|---|---|---| | v22 | major | 2025-10-15 | 2026-10-01 | 351 | 11.5 | | v23 | major | 2026-01-28 | 2027-02-01 | 369 | 12.1 | | v24 | major | 2026-04-22 | 2027-05-01 | 374 | 12.3 | | v25 | major | 2026-07-22 | 2027-08-01 | 375 | 12.3 | | v23.1 | minor | 2026-02-25 | 2027-02-01 | 341 | 11.2 | | v23.2 | minor | 2026-03-25 | 2027-02-01 | 313 | 10.3 | | v24.1 | minor | 2026-05-13 | 2027-05-01 | 353 | 11.6 | | v24.2 | minor | 2026-06-24 | 2027-06-01 | 342 | 11.2 |

Majors (n=4): 351–375 days. Minors (n=4): 313–353 days.

What this does to the rule of thumb. The prose says majors last "around 12 months" and minors "10 months". At the guaranteed floor:

- v22 gets 351 days — under twelve months. A major version can be shorter than "around 12 months", not longer. - v23.2 gets 313 days — 10.3 months, which is essentially the "10 months" the prose states for minors. The rule of thumb is not generous; it is roughly right at the floor. - The spread among minors is 40 days (313 to 353), driven entirely by *when in the cycle* a minor lands. A minor released one month before its major's successor cycle gets meaningfully less runway than one released just after.

Operational reading

plan from your own row, computed to the first day of the sunset month, in days. Do not compute in whole months from a month-granular sunset — that quietly grants you up to 30 days you were never promised, and it is what makes the published rule of thumb look conservative when it is not.

The Page Summary on the Live Page Contradicts the Page

[attested] — direct inspection of the retrieved HTML, 2026-08-26. The live sunset-dates page opens with a "Page Summary" panel (element devsite-key-takeaways-panel) whose heading carries data-tooltip="Generated with AI". Three of its bullets do not match the prose beneath it. Occurrence counts below are from a case-insensitive grep over the page's <article> element:

| AI "Page Summary" bullet | The page body, same URL, same day | |---|---| | "Google aims to keep at most four major versions available at any time" | "We strive to keep at most five major versions available at any one time." The string "four major" occurs once in the article — only in the summary. "five major" occurs once — only in the body. | | "There is at least a 20-week overlap between the release of client libraries for the latest version and the sunset date of the version being retired." | No such sentence exists in the body. "20-week" occurs once in the article, only in the summary. The word "overlap" occurs twice: once in that summary bullet, once in the unrelated footnote about v26.1 and the holiday season. | | Feature deprecations "such as changes to conversion environment usage and handling of gclid/gbraid values" | Neither term appears in the current deprecations table. "gclid" and "gbraid" occur once each in the article, only in the summary. |

Why this matters to an integrator, and what it does not prove. The 20-week overlap figure is the one number that would tell you how long you have *after* client libraries for the new version exist and *before* the old one dies. The live body publishes no overlap commitment of any kind, so that answer is now "read the timetable", with no stated minimum. An agent carrying a cached 20-week constant is running on a rule the current page does not state.

What we cannot show is *when* or *whether* the body ever contained it. The obvious way to date that is an archived snapshot, and archive.org was returning HTTP 503 throughout 2026-08-26 (see the provenance note), so this page makes no claim about the history of these sentences — only that, today, the generated summary and the body disagree, and the body is the authority.

Consequence

the first block of text on the page, and the block most likely to be lifted verbatim by a scraper or an LLM answering from a snippet, states rules the body contradicts. If an agent's retrieval pipeline summarises this URL, prefer the prose and the table; the panel is generated, not authoritative.

[attested] — count from the live timetable, base: the 8 "Released versions" rows as of 2026-08-26. Four major endpoints are currently live: v22, v23, v24, v25. That is under the body's stated cap of five. It coincides with the number in the AI summary, but the summary states a *cap* ("aims to keep at most four"), not a count of live versions — so the agreement is a coincidence, not corroboration.

What the Calendar Does NOT Cover: Unversioned Changes

The version timetable governs *endpoints*. It says nothing about behaviour changing underneath a version that is still perfectly alive. Google keeps those on a separate page, and points to it explicitly:

[citational] — sunset-dates, closing section: "While this page focuses on API version-level lifecycles, individual feature deprecations (such as the deprecation of Smart Campaigns) and unversioned workflow changes (such as new Demand Gen campaign budget requirements) are tracked separately."

[citational] — developers.google.com/google-ads/api/docs/deprecations ("Feature deprecations and unversioned changes", Last updated 2026-08-19 UTC, retrieved 2026-08-26). Complete table as published, with the stable identifiers Google gives, plus the per-version error enums that the linked announcement posts give and this table omits:

| Effective date as displayed | Change area | Change type | What breaks, and the identifier | |---|---|---|---| | July 2025 | Brand guidelines | Behavioral shift | For Performance Max campaigns with brand guidelines enabled (default for new campaigns), Business Name and Business Logo assets must be managed at campaign level via CampaignAsset (field types BUSINESS_NAME, LOGO) instead of at asset group level via AssetGroupAsset. Check Campaign.brand_guidelines_enabled. The announcement adds a version anchor the table omits: "enabled by default when creating PMax Campaigns using the API beginning in v21". — ads-developers.googleblog.com/2025/07/what-you-need-to-know-about-business.html | | January 2026 | Call-only ads | Deprecation | Creation of new call-only ads (CallAdInfo) no longer supported. The announcement anchors this to a version: "Starting January 2026, coinciding with the v23 API release". Table states, as a plan: "Existing call-only ads will stop serving in February 2027, and API support will be completely removed." Use Responsive Search Ads with call assets. — ads-developers.googleblog.com/2025/10/upgrade-your-call-only-ads-to.html | | February 2, 2026 | IP address and session attributes | Access restriction | New adopters sending ClickConversion.session_attributes_encoded, ClickConversion.session_attributes_key_value_pairs, or IP address via ClickConversion.user_identifiers without allowlisting fail with CUSTOMER_NOT_ALLOWLISTED_FOR_THIS_FEATURE, surfaced in partial_failure responses. Use the Data Manager API. — ads-developers.googleblog.com/2026/01/changes-to-ip-address-and-session.html | | April 1, 2026 | Customer Match | Access restriction | Developer tokens with no Customer Match requests in the qualifying window are restricted; OfflineUserDataJobService / UserDataService requests fail with CUSTOMER_NOT_ALLOWLISTED_FOR_THIS_FEATURE. Window as stated by the doc table: "between October 1, 2025 and March 31, 2026". As stated by the announcement: "between October 2025 and March 2026". — ads-developers.googleblog.com/2026/03/changes-to-customer-match-support-in.html | | April 1, 2026 | Demand Gen campaigns budget | Validation rule | Minimum daily budget of 5 USD (or local equivalent) for all Demand Gen campaigns. v21 and above: BUDGET_BELOW_DAILY_MINIMUM (see details.budget_per_day_minimum_error_details). v20: generic UNKNOWN, with the string CampaignBudgetError.BUDGET_BELOW_DAILY_MINIMUM in details.unpublished_error_code. "Existing campaigns running with less than the minimum budget are unaffected until their budget or duration in days is edited." — ads-developers.googleblog.com/2026/02/minimum-budget-requirement-for-demand.html | | June 1, 2026 | Data retention | Policy change | Granular reporting data (daily, hourly, weekly) retention reduced to 37 months; high-level data (monthly, quarterly, yearly) remains 11 years. Granular queries beyond 37 months return DateRangeError.INVALID_DATE; the announcement states that "Future API versions will return DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED". Move to segments.month / segments.quarter / segments.year. — ads-developers.googleblog.com/2026/05/new-data-retention-policy-for-google.html | | June 15, 2026 | Offline conversions | Access restriction | Developer tokens with no offline conversion upload requests in the qualifying window are restricted; ConversionUploadService.UploadClickConversions returns CUSTOMER_NOT_ALLOWLISTED_FOR_THIS_FEATURE. Window as stated by the doc table: "between December 17, 2025 and June 15, 2026". As stated by the announcement: "between December 2025 and May 2026". Migrate to the Data Manager API. — ads-developers.googleblog.com/2026/05/changes-to-offline-click-conversion.html | | September 23, 2026 | Smart Campaigns | Deprecation | "New Smart Campaigns cannot be created. Existing Smart Campaigns will continue to serve ads and can be updated." Detect via advertising_channel_type = SMART and advertising_channel_sub_type = SMART_CAMPAIGN. v24: SmartCampaignError.CREATION_FAILED. v23 and earlier: OperationAccessDeniedError.CREATE_OPERATION_NOT_PERMITTED. This date was changed after announcement — see below. — ads-developers.googleblog.com/2026/06/changes-to-support-for-smart-campaigns.html |

These are not governed by the version calendar — but several are keyed to versions. No row has a sunset date, and all of them apply to live versions. That is the point. But the common claim that unversioned changes are entirely version-independent is wrong on Google's own sources: call-only ad removal is timed to "coincide with the v23 API release", brand guidelines default "beginning in v21", and three of the eight surface different error enums depending on which version you call. An agent that pattern-matches one enum will miss the same event on a different endpoint.

Measured: Unversioned Changes Give About a Month of Notice, Not a Year

[attested] — our measurement. Base: all 8 rows of the deprecations table as published 2026-08-19 / retrieved 2026-08-26. Announcement date = the itemprop='datePublished' value on the ads-developers.googleblog.com post that row links to, fetched individually. Notice = effective − announced, in days, using the effective date as it stood on the announcement date.

| Change area | Type | Announced | Effective, as announced | Notice | |---|---|---|---|---| | Call-only ads | Deprecation | 2025-10-09 | "January 2026" | 84–111 d (see note) | | Smart Campaigns | Deprecation | 2026-06-23 | 2026-08-05 | 43 d (later moved) | | Demand Gen budget | Validation rule | 2026-02-27 | 2026-04-01 | 33 d | | Data retention | Policy change | 2026-05-01 | 2026-06-01 | 31 d | | Offline conversions | Access restriction | 2026-05-15 | 2026-06-15 | 31 d | | Customer Match | Access restriction | 2026-03-04 | 2026-04-01 | 28 d | | IP / session attributes | Access restriction | 2026-01-07 | 2026-02-02 | 26 d | | Brand guidelines | Behavioral shift | 2026-07-14 → announced 2025-07-14; effective month "July 2025" | — | not computable |

n = 7 computable, taking the call-only floor: 26, 28, 31, 31, 33, 43, 84. Median 31 days; range 26–84.

Two of these numbers need their base stated honestly rather than being reported as points:

- Call-only, 84–111 days. The table displays the effective date as "January 2026" — a month, not a day. Taking the first possible day gives 84 days. But the announcement ties the change to "the v23 API release", and the sunset-dates timetable puts that release at 2026-01-28, which gives 111 days. We report the range. A single figure here would be manufactured precision. - Smart Campaigns, 43 days as announced. The tempting figure is 92 days, from 2026-06-23 to the currently displayed 2026-09-23 — but that pairs an announcement with a date set 51 days later. See the next section.

The split still runs the wrong way for an agent, though less cleanly than the raw table suggests:

- Access restrictions — calls that worked yesterday start returning CUSTOMER_NOT_ALLOWLISTED_FOR_THIS_FEATURE — got 26, 28 and 31 days. These are the ones that break a running integration mid-flight, and they carried the shortest notice of the set. - Deprecations — a capability disappears, usually with a documented replacement — got 43 days and 84–111 days. More than the restrictions, but the 43-day case sits close to the restriction cluster, so "deprecations give you a comfortable runway" is not supportable from this sample.

Compare with a version sunset: roughly twelve months, published on a table a year ahead. The calendar an agent can plan around covers the risk that was never the urgent one.

The Effective Date Is Not a Commitment Either — and Can Move After It Passes

[citational] — first line of the Smart Campaigns announcement post, ads-developers.googleblog.com/2026/06/changes-to-support-for-smart-campaigns.html, itemprop='datePublished' = Tuesday, June 23, 2026, retrieved 2026-08-26:

> August 13, 2026 Update: The start date changed from August 5, 2026 to > September 23, 2026.

[attested] — arithmetic on that quote plus the post's publication date, base: one row. The change was announced on 2026-06-23 for 2026-08-05 (43 days' notice). On 2026-08-13 the date became 2026-09-23 — a slip of 49 days, published 8 days after the original effective date had already passed. For those 8 days the published deadline was in the past and uncorrected.

Three consequences for an agent:

1. A notice period computed today is not the notice period that was given. Pairing an announcement date with a currently displayed effective date overstates the warning by however much the date has since slipped — here, by a factor of more than two. 2. An agent that had migrated off Smart Campaigns for August 5 did unnecessary work early; an agent that trusted the table on August 6 through 12 saw a deadline it could no longer meet, which had in fact not fired. Neither state is recoverable from the table alone. Only the post carries the update line. 3. Slippage is not unique to this row. The same pattern shows up on the product side of Google Ads — see What Does NOT Work: AI Max for Search Failure Modes — where the opt-in that Google turns on for you burns budget and copy control, where the DSA sunset was pushed to February 2027. Treat every published effective date as a direction of travel with a revision history, and read the linked post, not just the table cell.

The Trap Inside Access Restrictions: Retroactive Qualifying Windows

[attested] — arithmetic on two rows of the deprecations table plus their announcement dates, base: two rows. Declared base caveat: these day counts use the doc table's day-granular window bounds; the announcement posts state the same windows at month granularity and, for offline conversions, with a different end ("December 2025 and May 2026" versus the table's "December 17, 2025 and June 15, 2026"). The sources do not agree, so the counts below are approximate to within weeks, not exact.

Both restrictions are decided by whether your developer token made a given call during a lookback window — and both windows had *already been open for months* when the rule was announced:

- Customer Match: window opens 2025-10-01 per the table, announced 2026-03-04. About 154 days of window had already run before anyone was told it existed. It closed 2026-03-31; the rule took effect the next day. - Offline conversions: window opens 2025-12-17 per the table, announced 2026-05-15 — about 149 days already elapsed at announcement.

Consequence

for these two, the notice period is not the actionable period. By announcement day, most of the behaviour that determined the outcome was already in the past. An integration that used Customer Match seasonally — or an agent that simply had no reason to call UploadClickConversions that quarter — could not retroactively earn its way out. The only defence is structural: keep a low-volume liveness call on every capability you intend to keep, or accept that idle capabilities can be revoked on a window you find out about after it opened.

What These Sources Do NOT Say

Being explicit about the gaps, because each one is a place where an agent would otherwise invent an answer:

- No error code for a post-sunset request. The docs say only that requests "will fail" and that the API "will throw an error". No HTTP status, no gRPC code, no enum name is given for hitting a sunset endpoint. (By contrast, the unversioned changes *do* name enums.) An agent cannot be written to pattern-match a specific sunset error — it must detect the condition from the calendar and the Cloud Console, not from the failure. - No in-response deprecation warning is documented. None of the three pages describes a header, a warning field, or any signal returned with a successful call telling you the version is near sunset — the words "header" and "warning" do not occur anywhere in the sunset-dates article. The documented channels are all external: the timetable, the developer blog, the Cloud Console metrics view. - No exact sunset day, ever. Every sunset in the timetable is a month. Even the row explicitly marked tentative only narrows to "any time in that month". - No minimum client-library overlap guarantee. The live body publishes none. The only place a 20-week figure appears on the page is the AI-generated summary, which the body contradicts. Do not carry it forward as a rule. - No history for these rules. We could not retrieve an archived snapshot on 2026-08-26 (archive.org was returning HTTP 503), so this page does not claim when the cap, the lifespan figures, or the overlap sentence last changed. It claims only what the live page says today, and where the live page disagrees with itself. - No commitment on the "at most five" cap. The wording is "We strive to keep". Treat the concurrent version count as an observation, not a contract. - The deprecations table is not exhaustive by construction. Google's own instruction is to "Regularly monitor the Google Ads developer blog to be the first to hear about upcoming feature deprecations" — the table lists what "occurred in recent API releases", so it is a rolling record, not a forward register. Anything announced but not yet added is invisible to a scraper of this page alone. - The table does not carry revision history. The Smart Campaigns date changed and the table shows only the current value; the fact of the change lives in the linked post. - Statements about the future are plans. "Existing call-only ads will stop serving in February 2027", "API support will be completely removed", "Future API versions will return DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED" — all of these are Google's stated intentions, published before the fact, and at least one comparable date has already moved. - This page does not cover product-level sunsets that happen in the Google Ads product rather than the API surface — for those, see What Does NOT Work: AI Max for Search Failure Modes — where the opt-in that Google turns on for you burns budget and copy control, which tracks the DSA / ACA auto-upgrade dates. Different calendar, different page, same class of risk.

What Does NOT Work

- Computing a migration deadline in whole months. A month-granular sunset plus a whole-month calculation silently grants you up to 30 days nobody promised. Measured in days to the first of the sunset month, v22 gets 351 days and v23.2 gets 313 — respectively under "around 12 months" and right at the "10 months" the prose gives for minors. Compute in days, to the floor. - Deriving notice periods from the currently displayed effective date. Smart Campaigns reads as 92 days that way; as announced it was 43. Read the linked post for update lines before computing anything. - Scraping the deprecations table with naive text extraction. Each effective date cell begins with a hidden sort key: the Smart Campaigns cell is literally <span style="display:none">2026-08-03</span>September 23, 2026. Strip tags without dropping display:none content and you get the string 2026-08-03September 23, 2026. All 8 rows carry such a key; on 7 of them it matches the displayed date, and on Smart Campaigns it does not — a parser that takes the first date it sees books that deprecation 51 days early. The key sits near the superseded 2026-08-05 date, which is suggestive, but no source documents how these keys are maintained, so treat the displayed date as authoritative and the key as unreliable. [attested] — direct inspection of the retrieved HTML, 2026-08-26; all 8 rows checked. - Using a hidden sort key as the effective date. The same artifact makes "January 2026" look like "2026-01-01". It is a sort key, not a commitment, and the announcement for that row gives a month, not a day. - Pinning to a minor version. There is no endpoint for it. /v24 is auto-updated to v24.1 and v24.2. The only pin that exists is the major. - Treating "deprecated" as the alarm. Every version older than about three months is deprecated and works fine. Wiring an alert to deprecation status produces a permanent alarm that gets muted, and the sunset then arrives unannounced. - Assuming the client library will keep you honest. Deprecated versions stay usable in *previously released* library versions; upgrading the library for an unrelated bug fix can silently drop the version you depend on, and after the sunset no library version carries it at all. - Matching a single error enum for an unversioned change. The same event raises SmartCampaignError.CREATION_FAILED on v24 but OperationAccessDeniedError.CREATE_OPERATION_NOT_PERMITTED on v23 and earlier, and the Demand Gen budget floor is a named error on v21+ but a bare UNKNOWN on v20. Handle the set, and check details.unpublished_error_code. - Averaging the projected rows into anything. Four of the twelve timetable rows are unreleased projections. Statistics that include them describe a plan. - Quoting the page's own AI "Page Summary". As of 2026-08-26 it contradicts the body on the version cap, asserts a 20-week overlap guarantee the body does not contain, and cites feature deprecations (gclid/gbraid) absent from the deprecations table.

The Detection Routine an Agent Can Actually Run

1. Read your real version from the Cloud Console, not from config: APIs & Services → Google Ads API → METRICS → Methods; the version sits inside the method string (google.ads.googleads.v25.services.GoogleAdsService.Mutate). Do this on a schedule — a dependency upgrade can move it without a code change. 2. Look up that major version's row in the sunset timetable and diary the first day of the stated sunset month, not the last. As of today: v22 → 2026-10-01, v23/v23.1/v23.2 → 2027-02-01, v24/v24.1 → 2027-05-01, v24.2 → 2027-06-01, v25 → 2027-08-01. 3. Check the client library floor for your target version before scheduling the migration; the floors are in the table above, and minor releases can require a higher one per the linked changelog. 4. Subscribe to ads-developers.googleblog.com — it is the only documented push channel, and it is the *only* channel for unversioned changes, where the ~31-day median notice lives and where date revisions are published. 5. Re-read the deprecations page on a shorter cycle than the sunset page — monthly, given that its median notice is 31 days. A quarterly review is already too slow for an access restriction. 6. Re-open the linked announcement post, not just the table row, for any change you have diarised. The table shows the current date; only the post shows that the date moved. 7. Keep every capability you rely on warm. Customer Match and offline conversions were both restricted on idleness measured over windows that opened months before the announcement. 8. Handle unversioned-change errors as a set, per version. Match CUSTOMER_NOT_ALLOWLISTED_FOR_THIS_FEATURE in partial_failure responses as well as top-level failures, and expect different enums for the same event on different major versions. 9. Never let the agent auto-upgrade a major version unattended. Major versions carry breaking changes by definition — removed fields, changed types, changed error reasons. The error-reason change in particular means an agent's own error handling can be the thing that breaks. This belongs behind the human checkpoint described in What Does NOT Work: Letting an API/Script Agent Run Unsupervised — the Actions That Need a Human Checkpoint.

Related

- Managing Google Ads Programmatically — API, Scripts, and MCC, and Where an Agent Needs a Human Checkpoint — how the agent gets access at all (developer token, OAuth, access levels, MCC, Scripts vs API). That page chooses the integration surface; this one tells you when the surface expires. The access-level tiers described there sit on top of a versioned endpoint that has a death date. - What Does NOT Work: Letting an API/Script Agent Run Unsupervised — the Actions That Need a Human Checkpoint — the human-checkpoint argument for high-blast-radius automated actions. A major-version migration is exactly such an action: breaking changes by definition, and the error-reason changes can invalidate the agent's own failure handling. - What Does NOT Work: AI Max for Search Failure Modes — where the opt-in that Google turns on for you burns budget and copy control — the product-side counterpart: forced migrations on a fixed 2026–2027 calendar (DSA / ACA auto-upgrade), where a published sunset date has already slipped once. Same failure shape, different surface — a date you did not choose changes behaviour you did. - Google Ads Campaign Types: What Each One Is For — Picking the Right Inventory Before You Set Up or Audit an Account — where Smart Campaigns and Demand Gen sit among campaign types; two of the unversioned changes above (Smart Campaigns deprecation, Demand Gen 5 USD minimum) hit those types directly. - Conversion Tracking Fundamentals — the layer every audit and every bid strategy depends on — offline conversions and session attributes are conversion-tracking surfaces; three of the eight unversioned changes above restrict exactly those API paths.