Changelog

The promise

Version 2 changes additively. Anything that would break code written against it today gets a new version, at a new path, with the old one still answering. The version is in the URL, and it is also on every webhook delivery as api_version.

We may do any of these without notice, so write your consumer to survive them:

• Add a field to a response. Do not fail on a field you do not recognise, and do not validate responses against a closed schema.
• Add an endpoint, a filter or an optional parameter.
• Add a webhook event. A subscription to ["*"] starts receiving it, so a handler that throws on an unknown event name is the thing that will break.
• Add a value to an enum - a new adjustment reason, a new charge kind. Default rather than crash.
• Reword a message. The message in an error is English prose written for a developer to read, and it can change. The code beside it cannot - branch on that.

What we will not do inside version 2:

• Remove or rename a field, an endpoint, a scope, an event or an error code.
• Change the type of a field, including turning a string amount into a number.
• Make an optional parameter required, or narrow what an existing one accepts.
• Change what an endpoint does to a store's data.

Tightening a limit is the honest exception. Rate limits and caps are published in Conventions and could move if the API is abused; a change there would be announced here first, and your code should already be handling429 rate_limited by waiting out Retry-After.

Deprecation, if it ever happens

A version stays up for at least 12 months after its replacement ships, and stores using it hear from us directly rather than finding out from a page. The contract this site renders on the reference page is the same file the Stockroom test suite holds the code to, so a field disappearing from the code without disappearing from the docs is a failing build rather than a surprise to you.

Changes

Version 2, early access

The first public version. Suppliers and their catalogs, purchase orders with lines, charges, receipts and payments, stock adjustments, a read-only mirror of the Shopify catalog, and webhooks across 24 events.

Early access means available on request rather than switched on for everyone, and it means we would rather hear about a shape that does not fit your integration now than freeze it. support@stockroom.app reaches the people who built it.