Skip to main content

Stokis API

Read-only REST API for your products, stock, suppliers, purchase orders, sales and forecasts.

1. Overview

The Stokis API gives read-only access to one workspace's data: products and their stock, suppliers, purchase orders, daily sales and demand forecasts. Use it to feed a spreadsheet, a BI tool, an ERP or an AI agent that works for the store.

WhatDetails
Base URLhttps://stokis.io/api/v1
FormatJSON over HTTPS. GET requests only.
AuthenticationAPI key in the header Authorization: Bearer sk_live_…
Who can use itWorkspaces on the Scale plan, and workspaces in their 30-day trial.
Rate limit30 requests a minute per IP address and path.

Call it from a server, a script or an agent. A web page on another site can't call it from the browser: cross-origin requests are allowed only from the Stokis app.

2. Authentication

  1. The workspace owner signs in to Stokis and opens Settings › Developers.
  2. Under Public API they choose New key and give it a name. The key starts with sk_live_ and is shown once, so copy it then.
  3. Send it with every request:
Authorization: Bearer sk_live_…

Test a new key with the API root:

curl "https://stokis.io/api/v1" \
  -H "Authorization: Bearer $STOKIS_API_KEY"
{
  "object": "api",
  "version": "v1",
  "documentation": "https://stokis.io/docs/api",
  "resources": [
    "products",
    "suppliers",
    "purchase-orders",
    "sales",
    "forecasts"
  ]
}

A key reads only its own workspace. Only the owner can create or revoke keys. Stokis stores a hash of the key, not the key itself, so a lost key can't be shown again: revoke it and create a new one. There is no OAuth and no way to create a key through the API.

3. Lists and formats

List endpoints take limit (1–100, default 50) and offset (default 0) and answer with a list object. When has_more is true, ask again with offset plus limit.

{
  "object": "list",
  "data": [
    "…"
  ],
  "has_more": true,
  "limit": 2,
  "offset": 0
}
  • Ids are Stokis ids (strings). Sales and forecasts are looked up by SKU.
  • Money is an object: { "amount": "9.90", "currency": "EUR" }, the amount a decimal string.
  • Times are ISO 8601 in UTC; days are YYYY-MM-DD.
  • Fields marked "or null" are always present and may be null.

4. Products

Products with their stock, stock status, cost and supplier. Deleted products are left out.

Product fields

FieldTypeDescription
objectstringAlways "product".
idstringStokis id of the product.
skustringSKU from the store. A combination or variation is its own product.
namestringProduct name.
referencestring or nullThe store's product reference.
barcodestring or nullEAN/UPC barcode.
stockintegerUnits in stock as Stokis last recorded them. 0 when status is untracked.
min_stockinteger or nullMinimum stock level.
max_stockinteger or nullMaximum stock level.
statusstringpaused: deactivated in Stokis; untracked: the store keeps no stock level; out_of_stock: stock is 0 or less; low: stock below min_stock; otherwise ok. Values: ok, low, out_of_stock, untracked, paused.
costmoney or nullUnit cost price.
category_pathstring or nullCategory path from the store, e.g. "Tea/Black tea".
supplier_idstring or nullId of the product's supplier.
is_activebooleanfalse when the product is paused.
created_atdate-timeWhen Stokis first saw the product.
updated_atdate-timeWhen Stokis last updated the product.

GET /api/v1/products

List products. Newest first.

ParameterInTypeDescription
limitqueryintegerItems per page, 1–100. Default 50.
offsetqueryintegerItems to skip. Default 0.

Request

curl "https://stokis.io/api/v1/products?limit=2" \
  -H "Authorization: Bearer $STOKIS_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "object": "product",
      "id": "m2x8c4q9v1z7b3n5k0w6r8ty",
      "sku": "TEA-EG-250",
      "name": "Earl Grey loose leaf tea 250 g",
      "reference": "EG250",
      "barcode": "4771234567890",
      "stock": 42,
      "min_stock": 20,
      "max_stock": 120,
      "status": "ok",
      "cost": {
        "amount": "3.40",
        "currency": "EUR"
      },
      "category_path": "Tea/Black tea",
      "supplier_id": "k3v9qz2m8xw1r7c4p6n0bd5t",
      "is_active": true,
      "created_at": "2026-03-02T09:14:00.000Z",
      "updated_at": "2026-11-16T06:02:11.000Z"
    }
  ],
  "has_more": false,
  "limit": 2,
  "offset": 0
}

