Queek docs

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 a pk_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 }
PartDetail
CallerThe 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.
nameRequired, at most 60 characters.
slugOptional: 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_dataOptional boolean. true seeds the fixture set below.
test_asOptional. The plan whose features the store has: all (the default, every feature) or a plan code (free, starter, ...). See Plan features.
Idempotency-KeyOptional, 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.

Statuserror_typeCause
422slug_takenThe address is in use. data.suggested is a free one.
422dev_store_limit_reachedYou already hold 5 dev stores. Delete one first.
422Validation failed: a missing name, or a slug that is malformed or reserved.
403The caller is not a developer.
429Creation 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_as on POST …/dev-stores), or later in the dashboard (Developers → Dev stores, the Test as column) or with PATCH …/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 403 with error_type subscription_feature_locked, exactly as on a live store on that plan.
  • GET /store on the Merchant API shows the same choice in plan.code and plan.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_:

KeyReaches
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: test

Telling the two apart

Every response served for a dev store carries:

X-Queek-Mode: test

A 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
PaymentsNo 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.
MessagesNo email, SMS, WhatsApp or push leaves a dev store. Order confirmations, merchant notifications and channel messages are dropped before they are sent.
DiscoveryA dev store is never listed in the marketplace, explore, search or any other discovery surface.
DeliveriesNo delivery is requested from a courier and no rider is dispatched.
MoneyNo settlement, payout or ledger entry is ever booked against a dev order.
AnalyticsStorefront events are accepted and dropped — nothing counts towards views or rankings.
AIQee 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 accountA 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 — including orders/paid, by choosing paid on 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.codeStatusCause
api_key_mode_mismatch401A _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_mode403An AI action was attempted outside a live or dev store. AI works on both.
custom_gateway_store_ineligible403A dev (or template) store tried to enable its own payment account.

On this page