> [!NOTE]
> **Objective:** Learn how Google Ads API versioning works.

## Semantic versioning

The Google Ads API follows [semantic versioning](https://semver.org/) with a major and
a minor version number. Versions are written as `MAJOR.MINOR` or `vMAJOR.MINOR`.
For example, `v26.0` (or `v26`) is a major
version, while `v26.1` is a minor version.

See the [release notes](https://developers.google.com/google-ads/api/docs/release-notes) for details on current and past
versions.

### Major versions

Major release versions introduce breaking, backward-incompatible changes. The
initial release of a major version ends in zero (`vX.0`, or `vX`, where `X` is
the major version number).

Each major version has a separate REST and gRPC endpoint path (`vX`), which does
not include the minor version suffix. In the following URL, `X` is the major
version number (for example, `v26`):

    https://googleads.googleapis.com/vX

If you are upgrading from an older major version, your code may require changes
when you switch to the new major version endpoint. If you are using our
[client libraries](https://developers.google.com/google-ads/api/docs/client-libs), upgrade to the client library release
that supports the new major version. When a major version is released, we
provide an [upgrade guide](https://developers.google.com/google-ads/api/docs/upgrade) to help you resolve any breaking
changes in your code.

Examples of breaking changes include:

- 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 default values.
- Changing the error reason returned from A to B.

### Minor versions

Minor versions introduce only backward-compatible changes. For a minor version,
`vMAJOR.MINOR` has a `MINOR` number greater than zero (for example,
`v26.1`).

When a minor version is released, the existing major version endpoint
(`https://googleads.googleapis.com/vX`) is automatically updated in place. You
don't need to change the version path in your endpoint URLs, and existing code
continues to work without breaking.

Minor versions add features or updates that don't affect your existing code. To
use fields or features from a minor version with a
[client library](https://developers.google.com/google-ads/api/docs/client-libs), upgrade your client library to a release
that includes the minor version definitions.

## Deprecation and sunsets

Periodically, older Google Ads API versions are deprecated and later sunset:

- **Deprecated** : When a major version (such as `v26`) is released, all earlier major versions are marked deprecated. API calls to deprecated versions continue to succeed until their sunset date, and existing client library releases continue to support them, though subsequent client library releases omit deprecated API versions to reduce package size.
- **Sunset**: A version is disabled on its sunset date, and all API calls to its endpoint fail.

We post announcements on the [developer blog](https://ads-developers.googleblog.com/search/label/google_ads_api) in advance of version
sunsets. Check the [deprecation and sunset schedule](https://developers.google.com/google-ads/api/docs/sunset-dates) for
active, deprecated, and scheduled sunset dates.