Stockout API

The Stockout API hands your own data back as JSON over plain HTTP. Point anything that can send a header at it — a script, a spreadsheet job, a warehouse dashboard, or the generic HTTP action in Zapier, Make or n8n — and you get the same snake_case fields the backup file uses.

v1 is read-only. GET and HEAD are the only methods; there is no endpoint that creates, updates or deletes anything, and nothing you can send will change your stock. Writing through the API is a later phase — see Versioning.

Base URL

Use the first form. The second is the same function on Supabase’s shorter function hostname and behaves identically — the path parser strips either prefix — so pick one and stay on it.

https://puhxxxsdvurwavbmuhhd.supabase.co/functions/v1/api/v1/<collection>      <- use this one
https://puhxxxsdvurwavbmuhhd.functions.supabase.co/api/v1/<collection>

Your first request

curl -s -H "Authorization: Bearer $STOCKOUT_API_KEY" \
     "https://puhxxxsdvurwavbmuhhd.supabase.co/functions/v1/api/v1/items?limit=1&pretty=1"

{
  "data": [
    {
      "id": "3f6a1c88-2d54-4b31-9d0e-7a1b2c3d4e5f",
      "location_id": "8b2e40d7-1f6c-4a93-b0d1-52c9e7a4188b",
      "name": "M8 Hex Bolt 40mm",
      "sku": "BOLT-M8-40, 5012345678900",
      "category": "Fasteners",
      "quantity": 1840,
      "price_at_cost": 0.07,
      "price_at_retail": 0.19,
      "low_stock_threshold": 250,
      "low_stock_is_percent": false,
      "near_capacity_threshold": 80,
      "near_capacity_is_percent": true,
      "max_capacity": 2500,
      "description": "Zinc-plated, DIN 933.",
      "storage_location": "Aisle 3 / Bin B12",
      "tracking_type": "Quantity",
      "selected_unit": null,
      "created_at": "2026-03-02T16:40:11.004921+00:00",
      "updated_at": "2026-09-11T09:14:02.117483+00:00",
      "is_deleted": false
    }
  ],
  "next_cursor": "MjAyNi0wOS0xMVQwOToxNDowMi4xMTc0ODMrMDA6MDB8M2Y2YTFjODgtMmQ1NC00YjMxLTlkMGUtN2ExYjJjM2Q0ZTVm",
  "has_more": true
}

Every request carries an API key in the Authorization header. Keys look like sto_live_ followed by 64 hex characters. There is no other way in — a Supabase session, an anon key or a plain apikey header will not authenticate you.

Authorization: Bearer sto_live_9f3ad2c17b414e8e9a355c0b1d2e3f4471a6c8b2d0e4f6a8c1b3d5e7f9a0b2c4

Minting a key

Key management lives in the app, not on this site. It is the same screen on all three surfaces, and only Owners and Admins can see it.

1. Open Menu → Settings → Developers → API Keys in the Windows app, the Android app or the web app.
2. Tap Create Key and give it a name that says where it will be used — “Zapier – reorder sheet” beats “key 2”.
3. Copy the key from the dialog straight away. It is displayed once and is never recoverable; we only store a hash of it. Afterwards the list shows the first 13 characters (sto_live_9f3a) and when it was last used.
4. Lost it? Mint a new one and revoke the old one. There is no “show key” button anywhere, by design.

Revoking

Tap Revoke next to a key. It stops working on the next request, permanently — revoked keys stay in the list, greyed out, so the audit trail survives. A team can hold 25 active keys at a time; revoke one to free a slot.

What can go wrong

One key reads every item, price, cost, customer, supplier and work order your team has, at every location. Treat it exactly like a password:

• Keep it in an environment variable or your platform’s secret store — never hard-coded, never committed.
• Give each integration its own key, so revoking one cannot break the rest.
• Rotate by minting the new key first, switching the integration over, then revoking the old one. Revocation takes effect on the very next request.
• Check Last used in the key list now and then. A key you do not recognise using should be revoked.
• If a key ever leaks, revoke it immediately and mint a replacement. There is no way to “rotate the secret” on an existing key.

Costs and retail prices are in /v1/items and customer contact details are in /v1/customers, so a leaked key is a commercial problem as well as a privacy one. If you need a feed for something untrusted, put your own server in front of the API and hand out only the fields that job needs.

Everything your team has stocked is readable. A handful of things are not, and they are missing by decision rather than by oversight — other people’s personal data, billing plumbing, and internal bookkeeping that would only mislead an integration.

For the same reason the “who did this” columns are never projected: created_by, invited_by and their siblings hold raw account ids from our auth system, which identify a person without naming one. org_id is left off every row too, but only because it would be the same value on all of them — it is in /v1/account.

Methods

