Widget and API reference

01Create and check an API key

1. Open Developers in Supplier Admin or Retailer Admin.
2. Create a key with api:read or api:write.
3. Save the secret when it appears; the list only shows masked keys.
4. Keep it on your server.

curl https://api.test.stockisto.com/api/public/v1/ping \
  -H "Authorization: Bearer $STOCKISTO_API_KEY"

OpenAPI JSON · Scalar

02Rate limits

03Errors

Errors use application/problem+json. A 401 means the key is missing or invalid; 403 means its scope is insufficient. A 402 names the required feature. A 429 carries Retry-After.

{
    "title": "Payment Required",
    "status": 402,
    "feature_required": true,
    "feature_key": "api.access"
}

04Pages of results

Public API lists take limit (1 to 200, default 50) and cursor. Send the response’s nextCursor as the next request’s cursor, until it is null. Keep the cursor unchanged. A malformed cursor returns 400.

curl 'https://api.test.stockisto.com/api/public/v1/stock?limit=1' \
  -H "Authorization: Bearer $STOCKISTO_API_KEY"

{ "data": [], "nextCursor": null }

05Versions

The version is in the path: /api/public/v1. Read the changelog before updating your integration.

06TEST and production

Every executable example uses TEST. Use the origins in your generated snippet and your own environment’s keys. Production MCP starts at go-live.

07The widget contract

• The script loads asynchronously into a Shadow DOM host.

• Saved embeds resolve before language, shape and data source selection.

• Unknown types or views are refused.

• Boot errors stamp data-stockisto-error on the script.

• Without a source, it reads missing-data-source and paints nothing.

• The mount keeps a hidden sentinel so div:empty host rules cannot hide it.

• Analytics sends only with data-analytics-consent="true".

08Which setting wins

09Check difficult host pages

Check a narrow column, loading and a refused configuration with the real widget.