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.
| What | Details |
|---|---|
| Base URL | https://stokis.io/api/v1 |
| Format | JSON over HTTPS. GET requests only. |
| Authentication | API key in the header Authorization: Bearer sk_live_… |
| Who can use it | Workspaces on the Scale plan, and workspaces in their 30-day trial. |
| Rate limit | 30 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
- The workspace owner signs in to Stokis and opens Settings › Developers.
- 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. - 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
| Field | Type | Description |
|---|---|---|
object | string | Always "product". |
id | string | Stokis id of the product. |
sku | string | SKU from the store. A combination or variation is its own product. |
name | string | Product name. |
reference | string or null | The store's product reference. |
barcode | string or null | EAN/UPC barcode. |
stock | integer | Units in stock as Stokis last recorded them. 0 when status is untracked. |
min_stock | integer or null | Minimum stock level. |
max_stock | integer or null | Maximum stock level. |
status | string | paused: 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. |
cost | money or null | Unit cost price. |
category_path | string or null | Category path from the store, e.g. "Tea/Black tea". |
supplier_id | string or null | Id of the product's supplier. |
is_active | boolean | false when the product is paused. |
created_at | date-time | When Stokis first saw the product. |
updated_at | date-time | When Stokis last updated the product. |
GET /api/v1/products
List products. Newest first.
| Parameter | In | Type | Description |
|---|---|---|---|
limit | query | integer | Items per page, 1–100. Default 50. |
offset | query | integer | Items 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.
| Parameter | In | Type | Description |
|---|---|---|---|
id | path | string | The 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
| Field | Type | Description |
|---|---|---|
object | string | Always "supplier". |
id | string | Stokis id of the supplier. |
name | string | Supplier name. |
email | string or null | Ordering email address. |
country | string or null | Country. |
default_currency | string | ISO 4217 code, the default currency of this supplier's orders. |
lead_time_days | integer or null | Quoted lead time in days. |
tier | string | Tier the merchant gave the supplier. Values: preferred, standard, probation, blocked. |
status | string | Whether the supplier is active or paused in Stokis. Values: active, paused. |
on_time_percent | integer or null | Share of received purchase orders with an expected date that arrived on or before it, 0–100. null with none. |
reliability_score | integer or null | 0–100, from on-time delivery, fill rate and reply time. null below 3 received orders with an expected date. |
reliability_grade | string or null | Band of reliability_score: excellent 90+, good 75+, fair 60+, otherwise at-risk. Values: excellent, good, fair, at-risk. |
created_at | date-time | When the supplier was added. |
GET /api/v1/suppliers
List suppliers. By name, A to Z.
| Parameter | In | Type | Description |
|---|---|---|---|
limit | query | integer | Items per page, 1–100. Default 50. |
offset | query | integer | Items 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.
| Parameter | In | Type | Description |
|---|---|---|---|
id | path | string | The 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
| Field | Type | Description |
|---|---|---|
object | string | Always "purchase_order". |
id | string | Stokis id of the purchase order. |
number | string | Purchase order number, e.g. "PO-2026-0042". |
status | string | Usual 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. |
source | string | auto: drafted by Stokis; manual: created by a person. Values: auto, manual. |
supplier_id | string | Id of the supplier. |
currency | string | ISO 4217 currency of the order. |
total_amount | string | Order total as a decimal string, in currency. |
expected_at | date-time or null | Expected delivery. |
sent_at | date-time or null | When it was sent to the supplier. |
received_at | date-time or null | When it was received. |
created_at | date-time | When the order was created. |
lines | array of objects | Order lines. Only when you retrieve one item. |
lines[].id | string | Line id. |
lines[].sku | string | SKU at the time of ordering. |
lines[].name | string | Product name at the time of ordering. |
lines[].qty | integer | Units ordered. |
lines[].qty_received | integer | Units received so far. |
lines[].unit_cost | money or null | Unit cost in the order's currency. |
GET /api/v1/purchase-orders
List purchase orders. Newest first, without lines.
| Parameter | In | Type | Description |
|---|---|---|---|
limit | query | integer | Items per page, 1–100. Default 50. |
offset | query | integer | Items 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.
| Parameter | In | Type | Description |
|---|---|---|---|
id | path | string | The 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
| Field | Type | Description |
|---|---|---|
object | string | Always "sales_history". |
sku | string | The SKU asked for. |
window_days | integer | Days covered, always 90. |
data | array of objects | One entry per day with a sales record, oldest first. Empty for an unknown SKU. |
data[].date | date | Day, YYYY-MM-DD. |
data[].qty | integer | Units 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.
| Parameter | In | Type | Description |
|---|---|---|---|
sku | path | string | The 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
| Field | Type | Description |
|---|---|---|
object | string | Always "forecast". |
sku | string | SKU. |
horizon_days | integer | Days the forecast covers (30). |
forecast_qty | integer | Suggested order quantity: demand over the horizon plus the lead-time and safety buffer. |
demand_qty | integer or null | Expected units sold over the horizon, before the buffer. |
last_computed_at | date-time | When the forecast was last computed. |
daily_series | object | Daily units behind the forecast. Only when you retrieve one item. |
daily_series.observed | array of numbers | Units sold per day in the sales window used, oldest first. |
daily_series.projected | array of numbers | Projected units per day over the horizon. |
GET /api/v1/forecasts
List forecasts. By SKU, without the daily series.
| Parameter | In | Type | Description |
|---|---|---|---|
limit | query | integer | Items per page, 1–100. Default 50. |
offset | query | integer | Items 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.
| Parameter | In | Type | Description |
|---|---|---|---|
sku | path | string | The 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."
}
}| Status | type | When |
|---|---|---|
| 401 | auth_error | The Authorization header is missing, or the key is malformed, unknown or revoked. |
| 402 | auth_error | The key is valid, but its workspace is not on the Scale plan and not in its 30-day trial. |
| 404 | not_found | No 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
- OpenAPI 3.1 description: /docs/api/openapi.json
- API catalog (RFC 9727): /.well-known/api-catalog
- How an agent gets access: /auth.md
- This page as markdown: send
Accept: text/markdown.
An agent uses a key that the store owner creates and hands over; agents can't sign up by themselves.