This guide explains how Merchant API handles versioning, releases, and the
lifecycle of its different versions.

## Versioning scheme

Merchant API employs a versioning strategy at the sub-API level. This means
that each Merchant API, for example Products within the Merchant API, will
have its own version lifecycle.

### Versioning format and presentation

- **Stable sub-API versions:** If a sub-API is in a stable version then all
  its methods are in a stable version. A stable sub-API version is represented
  as **vX** (for example, **v1** , **v2**). These are production-ready major
  versions.

- **Alpha sub-API versions:** If a sub-API is in an alpha, then all its
  methods are in alpha. An alpha sub-API version is represented as
  **vXalpha** (for example, **v1alpha** , **v2alpha**). They contain
  experimental, early access features intended for testing and rapid
  iteration. Alpha versions come with no stability assurance, have no defined
  lifespan and can be changed or discontinued with a notice period of 30 days.

### Version changes

- **Major version increments** (for example, v1 to v2): These signal backward-incompatible and breaking changes, which require developer action. Only breaking changes of stable sub-APIs will have a new version number. For example, v1 to v2.
- **Minor changes:** Backward compatible additions or fixes are presented as changes to the existing major version. Such changes will be detailed in the release notes for that major version. Non-breaking additions to a sub-API will be released to the alpha channel of the latest stable version or directly to the latest stable version.

## Sunset policy

We periodically sunset older Merchant sub-API versions. We commit to a 12-month
deprecation window for stable major versions (vX), starting from the official
deprecation announcement.

For example, if we deprecate v1 of the Products sub-API on January 15,
2026, it will sunset no earlier than January 15, 2027. Beyond this date, the
earlier version of the sub-API will no longer be available for use.

## Sub-API version and lifecycle status

The following table lists the latest versions of each sub-API of Merchant API:

| Sub-API | Versions | Status |
|---|---|---|
| Accounts | v1 v1alpha | Active Active |
| Conversions | v1 | Active |
| Data sources | v1 | Active |
| Inventories | v1 | Active |
| Issue resolution | v1 | Active |
| Local feeds partnership | v1 | Active |
| Notifications | v1 | Active |
| Order tracking | v1 | Active |
| Products | v1 | Active |
| Product Studio | v1alpha | Active |
| Promotions | v1 | Active |
| Quota | v1 | Active |
| Reports | v1 | Active |
| Reviews | v1alpha | Active |

## Best practices

- Regularly check the release notes and [latest updates](https://developers.google.com/merchant/api/latest-updates) for new versions, major updates, improvements, and announcements about sub-API launches and deprecations.
- If a sub-API has two or more stable versions, we suggest using the latest version at all times.
- Design your application to gracefully handle various sub-API errors, including network issues, rate limits, and the new error codes or messages that might be introduced with newer sub-API versions.
- Don't wait until a sub-API version is about to be sunset to start planning your upgrade. Begin evaluating and testing new versions as soon as they are available.
- For feature requests or concerns about a sub-API roadmap, [reach out to us
  with questions or feedback](https://developers.google.com/merchant/api/support/give-feedback). For information about how to contact the Merchant API team for technical support, see [Get help with Merchant API](https://developers.google.com/merchant/api/support/get-help).