GET returns data. HEAD runs the identical request and returns the same status and headers with no body — handy for uptime checks and curl -I. OPTIONS is the CORS preflight. Every other method is 405 method_not_allowed with the hint “This API is read-only; use GET or HEAD.”

URL shapes

GET /v1                          <- discovery: the collection and endpoint lists
GET /v1/account                  <- your team, plan, members, devices, locations
GET /v1/<collection>             <- a page of rows
GET /v1/<collection>/<uuid>      <- one row by id

Anything deeper is 404 not_found (“Expected /v1/<collection> or /v1/<collection>/<id>.”). An id that is not a uuid is 400 bad_request before we ever touch the database.

Response shapes

There are exactly three. Every successful body is wrapped in data, so a list and a single row never have to be told apart by guessing.

// list
{ "data": [ { ... }, { ... } ], "next_cursor": "<opaque string or null>", "has_more": true }

// single row
{ "data": { ... } }

// error  (plus "request_id" on a 500)
{ "error": "bad_param", "hint": "'locationid' is not a supported query parameter for /v1/items." }

Response headers

The X-RateLimit-* trio is on every response decided after your key is accepted — including the 400s, the 404s and a 500. It is absent from 401, 402, 405, 503 and the 404 for a path with too many segments, all of which are decided before the limiter ever runs.

Formatting

Responses are compact by default. Add ?pretty=1 for 2-space indentation while you are exploring; leave it off in production.

JSON held in text fields

checklists.items_json and label_templates.elements_json are strings that contain JSON, not nested objects. That is deliberate: they come back byte-identical to what the backup file holds, so a value round-trips through the API and back into the app unchanged. Parse them yourself.

const res  = await fetch(`${BASE}/v1/checklists?limit=1`, { headers: AUTH });
const body = await res.json();

body.data[0].items_json;               // '[{"text":"Check oil","done":false}]'  <- a string
JSON.parse(body.data[0].items_json);   // [ { text: 'Check oil', done: false } ] <- parse it

Lists return at most limit rows (1–200, default 50) ordered by the collection’s sort column ascending, with id breaking ties. When more rows exist you get has_more: true and an opaque next_cursor; pass it back as ?cursor= to continue. When has_more is false, next_cursor is null and you are done.

The sort column is updated_at everywhere except /v1/stock-movements, which has no updated_at and sorts on ingested_at — the moment the movement reached the server, not the created_at business time the device stamped on it.

A worked example

Two rows at a time through /v1/folders, a small collection, so the rows fit whole.

curl -s -H "Authorization: Bearer $STOCKOUT_API_KEY" \
     "https://puhxxxsdvurwavbmuhhd.supabase.co/functions/v1/api/v1/folders?limit=2&pretty=1"

{
  "data": [
    {
      "id": "3f6a1c88-2d54-4b31-9d0e-7a1b2c3d4e5f",
      "location_id": "8b2e40d7-1f6c-4a93-b0d1-52c9e7a4188b",
      "name": "Winter service kit",
      "updated_at": "2026-09-11T09:14:02.117483+00:00",
      "is_deleted": false
    },
    {
      "id": "c07d5e12-9b84-4f60-83aa-11e2c6d40b97",
      "location_id": "8b2e40d7-1f6c-4a93-b0d1-52c9e7a4188b",
      "name": "Reorder next week",
      "updated_at": "2026-09-11T11:48:31.902004+00:00",
      "is_deleted": false
    }
  ],
  "next_cursor": "MjAyNi0wOS0xMVQxMTo0ODozMS45MDIwMDQrMDA6MDB8YzA3ZDVlMTItOWI4NC00ZjYwLTgzYWEtMTFlMmM2ZDQwYjk3",
  "has_more": true
}

curl -s -H "Authorization: Bearer $STOCKOUT_API_KEY" \
     "https://puhxxxsdvurwavbmuhhd.supabase.co/functions/v1/api/v1/folders?limit=2&pretty=1&cursor=MjAyNi0wOS0xMVQxMTo0ODozMS45MDIwMDQrMDA6MDB8YzA3ZDVlMTItOWI4NC00ZjYwLTgzYWEtMTFlMmM2ZDQwYjk3"

