StockroomAPIOpen the app
Guide

Changelog

What we may change under you, what we may not, and everything that has changed.

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

2026-09-24

  • GET /v2/receipts lists every receipt in the store, across orders, oldest update first. A new receipt, a void and a correction each move updated_at, soupdated_at_min works as a feed of deliveries. Each row names its order's number, type and supplier. invoiced=false lists the deliveries still waiting for an invoice.
  • PATCH /v2/purchase_orders/{id}/receipts/{receipt_id} records or corrects a delivery's supplier invoice (invoice_reference, invoice_total,invoice_date) and its received_at after the fact. Nothing moves in Shopify.
  • A new webhook event, receipt.updated, fires when a receipt's invoice or date is corrected, whether through the API or in the Stockroom app.
  • Order, receipt and adjustment lines can name their product by sku, barcodeor (on orders) supplier_sku instead of a Shopify id. The match ignores case and must be exactly one product. A code that matches nothing or several is 422 unknown_variant, withunknown or ambiguous on the line in details. A line that sends a product_title and no id is still a custom line, as before.
  • Every response carries an X-Request-Id header, and every error repeats it aserror.request_id. Quote it to support.

2026-09-12

  • Purchase order sends have their own limit: 10 per minute and 500 per day per store, listed inRate limits. The general write limit still applies.
  • Idempotency-Key values are scoped to the key that sent them. Two keys on one store that pick the same string no longer see each other's 409 or replay.
  • GET /v2/stock_adjustments?status= now answers 400 invalid_filter for a status it does not know, the same as the purchase order list.
  • A product_title, variant_title, sku or barcodesent on a line that names a variant_id is kept, as the reference already said; the ids on the line always come from the catalog.

Version 2, early access

The first public version. Suppliers and their catalogs, purchase orders with lines, charges, receipts and payments, stock adjustments, 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.