GET /api/v1/products/{id}

Retrieve a product. One product by its Stokis id. 404 when nothing matches.

ParameterInTypeDescription
idpathstringThe product's Stokis id.

Request

curl "https://stokis.io/api/v1/products/m2x8c4q9v1z7b3n5k0w6r8ty" \
  -H "Authorization: Bearer $STOKIS_API_KEY"

Response

{
  "object": "product",
  "id": "m2x8c4q9v1z7b3n5k0w6r8ty",
  "sku": "TEA-EG-250",
  "name": "Earl Grey loose leaf tea 250 g",
  "reference": "EG250",
  "barcode": "4771234567890",
  "stock": 42,
  "min_stock": 20,
  "max_stock": 120,
  "status": "ok",
  "cost": {
    "amount": "3.40",
    "currency": "EUR"
  },
  "category_path": "Tea/Black tea",
  "supplier_id": "k3v9qz2m8xw1r7c4p6n0bd5t",
  "is_active": true,
  "created_at": "2026-03-02T09:14:00.000Z",
  "updated_at": "2026-11-16T06:02:11.000Z"
}

5. Suppliers

Suppliers with the same on-time rate and reliability score the app shows.

Supplier fields

FieldTypeDescription
objectstringAlways "supplier".
idstringStokis id of the supplier.
namestringSupplier name.
emailstring or nullOrdering email address.
countrystring or nullCountry.
default_currencystringISO 4217 code, the default currency of this supplier's orders.
lead_time_daysinteger or nullQuoted lead time in days.
tierstringTier the merchant gave the supplier. Values: preferred, standard, probation, blocked.
statusstringWhether the supplier is active or paused in Stokis. Values: active, paused.
on_time_percentinteger or nullShare of received purchase orders with an expected date that arrived on or before it, 0–100. null with none.
reliability_scoreinteger or null0–100, from on-time delivery, fill rate and reply time. null below 3 received orders with an expected date.
reliability_gradestring or nullBand of reliability_score: excellent 90+, good 75+, fair 60+, otherwise at-risk. Values: excellent, good, fair, at-risk.
created_atdate-timeWhen the supplier was added.

GET /api/v1/suppliers

List suppliers. By name, A to Z.

ParameterInTypeDescription
limitqueryintegerItems per page, 1–100. Default 50.
offsetqueryintegerItems to skip. Default 0.

Request

curl "https://stokis.io/api/v1/suppliers?limit=2" \
  -H "Authorization: Bearer $STOKIS_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "object": "supplier",
      "id": "k3v9qz2m8xw1r7c4p6n0bd5t",
      "name": "Nordic Leaf Trading",
      "email": "[email protected]",
      "country": "DE",
      "default_currency": "EUR",
      "lead_time_days": 10,
      "tier": "preferred",
      "status": "active",
      "on_time_percent": 92,
      "reliability_score": 95,
      "reliability_grade": "excellent",
      "created_at": "2026-02-20T11:00:00.000Z"
    }
  ],
  "has_more": false,
  "limit": 2,
  "offset": 0
}

GET /api/v1/suppliers/{id}

Retrieve a supplier. One supplier by its Stokis id. 404 when nothing matches.

ParameterInTypeDescription
idpathstringThe supplier's Stokis id.

Request

curl "https://stokis.io/api/v1/suppliers/k3v9qz2m8xw1r7c4p6n0bd5t" \
  -H "Authorization: Bearer $STOKIS_API_KEY"

Response

{
  "object": "supplier",
  "id": "k3v9qz2m8xw1r7c4p6n0bd5t",
  "name": "Nordic Leaf Trading",
  "email": "[email protected]",
  "country": "DE",
  "default_currency": "EUR",
  "lead_time_days": 10,
  "tier": "preferred",
  "status": "active",
  "on_time_percent": 92,
  "reliability_score": 95,
  "reliability_grade": "excellent",
  "created_at": "2026-02-20T11:00:00.000Z"
}

6. Purchase orders

Purchase orders in every status, drafts included. Lists leave out the lines; retrieve one order to get them.

Purchase order fields

