Skip to content

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.

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.

  • 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 Breaking or Removed entry.
  • The error envelope is fixed: errors is an array of strings and details carries one object per error. Neither changes shape. New keys may be added.
  • The MCP server follows the same rules. A tool’s name, its method and path arguments, and the shape of its result are covered by the changelog like any action.

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.

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.

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.

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.

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.

Agents and tooling can fetch the same list as JSON, no API key needed:

GET https://app.stoqapp.com/api/v2/external/changelog.json

It 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"
}
]
}
  • breaking is true when any change is breaking or removed; deprecated is true when any change is deprecated.
  • changes[].kind is the label from the page, lower case with underscores: added, new, changed, renamed, removed, deprecated, breaking, behaviour_change, fixed, and so on. summary is an entry written as one sentence rather than a list, and note is a bullet with no label. Treat an unknown kind as informational.
  • scope is API v2, MCP, API v2 and MCP, and similar; it is null when the title names none.
  • To find what affects you: take the entries newer than your last check, keep the ones with breaking or deprecated set, and read affects and send_instead.

The same URL is listed in /llms.txt under Developer resources.

Was this page helpful?

Still stuck? Ask Quinn or chat with support