Getting started.

Before you begin

You need a separate sandbox tenant with at least one active store, active products and variants with stock, and a running sandbox API. Production data and production keys must not be used in this preview.

1. Create a sandbox key

Sign in as a store owner in Simple Retail POS and open Apps Settings → Developer API Keys. Create a key with reports:inventory:read and select the permitted stores. No owner access token or API request is needed to create it from the app.

The secret is shown once; save it in your server-side secret manager. If you lose it, create a replacement and revoke the old key after updating your integration.

Keys are bound to one tenant and one environment. You can revoke a single key without disrupting other integrations. Do not place the key in a browser storefront, source control, URL, analytics, or logs.

2. Request inventory

Set the sandbox API origin supplied by your administrator, your own key, and a permitted store ID. The header contains the raw API key as a bearer token.

curl --request GET --url "$SANDBOX_API_BASE_URL/api/v1/public/reports/inventory?store_id=$STORE_ID&limit=50" --header "Authorization: Bearer $SANDBOX_API_KEY" --header "Accept: application/json"

Or open the interactive reference and enter the same sandbox key there. The test console sends requests directly to the sandbox API; this portal has no shared API credential or hosted request proxy.

3. Read the response

A successful response contains a data array and a page object. Quantities are decimal strings. If page.has_more is true, send page.next_cursor as the next request's cursor. The report is a current stock snapshot, not a historical balance.

{
  "data": [{
    "variant_id": "...",
    "product_id": "...",
    "product_name": "Example item",
    "variant_name": "Example size",
    "sku": "SKU-001",
    "quantity": "12.0000",
    "low_stock": false
  }],
  "page": { "has_more": false, "next_cursor": null }
}

Errors use application/problem+json and return a request_id. Expect 401 for a missing or invalid key, 403 for a missing scope, 404 for an unavailable store, and 429 when a rate limit is reached.

Security notes

The API derives the tenant from your key, not from a request field. Store IDs are checked against that tenant and any key allowlist. Sandbox and production use separate keys and databases. The interactive reference does not persist authentication in local storage; close the page when testing is complete.