Stability & Deprecation
What counts as a breaking change to STOQ API v2, the MCP tools, the STOQ.v2 storefront methods and the $app metafields and metaobjects, how a change is announced, and how to read the changelog as JSON.
BetaAPI v2 is in public beta: endpoints, fields and behaviour can change before general availability. See the changelog
Last updated
STOQ API v2 and its MCP server are in public beta (see the overview). This page says what that means for an integration today: what can change without a new version, how a change is announced, and where an agent reads the list.
What counts as a change
Section titled “What counts as a change”| Kind | Examples | Announced as |
|---|---|---|
| Additive | A new action, a new optional request field, a new response field, a new value in a response enum | New or Added in the changelog. Your client must ignore response fields and enum values it does not know. |
| Deprecation | A value, field or action that still works but has a replacement | Deprecated in the changelog. The response to a deprecated call carries a top-level warnings array that names what to send instead. |
| Breaking | A removed or renamed field or action, a changed type or meaning, a stricter validation, a changed default | Breaking, Removed or Renamed in the changelog, with What to send instead. |
A fix that makes the API do what its documentation already says is a Fixed entry, not a breaking change.
How a change is announced
Section titled “How a change is announced”- Every change that can affect an integration gets a dated entry in the API Changelog, newest first, on the day it ships. Each entry says what changed, who it affects and what to send instead.
- A deprecated call keeps working until the changelog says it is removed, and the removal gets its own
BreakingorRemovedentry. - The error envelope is fixed:
errorsis an array of strings anddetailscarries one object per error. Neither changes shape. New keys may be added. - The MCP server follows the same rules. A tool’s name, its
methodandpatharguments, and the shape of its result are covered by the changelog like any action.
The other public surfaces
Section titled “The other public surfaces”The same three kinds of change (additive, deprecation, breaking) apply to every surface below, and every change to one of them gets a changelog entry in the pull request that makes it.
MCP tools
Section titled “MCP tools”The MCP server exposes the API v2 actions through search, execute_read and execute_write, plus the docs and widget tools. A tool’s name, its arguments (including method, path and params), its annotations and the shape of its result are covered like an API v2 action: renaming a tool or argument, removing one, or changing what a result contains is breaking and is listed under MCP in the changelog. New tools, new optional arguments and new result fields are additive. Because search reads the live action registry, a change to an API v2 action is a change to what the MCP tools can do.
STOQ.v2 storefront methods
Section titled “STOQ.v2 storefront methods”The names under window.STOQ.v2 and their types in stoq.d.ts are the stable storefront API. Adding a method, an option or an event is additive. Removing or renaming a method, changing what its promise resolves or rejects with, or changing an event’s name or detail is breaking.
The older window._RestockRocket functions are not removed: each STOQ.v2 method calls the legacy function by name, so the legacy name keeps working for as long as the method that wraps it does. If a legacy name is ever retired, that is a breaking entry in the changelog that names the STOQ.v2 method to use.
Deprecations of storefront methods are announced in the docs and the changelog. The storefront code does not log a console warning today, so do not rely on one to find a deprecated call.
$app metafields and metaobjects
Section titled “$app metafields and metaobjects”The metafields and the $app:offer metaobject that STOQ writes to a store are described in the storefront data contract, and each field is marked stable or internal there. Changing a stable field (its name, type, meaning or whether it can be null) is breaking. Adding a field or a new enum value is not. Fields marked internal can change without notice. The contract file carries its own version and changelog; a change to a stable field needs a new version there as well as an entry in the API changelog.
During the beta
Section titled “During the beta”v2 is in public beta, so a breaking change can ship without a fixed notice period. What is guaranteed is the record: it is in the changelog the day it ships, with the replacement. Pin only what you can adjust, and subscribe to the changelog (below) so a change is a diff you can read rather than a surprise.
The notice period for deprecated and removed behaviour at general availability is announced on this page and in the changelog before GA. Until then, do not assume a window.
Reading the changelog as data
Section titled “Reading the changelog as data”Agents and tooling can fetch the same list as JSON, no API key needed:
GET https://app.stoqapp.com/api/v2/external/changelog.jsonIt is generated from the changelog page, so the two cannot disagree. Newest entry first:
{ "policy": "https://docs.stoqapp.com/v2/docs/api-v2/stability-and-deprecation/", "doc": "https://docs.stoqapp.com/docs/api-changelog/", "entries": [ { "date": "2026-10-30", "scope": "API v2", "title": "separate orders can be grouped by ship date", "breaking": false, "deprecated": false, "changes": [{ "kind": "added", "text": "`ship_date` for `fulfillment.separate_orders.grouping` ..." }], "affects": "integrations that set separate-order grouping. ...", "send_instead": null, "source": "STOQ-2237" } ]}breakingistruewhen any change isbreakingorremoved;deprecatedistruewhen any change isdeprecated.changes[].kindis the label from the page, lower case with underscores:added,new,changed,renamed,removed,deprecated,breaking,behaviour_change,fixed, and so on.summaryis an entry written as one sentence rather than a list, andnoteis a bullet with no label. Treat an unknown kind as informational.scopeisAPI v2,MCP,API v2 and MCP, and similar; it isnullwhen the title names none.- To find what affects you: take the entries newer than your last check, keep the ones with
breakingordeprecatedset, and readaffectsandsend_instead.
The same URL is listed in /llms.txt under Developer resources.
Thanks for letting us know.
Still stuck? Ask Quinn or chat with support