FieldTypeDescription
objectstringAlways "purchase_order".
idstringStokis id of the purchase order.
numberstringPurchase order number, e.g. "PO-2026-0042".
statusstringUsual path: draft → awaiting (approval) → sent → confirmed → received. cancelled can happen before that; bounce: sending the email failed. Values: draft, awaiting, sent, confirmed, received, cancelled, bounce.
sourcestringauto: drafted by Stokis; manual: created by a person. Values: auto, manual.
supplier_idstringId of the supplier.
currencystringISO 4217 currency of the order.
total_amountstringOrder total as a decimal string, in currency.
expected_atdate-time or nullExpected delivery.
sent_atdate-time or nullWhen it was sent to the supplier.
received_atdate-time or nullWhen it was received.
created_atdate-timeWhen the order was created.
linesarray of objectsOrder lines. Only when you retrieve one item.
lines[].idstringLine id.
lines[].skustringSKU at the time of ordering.
lines[].namestringProduct name at the time of ordering.
lines[].qtyintegerUnits ordered.
lines[].qty_receivedintegerUnits received so far.
lines[].unit_costmoney or nullUnit cost in the order's currency.

GET /api/v1/purchase-orders

List purchase orders. Newest first, without lines.

ParameterInTypeDescription
limitqueryintegerItems per page, 1–100. Default 50.
offsetqueryintegerItems to skip. Default 0.

Request

curl "https://stokis.io/api/v1/purchase-orders?limit=2" \
  -H "Authorization: Bearer $STOKIS_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "object": "purchase_order",
      "id": "p7n2w9c4x1v8m3q6z0k5r2hb",
      "number": "PO-2026-0042",
      "status": "received",
      "source": "auto",
      "supplier_id": "k3v9qz2m8xw1r7c4p6n0bd5t",
      "currency": "EUR",
      "total_amount": "340.00",
      "expected_at": "2026-11-10T00:00:00.000Z",
      "sent_at": "2026-10-31T08:30:00.000Z",
      "received_at": "2026-11-09T13:20:00.000Z",
      "created_at": "2026-10-30T07:00:00.000Z"
    }
  ],
  "has_more": false,
  "limit": 2,
  "offset": 0
}

GET /api/v1/purchase-orders/{id}

Retrieve a purchase order. One order with its lines. 404 when nothing matches.

ParameterInTypeDescription
idpathstringThe purchase order's Stokis id.

Request

curl "https://stokis.io/api/v1/purchase-orders/p7n2w9c4x1v8m3q6z0k5r2hb" \
  -H "Authorization: Bearer $STOKIS_API_KEY"

Response

{
  "object": "purchase_order",
  "id": "p7n2w9c4x1v8m3q6z0k5r2hb",
  "number": "PO-2026-0042",
  "status": "received",
  "source": "auto",
  "supplier_id": "k3v9qz2m8xw1r7c4p6n0bd5t",
  "currency": "EUR",
  "total_amount": "340.00",
  "expected_at": "2026-11-10T00:00:00.000Z",
  "sent_at": "2026-10-31T08:30:00.000Z",
  "received_at": "2026-11-09T13:20:00.000Z",
  "created_at": "2026-10-30T07:00:00.000Z",
  "lines": [
    {
      "id": "l4c8x2v6n1m9q3z7w0k5r8bp",
      "sku": "TEA-EG-250",
      "name": "Earl Grey loose leaf tea 250 g",
      "qty": 100,
      "qty_received": 100,
      "unit_cost": {
        "amount": "3.40",
        "currency": "EUR"
      }
    }
  ]
}

7. Sales

Daily units sold for one SKU over the last 90 days, from the store's orders or a CSV import.

Sales history fields

FieldTypeDescription
objectstringAlways "sales_history".
skustringThe SKU asked for.
window_daysintegerDays covered, always 90.
dataarray of objectsOne entry per day with a sales record, oldest first. Empty for an unknown SKU.
data[].datedateDay, YYYY-MM-DD.
data[].qtyintegerUnits sold that day.

GET /api/v1/sales/{sku}

Daily sales for a SKU. The last 90 days. An unknown SKU gives an empty data array, not 404.

ParameterInTypeDescription
skupathstringThe product's SKU, exactly as in the store.

Request

curl "https://stokis.io/api/v1/sales/TEA-EG-250" \
  -H "Authorization: Bearer $STOKIS_API_KEY"

