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 individual components or services within the Merchant API will have their own version lifecycle.
Versioning format and presentation
Stable sub-API versions: If a sub-API is in stable version then all its methods are in stable version. 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 alpha version, then all its methods are in alpha version. Alpha sub-API version is represented as vXalpha (for example, v1alpha, v2alpha). These are early access, experimental versions intended for testing and rapid iteration. Alpha versions come with no stability assurance and have no guaranteed lifespan. Alpha versions 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.
Sunsets
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 | Alpha versions | Beta versions | Status |
|---|---|---|---|
| Accounts | Not available | v1 beta | v1 beta version is active |
| Products | Not available | v1 beta | v1 beta version is active |
| Product inputs | Not available | v1 beta | v1 beta version is active |
| Local inventories | Not available | v1 beta | v1 beta version is active |
| Regional inventories | Not available | v1 beta | v1 beta version is active |
| Data sources | Not available | v1 beta | v1 beta version is active |
| Promotions | Not available | v1 beta | v1 beta version is active |
| Reports | Not available | v1 beta | v1 beta version is active |
| Conversions | Not available | v1 beta | v1 beta version is active |
| Notifications | Not available | v1 beta | v1 beta version is active |
| Reviews | Not available | v1 beta | v1 beta version is active |
| Shipping settings | Not available | v1 beta | v1 beta version is active |
| Product Studio | v1 alpha | Not available | v1 alpha version is active |
Best practices
- Regularly check the release notes and latest updates for new versions, major updates, improvements, and announcements about sub-API launches and deprecations.
- If a sub-API has 2 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. For information about how to contact Merchant API team for technical support, see Get help with Merchant API.