Stay organized with collections
Save and categorize content based on your preferences.
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 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 v1beta
Active To be discontinued on Feb 28, 2026
Conversions
v1 v1beta
Active To be discontinued on Feb 28, 2026
Data sources
v1 v1beta
Active To be discontinued on Feb 28, 2026
Inventories
v1 v1beta
Active To be discontinued on Feb 28, 2026
Issue resolution
v1 v1beta
Active To be discontinued on Feb 28, 2026
Local feeds partnership
v1 v1beta
Active To be discontinued on Feb 28, 2026
Notifications
v1 v1beta
Active To be discontinued on Feb 28, 2026
Order tracking
v1 v1beta
Active To be discontinued on Feb 28, 2026
Products
v1 v1beta
Active To be discontinued on Feb 28, 2026
Product Studio
v1alpha
Active
Promotions
v1 v1beta
Active To be discontinued on Feb 28, 2026
Quota
v1 v1beta
Active To be discontinued on Feb 28, 2026
Reporting
v1 v1beta
Active To be discontinued on Feb 28, 2026
Reviews
v1alpha v1beta
Active To be discontinued on Feb 28, 2026
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 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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-13 UTC."],[],[],null,["This guide explains how Merchant API handles versioning, releases, and the\nlifecycle of its different versions.\n\nVersioning scheme\n\nMerchant API employs a versioning strategy at the sub-API level. This means\nindividual components or services within the Merchant API will have their\nown version lifecycle.\n\nVersioning format and presentation\n\n- **Stable sub-API versions:** If a sub-API is in stable version then all its\n methods are in stable version. Stable sub-API version is represented as vX\n (for example, v1, v2). These are production-ready major versions.\n\n- **Alpha sub-API versions:** If a sub-API is in alpha version, then all its\n methods are in alpha version. Alpha sub-API version is represented as vXalpha\n (for example, v1alpha, v2alpha). These are early access, experimental versions\n intended for testing and rapid iteration. Alpha versions come with no\n stability assurance and have no guaranteed lifespan. Alpha versions can be\n changed or discontinued with a notice period of 30 days.\n\nVersion changes\n\n- **Major version increments (for example, v1 to v2):** These signal\n backward-incompatible and breaking changes, which require developer action.\n Only breaking changes of stable sub-APIs will have a new version number. For\n example, v1 to v2.\n\n- **Minor changes:** Backward compatible additions or fixes are presented as\n changes to the existing major version. Such changes will be detailed in the\n release notes for that major version. Non-breaking additions to a sub-API will\n be released to the alpha channel of the latest stable version or directly to\n the latest stable version.\n\nSunsets\n\nWe periodically sunset older Merchant sub-API versions. We commit to a 12-month\ndeprecation window for stable major versions (vX), starting from the official\ndeprecation announcement.\n\nFor example, if we deprecate v1 of the Products sub-API on January 15, 2026, it\nwill sunset no earlier than January 15, 2027. Beyond this date, the earlier\nversion of the sub-API will no longer be available for use.\n\nSub-API version and lifecycle status\n\nThe following table lists the latest versions of each sub-API of Merchant API:\n\n| Sub-API | Alpha versions | Beta versions | Status |\n|--------------------------|----------------|---------------|----------------------------|\n| **Accounts** | Not available | v1 beta | v1 beta version is active |\n| **Products** | Not available | v1 beta | v1 beta version is active |\n| **Product inputs** | Not available | v1 beta | v1 beta version is active |\n| **Local inventories** | Not available | v1 beta | v1 beta version is active |\n| **Regional inventories** | Not available | v1 beta | v1 beta version is active |\n| **Data sources** | Not available | v1 beta | v1 beta version is active |\n| **Promotions** | Not available | v1 beta | v1 beta version is active |\n| **Reports** | Not available | v1 beta | v1 beta version is active |\n| **Conversions** | Not available | v1 beta | v1 beta version is active |\n| **Notifications** | Not available | v1 beta | v1 beta version is active |\n| **Reviews** | Not available | v1 beta | v1 beta version is active |\n| **Shipping settings** | Not available | v1 beta | v1 beta version is active |\n| **Product Studio** | v1 alpha | Not available | v1 alpha version is active |\n\nBest practices\n\n- Regularly check the release notes and [latest\n updates](/merchant/api/latest-updates) for new versions, major updates, improvements, and announcements about sub-API launches and deprecations.\n- If a sub-API has 2 or more stable versions, we suggest using the latest version at all times.\n- 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.\n- 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.\n- For feature requests or concerns about a sub-API roadmap, [reach out to us\n with questions or feedback](/merchant/api/support/give-feedback). For information about how to contact Merchant API team for technical support, see [Get help with Merchant API](/merchant/api/support/get-help)."]]
