Dev stores
A developer-owned dev store with its own test keys, a simulated payment page, and nothing that can reach a real customer.
Create a dev store: your own standalone sandbox for building against the API. Build against it first. Its orders never touch real money, real customers or real deliveries, and its keys cannot reach a live store.
There is no flag to flip on a live request. Test mode is a property of the store your key belongs to, which is what makes the containment below hold everywhere at once.
Creating one
You create it in the Queek dashboard under Developers → Dev stores → Create, and it is yours as a developer — never a copy of a live merchant store, and never promotable to one. Creating a dev store:
- starts empty, with a slug of your choosing (the suggested one is your name
plus
-dev). Generate test data seeds a dedicated edge-case fixture set — never a template clone, never a merchant's catalogue; - hands you a storefront password (shown at creation and re-viewable by you afterwards). The
storefront stays password-protected: a dev store can never be made public. It mints no key: a
sk_test_key comes from a Server or backend connection and apk_test_key from a Testing on my computer connection, both made under Channels → Headless API on the dev store; - is capped at 5 dev stores per developer. Delete one to make room for the next.
The lifecycle after that is open it (admin_url), rename it, and delete it.
Create a dev store from a script
For CI and coding agents, a dev store can be created without the dashboard.
From the command line, queek app dev --create-dev-store creates one with test data and runs your app on it
(--dev-store-name and --dev-store-address set its name and address); see
Build an app.
To call the route yourself:
POST https://api.usequeek.com/api/v1/biz/vendor/developer/dev-stores
Authorization: Bearer <developer access token>
Content-Type: application/json
Idempotency-Key: <a fresh unique value>
{ "name": "Checkout tests", "slug": "checkout-tests", "test_data": true }| Part | Detail |
|---|---|
| Caller | The signed-in developer, with the access token that queek auth login creates. This is not a Merchant API key, and an App Automation Token cannot create or list dev stores. |
name | Required, at most 60 characters. |
slug | Optional: lowercase letters, digits and dashes, at most 60 characters, and not a reserved word. It becomes the store's address. Without it, the address is the name as a slug with -dev added. |
test_data | Optional boolean. true seeds the fixture set below. |
test_as | Optional. The plan whose features the store has: all (the default, every feature) or a plan code (free, starter, ...). See Plan features. |
Idempotency-Key | Optional, and worth always sending. Retrying with the same key and body replays the first response, including the same storefront password, instead of creating a second store. The same key with a different body answers 409. |
A new store answers 201:
{
"status": "success",
"message": "Dev store created successfully",
"data": {
"id": "…",
"p_id": 1218,
"name": "Checkout tests",
"slug": "checkout-tests",
"storefront_url": "…",
"admin_url": "…",
"password_set": true,
"storefront_password": "test-…",
"test_as": "all",
"created_at": "2026-10-18T09:00:00+00:00"
}
}With test_data: true, data also carries test_data: how many of each kind were seeded
(products, collections, customers, drafts, coupons, zones, metafields and metaobjects).
p_id is the number you pass as --store. storefront_password is the lock on the store's storefront.
The creation response carries it, the CLI prints it once, and the owner can read it again from the
dev stores list (GET …/dev-stores) or in the dashboard; POST …/dev-stores/{p_id}/rotate-password
replaces it.
| Status | error_type | Cause |
|---|---|---|
| 422 | slug_taken | The address is in use. data.suggested is a free one. |
| 422 | dev_store_limit_reached | You already hold 5 dev stores. Delete one first. |
| 422 | Validation failed: a missing name, or a slug that is malformed or reserved. | |
| 403 | The caller is not a developer. | |
| 429 | Creation is limited to a small number per hour, per developer. |
The same group lists a developer's stores with GET …/dev-stores, renames one with
PATCH …/dev-stores/{p_id} (name, slug and test_as, any of them) and deletes one with DELETE …/dev-stores/{p_id}.
What test data seeds
test_data: true seeds a fixed set of edge-case fixtures, never a copy of a merchant's catalogue:
products (including ones with no image, perishable, digital, wholesale and foreign-price cases),
collections, customers, coupons, shipping zones, metafields, metaobjects and draft orders.
It seeds no pages, posts, menus or languages. Create a page or a post through the
Merchant API (POST /pages, POST /posts) when you need one.
Plan features (Test as)
A dev store is free and never on a paid plan. By default it has every plan feature
(Test as all), so you can build against plan-gated routes such as conversations.
Suppliers and purchase orders are on every plan. Most merchants are on the Free plan, so test the way they meet your app: set
Test as to a plan code and the store has exactly that plan's features, no more.
- Set it at creation (
test_asonPOST …/dev-stores), or later in the dashboard (Developers → Dev stores, the Test as column) or withPATCH …/dev-stores/{p_id}and{ "test_as": "free" }. Only the store's owner can change it. - The list response carries
test_as_options:all, then every plan code, lowest tier first. Tolerate codes you do not know. - A plan-gated route the chosen plan lacks answers
403witherror_typesubscription_feature_locked, exactly as on a live store on that plan. GET /storeon the Merchant API shows the same choice inplan.codeandplan.features.- It is a preset for the sandbox, not a subscription: nothing is billed or charged, and no subscription is created.
Test keys
Test keys carry _test_ where live keys carry _live_:
| Key | Reaches |
|---|---|
sk_test_…, pk_test_… | the dev store only |
sk_live_…, pk_live_… | the live store only |
Any key minted for the dev store carries _test_: the prefix is derived from the store at mint time,
and checked against the store on every request. A key never crosses modes: a _test_ key on a live store, or a _live_ key on a dev
store, is a 401 api_key_mode_mismatch. Going live is swapping the key — no path, header
or body changes. For a site or app built on the Headless API, the key comes
from a Testing on my computer connection (Channels → Headless API on the dev store) and
Go live creates the matching connection
on your live store.
Everything else — X-Client-Key, origins, rate limits, the reference
— is identical.
curl -i https://client.usequeek.com/v1/store/info \
-H "X-Client-Key: sk_test_your_key_here" \
-H "Accept: application/json"
# …
# X-Queek-Mode: testTelling the two apart
Every response served for a dev store carries:
X-Queek-Mode: testA live store sends no X-Queek-Mode header. The header is exposed over CORS, so browser code
can read it. Log it, and refuse to start a production build against a response that carries
it.
The storefront password
A dev store's storefront is password-protected and can never be made public. Its password is the
one shown when the store was created and re-viewable by its owner. Every store/* read for a
dev store needs the store's storefront token; a request without a valid one answers:
{
"status": "failed",
"error_code": "storefront_password_required",
"message": "This store is in development. Enter the storefront password to continue.",
"data": null,
"error": {
"code": "storefront_password_required",
"message": "This store is in development. Enter the storefront password to continue.",
"doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#storefront_password_required",
"request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45"
}
}POST /auth/storefront/password with { "password": "…" } answers a token
(data.token, valid for 24 hours). Send it as the X-Storefront-Token header, or, in a browser,
as the queek_dev_store cookie. A token opens only its own store, and rotating the store's
password makes every earlier token stop working. A wrong password is 422 wrong_password, and a
live store answers 422 password_not_required.
What a dev store cannot do
The point of the dev store is what it contains. Each of these is enforced server-side, not by convention:
| Dev store | |
|---|---|
| Payments | No provider is ever called. Checkout hands the shopper a Queek-hosted simulated payment page where you choose the outcome: paid runs the same order finalisation a real provider callback runs; declined mirrors a failed payment. A live transaction's reference is a 404 on that page. |
| Messages | No email, SMS, WhatsApp or push leaves a dev store. Order confirmations, merchant notifications and channel messages are dropped before they are sent. |
| Discovery | A dev store is never listed in the marketplace, explore, search or any other discovery surface. |
| Deliveries | No delivery is requested from a courier and no rider is dispatched. |
| Money | No settlement, payout or ledger entry is ever booked against a dev order. |
| Analytics | Storefront events are accepted and dropped — nothing counts towards views or rankings. |
| AI | Qee and AI generation work on a dev store, billed to your own developer subscription and shared across your dev stores. The first AI call creates the free subscription automatically; when the credits run out the call is a 402. |
| Own payment account | A dev store cannot enable a merchant-owned gateway (custom_gateway_store_ineligible). |
What still works
- Webhooks fire. Subscribe an endpoint to the dev store and every
orders/*topic is delivered, signed, retried and logged exactly as for a live store. This is how you prove your receiver — includingorders/paid, by choosingpaidon the simulated payment page. - The whole read API: catalogue, content, metafields, reviews, cart, once the request carries the storefront token.
- Orders from day one. A fresh dev store takes test orders without any business or payment setup: the dashboard's Create Order, the Merchant API's
POST /orders(paid on the simulated payment page) and a storefront checkout behind the password. They run the normal order flow, stock movements and webhooks. - Stock tracking starts Disabled, as on a live store. To test stock movements, set it to Track in Settings → Inventory.
- Refunds need no transaction PIN. A dev store's refunds are simulated, so the dashboard never asks for the PIN.
- Cart and
checkout_url. The shopper walks the real Queek checkout; only the payment step is simulated.
Rename, delete, retention
- Rename changes the dev store's name or slug in place. Your integration keeps working.
- Delete removes the store and its keys. Create a fresh one afterwards.
- Retention: a dev store's orders and analytics events older than 30 days are pruned automatically. The store and its keys are never pruned — only the scratch data ages out.
Error codes you will meet
error.code | Status | Cause |
|---|---|---|
api_key_mode_mismatch | 401 | A _test_ key was used against a live store or a _live_ key against a dev store. Mint a key for the store you mean. |
ai_unavailable_in_test_mode | 403 | An AI action was attempted outside a live or dev store. AI works on both. |
custom_gateway_store_ineligible | 403 | A dev (or template) store tried to enable its own payment account. |
Custom payment provider
Connect your own payment server to a store. The signed HTTP contract Queek calls to start and confirm each payment, the eight connection checks, and a complete reference server.
Versioning & errors
What v1 promises, how a change is announced, and the shape every failure answers in.