Sandbox and versions

A separate environment with demo data to build your integration without touching your real data, and the versioning policy with its Deprecation and Sunset headers.

On this page
  1. The sandbox
  2. Versioning policy
  3. The Deprecation and Sunset headers

The sandbox

A sandbox is a throwaway account, separate from yours, with the demo sales history already loaded and a write key already issued. You build and test against it with the same URL and the same routes as production; when it works, you swap the key.

Who creates it
An account administrator, from the "Developer sandbox" card under Automation → "API Keys". An API key cannot create sandboxes.
How long it lasts
7 days. Then it is erased automatically, with its data and its key. It can be erased sooner with "Delete".
How many
Up to 2 live at once per company (409 sandbox_limit_reached if you ask for a third). A trial account cannot create sandboxes.
Its limits
A trial account's: 30 SKUs, 1 key, 120 calls per minute and 200 per day.
Isolation
The sandbox key cannot reach your real account, and your real keys cannot reach the sandbox: every call is scoped to its key's account.
No way out
The sandbox cannot send email or WhatsApp to anyone.
  1. As an administrator, open Automation, "API Keys" tab, and scroll to "Developer sandbox".
  2. Press "Create sandbox". "Sandbox created" appears with two items: "Sandbox API key:" and "Login to see in the app what your calls did:" (an email and a password).
  3. Copy the key: "Shown once: copy it now.".
  4. To see in the app what your calls did, sign in with that login in another private window.
  5. When you are done, press "Delete" on its row and confirm "Delete this sandbox?". Your real data is not touched.
# 1. An administrator presses "Create sandbox" (Automation > API Keys).
#    The card shows the sandbox key ONCE, plus a login to look at it in the app.
export STOCKAI_KEY="sk_live_..."      # the SANDBOX key

# 2. Build against it exactly as against production: same URL, same routes.
curl https://app.stockai.es/api/v1/planning -H "Authorization: Bearer $STOCKAI_KEY"

# 3. When it works, swap the key for a production one. Nothing else changes.

Versioning policy

Every route lives under /api/v1. Within a version some changes can happen at any time and some never do:

May arrive without notice
A new endpoint, a new field in a response, a new optional parameter, a new error_code for a new situation. Write your client to ignore fields it does not know.
Never within v1
Removing or renaming an endpoint, a field or a parameter; changing a field's type or meaning; making an optional field required; changing an existing error_code.
A breaking change
Ships as a new version (/api/v2). The previous one keeps working for at least 12 months after the announcement.
Retiring a single endpoint
With at least 180 days of notice. It keeps working until the sunset date.

The Deprecation and Sunset headers

From the day an endpoint's retirement is announced, every response from it carries these headers, so your system learns about it from the call itself:

HTTP/1.1 200 OK
Deprecation: @1798761600
Sunset: Tue, 29 Jun 2027 00:00:00 GMT
Link: </v2/alerts>; rel="successor-version", <https://app.stockai.es/desarrolladores#versionado>; rel="deprecation"
Deprecation
When it was announced, as @ + Unix seconds (RFC 9745).
Sunset
The HTTP date after which the endpoint may disappear (RFC 8594).
Link with rel="successor-version"
The route that replaces it, when there is one.
Link with rel="deprecation"
This policy's page.

Today no endpoint is being retired, so you will not see these headers. Log response headers, or alert when Sunset appears, to find out in time the day one arrives.