Response

{
  "object": "sales_history",
  "sku": "TEA-EG-250",
  "window_days": 90,
  "data": [
    {
      "date": "2026-11-14",
      "qty": 3
    },
    {
      "date": "2026-11-15",
      "qty": 5
    },
    {
      "date": "2026-11-16",
      "qty": 2
    }
  ]
}

8. Forecasts

Demand forecasts per SKU for the next 30 days, as the agent uses them for purchase order quantities.

Forecast fields

FieldTypeDescription
objectstringAlways "forecast".
skustringSKU.
horizon_daysintegerDays the forecast covers (30).
forecast_qtyintegerSuggested order quantity: demand over the horizon plus the lead-time and safety buffer.
demand_qtyinteger or nullExpected units sold over the horizon, before the buffer.
last_computed_atdate-timeWhen the forecast was last computed.
daily_seriesobjectDaily units behind the forecast. Only when you retrieve one item.
daily_series.observedarray of numbersUnits sold per day in the sales window used, oldest first.
daily_series.projectedarray of numbersProjected units per day over the horizon.

GET /api/v1/forecasts

List forecasts. By SKU, without the daily series.

ParameterInTypeDescription
limitqueryintegerItems per page, 1–100. Default 50.
offsetqueryintegerItems to skip. Default 0.

Request

curl "https://stokis.io/api/v1/forecasts?limit=2" \
  -H "Authorization: Bearer $STOKIS_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "object": "forecast",
      "sku": "TEA-EG-250",
      "horizon_days": 30,
      "forecast_qty": 118,
      "demand_qty": 96,
      "last_computed_at": "2026-11-17T02:00:00.000Z"
    }
  ],
  "has_more": false,
  "limit": 2,
  "offset": 0
}

GET /api/v1/forecasts/{sku}

Forecast for a SKU. One SKU's forecast with its daily series. 404 when nothing matches.

ParameterInTypeDescription
skupathstringThe product's SKU, exactly as in the store.

Request

curl "https://stokis.io/api/v1/forecasts/TEA-EG-250" \
  -H "Authorization: Bearer $STOKIS_API_KEY"

Response

{
  "object": "forecast",
  "sku": "TEA-EG-250",
  "horizon_days": 30,
  "forecast_qty": 118,
  "demand_qty": 96,
  "last_computed_at": "2026-11-17T02:00:00.000Z",
  "daily_series": {
    "observed": [
      3,
      0,
      4,
      5,
      2
    ],
    "projected": [
      3,
      3,
      3,
      3,
      3
    ]
  }
}

9. Errors

Errors use HTTP status codes. 401, 402 and 404 answer with an error object:

{
  "error": {
    "type": "auth_error",
    "message": "Invalid or revoked API key."
  }
}
StatustypeWhen
401auth_errorThe Authorization header is missing, or the key is malformed, unknown or revoked.
402auth_errorThe key is valid, but its workspace is not on the Scale plan and not in its 30-day trial.
404not_foundNo product, supplier, purchase order or forecast with that id or SKU in the key's workspace.
429—More than 30 requests in a minute (see Rate limits).
5xx—Something failed on our side; retry later.

A 5xx error has a slightly different body:

{
  "success": false,
  "error": {
    "type": "Error",
    "message": "Internal server error"
  }
}

10. Rate limits

Each IP address may make 30 requests a minute to each URL path. The query string doesn't count: /products?offset=50 shares the limit of /products, while /products/a and /products/b are counted apart. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time in milliseconds).

Over the limit the answer is 429 with this body; wait retryAfter seconds:

{
  "error": "Too many requests",
  "retryAfter": 42,
  "limit": 30,
  "remaining": 0,
  "reset": "2026-11-17T09:30:42.000Z"
}

11. Plans, trials and revoking keys

  • The API is part of the Scale plan. A workspace in its 30-day trial can use it too.
  • When the trial ends or the workspace leaves Scale, its keys stay but every call answers 402 until it is on Scale again. Nothing is deleted.
  • Revoking a key in Settings › Developers stops it at once (401). It can't be undone.
  • Keys don't expire. The app shows when each key was last used.

12. For AI agents and tools

An agent uses a key that the store owner creates and hands over; agents can't sign up by themselves.