{
  "data": [
    {
      "id": "5a41b9d3-6c07-4e28-8f15-90ab3c7d6e21",
      "location_id": "8b2e40d7-1f6c-4a93-b0d1-52c9e7a4188b",
      "name": "Damaged / write-off",
      "updated_at": "2026-09-11T13:02:55.410882+00:00",
      "is_deleted": false
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Reading everything

const BASE = "https://puhxxxsdvurwavbmuhhd.supabase.co/functions/v1/api";
const AUTH = { Authorization: `Bearer ${process.env.STOCKOUT_API_KEY}` };  // server-side only

async function fetchAll(collection, params = {}) {
  const rows = [];
  let cursor = null;

  for (;;) {
    const q = new URLSearchParams({ ...params, limit: "200" });
    if (cursor) q.set("cursor", cursor);

    const res = await fetch(`${BASE}/v1/${collection}?${q}`, { headers: AUTH });

    if (res.status === 429) {                       // over the limit: wait it out and retry
      const wait = Number(res.headers.get("Retry-After") || 1);
      await new Promise(r => setTimeout(r, wait * 1000));
      continue;
    }
    if (!res.ok) {
      const err = await res.json();
      throw new Error(`${res.status} ${err.error}: ${err.hint}`);
    }

    const page = await res.json();
    rows.push(...page.data);
    if (!page.has_more) return rows;
    cursor = page.next_cursor;
  }
}

const items = await fetchAll("items", { location_id: "8b2e40d7-1f6c-4a93-b0d1-52c9e7a4188b" });

On every list

updated_since filters the same column the collection sorts on — updated_at everywhere except /v1/stock-movements, where it means “ingested since” — see the ledger. On a single-row URL only include_deleted, pretty and that collection’s own filters are accepted.

Per-collection filters

Each collection accepts only the filters listed below. They are all exact matches except sku.

Keeping a copy in step

Combine updated_since with include_deleted=true and you have an incremental sync: ask for everything that changed since your last run, apply it, and remember the newest updated_at you saw. Rows arrive oldest first, so the last row of the last page is the new watermark.

// Runs on a schedule. `since` is whatever you stored at the end of the previous run.
let since = await loadWatermark();          // e.g. "2026-09-11T09:14:02.117483+00:00"

const changed = await fetchAll("items", { updated_since: since, include_deleted: "true" });

for (const row of changed) {
  if (row.is_deleted) await removeLocally(row.id);
  else                await upsertLocally(row);
}

if (changed.length) await saveWatermark(changed[changed.length - 1].updated_at);

Re-running with a slightly old watermark is safe — you simply re-apply rows you already have. Running with a watermark from the future is not: updated_since is strictly greater-than, so anything stamped at exactly that moment is skipped. Always store a timestamp you actually received, never Date.now().

Deleting something in Stockout sets is_deleted to true and bumps updated_at; the row stays. The API returns is_deleted on every collection that has it, but hides deleted rows by default. Add include_deleted=true to see them.

This is the only way to keep an external copy honest. Poll with updated_since and include_deleted=true: a row that comes back with is_deleted: true tells you to remove your copy. Without it, a deleted row just stops appearing, and a mirror has no way to tell that apart from “nothing changed”.

A value other than true, false, 1 or 0 is 400 bad_request (“include_deleted must be true or false.”).

Every failure has the same body: a stable error code you can branch on, and a hint sentence meant for whoever is reading your logs. Branch on error, never on the wording of hint — hints get reworded, codes do not.

HTTP/1.1 400 Bad Request

{
  "error": "bad_param",
  "hint": "'locationid' is not a supported query parameter for /v1/items."
}

A 500 never leaks

If something breaks on our side you get a request_id and nothing else. The underlying database message names tables, columns and constraints and reflects your own input back at you, so it is written to our logs and never to the response.

{
  "error": "server_error",
  "hint": "Something went wrong on our side. Quote the request_id if you contact support.",
  "request_id": "6b1f0c2e-9a47-4d83-8e15-2f7c40ab9d63"
}

Handling them

const res = await fetch(`${BASE}/v1/items?limit=50`, { headers: AUTH });

if (!res.ok) {
  const err = await res.json();
  switch (err.error) {
    case "rate_limited":          // wait Retry-After seconds, then repeat the same request
      return retryAfter(res.headers.get("Retry-After"));
    case "unauthorized":          // the key is gone: stop, alert a human, do not retry
      throw new Error("Stockout API key is invalid or revoked");
    case "no_active_subscription":
      throw new Error("The Stockout subscription has lapsed");
    case "service_unavailable":   // transient on our side
    case "server_error":          // err.request_id is worth logging
      return retryWithBackoff();
    default:                      // every 400 is a bug in the request: fix the call
      throw new Error(`${res.status} ${err.error}: ${err.hint}`);
  }
}

Both buckets are checked on every request. The team bucket exists so that minting extra keys cannot multiply your quota; for the same reason a team may hold at most 25 active keys.

Windows are fixed, not sliding: the minute counter resets at the top of each minute and the daily counter at midnight UTC. X-RateLimit-Reset tells you exactly when, in unix epoch seconds.

HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1789239600

Go over and you get 429 rate_limited with a Retry-After in seconds. Wait that long and repeat the identical request.

HTTP/1.1 429 Too Many Requests
Retry-After: 34
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1789239600

{
  "error": "rate_limited",
  "hint": "60 requests per minute per API key (10000/day). Retry in 34s."
}

GET /v1

Lists every collection this API version serves, plus endpoints — the two paths that are not collections, so a client that learns the API from this document alone can still find /v1/account. Useful as a health check and to confirm a key works before wiring anything else up. It accepts pretty and nothing else.

curl -s -H "Authorization: Bearer $STOCKOUT_API_KEY" "https://puhxxxsdvurwavbmuhhd.supabase.co/functions/v1/api/v1?pretty=1"

{
  "data": {
    "version": "v1",
    "collections": [
      "items",
      "locations",
      "kits",
      "kit-components",
      "equipment",
      "equipment-log",
      "checklists",
      "checklist-log",
      "folders",
      "folder-items",
      "suppliers",
      "supplier-contacts",
      "item-suppliers",
      "customers",
      "work-orders",
      "work-order-materials",
      "work-order-equipment",
      "work-order-checklists",
      "work-order-labor",
      "work-order-activity",
      "label-templates",
      "stock-movements",
      "item-external-refs",
      "integrations"
    ],
    "endpoints": [
      "/v1",
      "/v1/account"
    ],
    "docs": "https://stockoutinventory.com/developers.html"
  }
}

GET /v1/account

Everything about the team the key belongs to, composed from several tables rather than exposed as a collection. Accepts pretty; include_deleted is tolerated and ignored. There is no /v1/account/<id> — that is a 404.

{
  "data": {
    "org": {
      "id": "1c8d3b90-4f2a-4c77-9e05-6ab1d2f34c58",
      "name": "Northgate Plumbing",
      "created_at": "2026-02-14T08:03:44.120031+00:00"
    },
    "plan": {
      "plan": "standard",
      "status": "active",
      "device_cap": 4,
      "current_period_end": "2026-10-01T00:00:00+00:00",
      "cancel_at_period_end": false
    },
    "members": [
      { "role": "owner",  "email": "dana@northgate.example",  "created_at": "2026-02-14T08:03:44.120031+00:00" },
      { "role": "user",   "email": "sam@northgate.example",   "created_at": "2026-03-01T14:22:09.771204+00:00" }
    ],
    "devices": [
      { "label": "Warehouse tablet", "platform": "Android", "last_seen_at": "2026-09-11T12:55:02.339115+00:00",
        "created_at": "2026-02-14T09:10:00.000000+00:00" }
    ],
    "locations": [
      { "id": "8b2e40d7-1f6c-4a93-b0d1-52c9e7a4188b", "name": "Main Warehouse", "is_active": true }
    ],
    "key": {
      "name": "Zapier - reorder sheet",
      "key_prefix": "sto_live_9f3a",
      "scopes": "read",
      "created_at": "2026-08-30T10:11:12.000000+00:00",
      "last_used_at": "2026-09-11T13:40:55.208844+00:00"
    },
    "rate_limit": { "per_minute": 60, "per_day": 10000, "remaining": 57 }
  }
}

Field names are the ones Stockout stores, so they match the backup file exactly. A field marked nullable can come back as JSON null; the rest are always present. org_id is stripped from every row.

Every one of these platforms ships a step that makes an arbitrary HTTP request. Because the API is ordinary REST with a bearer header and JSON responses, that step is all you need.

Settings to enter

A polling scenario

A schedule every 15 minutes, asking only for what changed, is the pattern that fits inside the rate limit comfortably and never re-processes the same row twice.

GET https://puhxxxsdvurwavbmuhhd.supabase.co/functions/v1/api/v1/items
      ?updated_since=2026-09-11T09:00:00Z
      &include_deleted=true
      &limit=200

Authorization: Bearer sto_live_...

1. Store the newest updated_at you processed and feed it back in as updated_since next run.
2. Rows come back oldest first, so the last row of the last page is your new watermark.
3. Rows with is_deleted: true are deletions — remove them on your side.
4. If has_more is true, loop with cursor before you finish the run.

The version is in the path. Everything on this page is v1, and v1 is read-only.

Changes you should expect

• New fields on existing rows and new collections can appear at any time. Ignore fields you do not recognise rather than failing on them.
• Hint wording changes freely. The error code does not — branch on that.
• Cursor encoding is an implementation detail and may change. It is opaque for exactly this reason; a cursor is only ever valid for the request that follows the one that produced it.

Changes that would need a v2

Removing or renaming a field, changing a field’s type, changing what a filter means, or changing the response envelope. If any of that ever becomes necessary it ships as /v2, and /v1 keeps working.

Writing data

Creating, updating and deleting records through the API is a planned future phase, not a current feature. Until then the apps are the only way to change anything, which is also why a leaked key cannot be used to wreck your inventory — only to read it. When write endpoints arrive they will be additive: new methods on the same paths, with the same key format and the same error vocabulary.