Platform and developer

Capabilities for developer tools, authentication, webhooks and platform. 21 capabilities on this page: 18 available, 0 partly available, 3 not yet available. 2 more are not offered by design.

Each entry says what the capability does, what is missing or worth knowing where that applies, a workaround where there is a gap, and how you reach it. An entry marked Not offered by design says why and what to use instead. Scope names are explained on Merchant API scopes; How to read this catalogue defines the labels.

Developer tools

Command-line app flow

Available

The command-line tool covers scaffolding, the tunnel dev loop with dev-installs (optionally previewed through a localhost page) and their cleanup, deploy, version release, review submission and spec codegen against the live merchant contract.

Good to know:

• Automation tokens never substitute for dev-install routes.

• Routes: POST api/v1/biz/vendor/developer/apps/{app}/dev-installs, DELETE api/v1/biz/vendor/developer/apps/{app}/dev-installs/{store}, GET api/v1/biz/vendor/developer/apps/{app}/versions, POST api/v1/biz/vendor/developer/apps/{app}/versions/{version}/release, POST api/v1/biz/vendor/developer/apps/{app}/versions/{sequence}/submit

• Packages: @usequeek/cli

Dev stores and test data

Available

Developer-owned sandbox stores with a capped count, storefront password lock, rename and slug control, generated test data that can be re-run at any time to top up what is missing (pages, posts, menus, locales, orders, reviews, suppliers and more), a dev-install flow that refreshes the grant in place without re-consent, and day-one test orders: a new dev store has a region, so the dashboard Create Order, the Merchant API order create and the password-protected storefront checkout all work with no setup, using simulated money only.

Good to know:

• Capped per developer; sandboxes never transfer to merchants.

• A dev store has every plan feature switched on (suppliers, purchase orders and the other plan-gated capabilities), so you can build and test against them; a live store only has the features of its plan, and a call to a plan-gated route there is refused with an upgrade-required answer.

• Re-running the test data only creates what is missing; records you changed or added are never touched. Only the owner can run it, and an automation token cannot.

• Orders on a dev store use simulated money only: cash is recorded without a provider, and an online payment lands on a hosted test page where you choose paid or declined. Nothing is ever charged or paid out. A dev store has no bank account, so Merchant API orders pay online (name a customer); bank transfer is refused with payment_method_unavailable.

• Stock tracking is the store's own setting and is off until you turn it on; with it on, completing an order writes the normal sale movement. A store with no region refuses orders with the code store_region_missing.

• Routes: POST api/v1/biz/vendor/developer/dev-stores, POST api/v1/biz/vendor/developer/dev-stores/{store}/test-data

• Configuration: developer.max_dev_stores, developer.dev_store_location

App SDK (install, session, scopes)

Available

The app SDK covers install and webhook handling, the single embedded session-token model, typed merchant clients generated from the live spec, and the scopes catalogue.

Good to know:

• Bridge coverage is a subset: title, toast, save bar, navigation, open and product picker today.

• Routes: POST api/v1/apps/installations/{installation}/access_tokens

• Packages: @usequeek/app-sdk

AI builder toolkit and live capacity doc

Available

The AI toolkit skills fetch this live capability document before planning any app, so the building model checks what the platform can do instead of trusting memory. The document is generated from the code at build time.

Good to know:

• The toolkit points at the live doc; no capability facts are baked into skills.

• Routes: GET docs/capabilities.json

• Repositories: usequeek/queek-ai-toolkit

Authentication

App-credential API

Available

Third-party servers authenticate with a short-lived signed app token to list installations, mint installation tokens and resync.

Good to know:

• Per-app throttle after verify; per-IP failure bucket before verify.

• Routes: GET api/v1/apps/installations, POST api/v1/apps/installations/{installation}/access_tokens

Install lifecycle handoffs

Available

Signed server-to-server install, uninstall, resync, settings and scope-change events to the app URLs. Answer first, then verify: a proof call inside the handoff deadlocks. The uninstalled handoff carries data.reason store_deleted when the whole store is deleted; a merchant uninstall sends no reason.

Good to know:

• Bounded by the handoff timeout; installations flip active only after the app answers success.

• Delivery of the uninstalled handoff is queued and retried with backoff, and a store deletion does not wait for the app to answer.

• Handoff events: app/installed, app/uninstalled, app/resync, app/scopes_update, app/settings_updated

Optional scopes (request at runtime)

Available

Install grants required scopes only; optional scopes are requested after install, approved or declined by the merchant, revocable by the app, and announced over the signed scope-change handoff.

Good to know:

• Required scopes are never revocable; the merchant remedy is uninstall.

• Routes: POST api/v1/biz/vendor/app-store/{slug}/scopes/approve

• Manifest: optional_scopes

Embedded session tokens

Available

Short-lived signed tokens per installation and user for framed pages. There are no refresh tokens; the app fetches a fresh token per need.

Good to know:

• Fetch a fresh token per need; replay window is bounded and documented.

• Configuration: apps.session_token_ttl

Webhooks

Abandoned-cart topics

Available

An app can read abandoned checkouts and subscribe to checkouts/create and checkouts/update. A signed-in customer's cart is reported once it has been unchanged for the idle delay (60 minutes by default). Shopper messages have their own topic, conversation_messages/create.

Good to know:

• Events fire after a cart has been unchanged for the delay, not when it is created or edited, and a cart that keeps changing is not reported.
• Only carts of signed-in customers with a record at the store are reported, and only ones changed in the last 72 hours; guest carts, carts written only on the Queek marketplace, empty carts, carts not edited since this launched and carts of a customer the merchant deleted are not.
• A customer who placed an order after the cart last changed is not reported; abandoned payments are orders, so use orders/create and GET orders.
• A cart first built on the marketplace and later edited on the store's own channel is reported from that edit on.
• Delivery and the read need the merchant-checkouts-read grant; name, email and phone are null without merchant-customers-contact-read.
• The link is the store's checkout page, the same for every shopper, who signs in to see their cart. There are no prices, totals or per-cart recovery links.
• Delivery is at least once. An app added later is not sent carts already reported; it catches up with the list. A page walk is not a snapshot.

Workaround: Poll GET abandoned-checkouts with updated_since and deduplicate on the cart id and updated_at; use orders/create to detect completion.

• Routes: GET abandoned-checkouts
• Scopes: merchant-checkouts-read
• Webhooks: checkouts/create, checkouts/update

Orders, products, customers, inventory, locales webhooks

Available

Eighteen topics across orders, products, customers, inventory levels, locales and translations, with pinned delivery, multi-hour retry horizon and per-install echo suppression.

Good to know:

• Customer topics are additionally gated by a privacy kill-switch.

• Webhooks: orders/create, orders/paid, products/update

Delivery retries, replay and ordering

Available

Deliveries are signed, retried with backoff, and carry an event id that a retry reuses; an endpoint that keeps failing is disabled. Delivery replay exists in the merchant dashboard only.

Good to know:

• Deliveries are at-least-once and unordered; reconcile after any missed delivery.
• Replay is available in the merchant dashboard only, not through the Merchant API.
• A replay creates a new event id, so event-id deduplication alone does not make an operation idempotent.

Workaround: Dedupe on the event id and on the resource and operation, and reconcile against cursor reads.

Lifecycle as subscribable topics

Available

Install, uninstall, resync, settings and scope-change events reach an app as signed server-to-server handoffs to the URLs in its manifest. They are handoffs rather than webhook topics because an uninstalled app’s endpoint no longer exists.

Good to know:

• Handoffs need declared install and uninstall URLs and are verified by signature; they cannot be subscribed to as topics.

Workaround: Declare the handoff URLs and verify the envelope signature on your server.

• Handoff events: app/uninstalled

Erasure and redaction topics

Available

A merchant can ask, from a customer's profile in the dashboard, for the customer's data (a data request, sent at once) or for the customer's personal data to be erased (an erasure, which waits ten days so it can be cancelled, and is held until 180 days after the customer's last order). The topics customers/data_request and customers/redact carry ids only and are delivered to every active install whose manifest declares them, with no scope or approval line. Shop redaction is the app/uninstalled handoff with data.reason set to store_deleted, sent when a store is deleted.

Good to know:

• Both requests are filed by the merchant in the dashboard. An app cannot file one, and deleting an account in the Queek mobile app does not send anything to the stores that customer bought from.
• The payload has ids only: the request id, the customer id, the customer's order ids (capped, with orders_truncated) and the request time. It never carries a name, email or phone, so an app that stored data keyed only by something it collected itself cannot be addressed by id.
• Delivery is at-least-once: dedupe on data.id, which a retry or a resend after a crash reuses. Delivery follows the webhook retry schedule and stops when the app's endpoint is disabled; Queek does not wait for the app to answer and does not track completion.
• An install whose manifest listed no webhook topics when it was installed has no endpoint and cannot receive these topics until it is reinstalled.
• The erasure notice is sent when the request falls due, then Queek anonymises its own copy for that store only. Queek keeps the financial order record (customer links and addresses removed), records tied to the customer's global platform account (reviews, ratings, comments, bookmarks, assistant threads) and messaging-gateway transcripts.
• customers/delete means removed from the store's directory, not erased.
• The store-deleted handoff is sent once per installation, after the 14-day grace period, and the store name in it reads as a deleted store. Delivery is queued and retried with backoff, and a store deletion does not wait for the app to answer.

Workaround: Declare customers/data_request and customers/redact in the manifest, answer 2xx, dedupe on data.id, and on customers/redact erase the customer's data in your own storage by the ids in the payload. On app/uninstalled with reason store_deleted, delete the installation and every copy of the store's customer data.

• Webhooks: customers/data_request, customers/redact, customers/delete
• Handoff events: app/uninstalled

Platform

Analytics query and app events

Available

Apps can read up to 30 days of anonymous storefront traffic, and sales, product and customer aggregates for ranges of up to 90 days.

Good to know:

• Sales, product and customer reads cover whole days, at most 90 days, ending no later than today. Answers are cached for up to three minutes and shared by every app of the store, so a new order can take that long to show.
• Each installation may make 20 analytics reads a minute and 1,000 a day across the sales, products and customers routes; a cached answer counts too.
• Customer analytics are counts, rates and one average: no customer, name or contact is returned. Sales leaves out net revenue, fees and settlements, which are payments data.
• There is no event ingestion, report builder or query language, and no row-level order, product or customer export through analytics.

Workaround: Use the fixed aggregates; list orders or customers through their own routes for row-level data. This API does not accept events or custom reports.

• Routes: GET api/v1/merchant/analytics/traffic, GET api/v1/merchant/analytics/sales, GET api/v1/merchant/analytics/products, GET api/v1/merchant/analytics/customers
• Scopes: merchant-analytics-traffic-read, merchant-analytics-sales-read, merchant-analytics-products-read, merchant-analytics-customers-read

Workflow automation

Not yet available

Webhooks are notifications, not workflows. There is no trigger and action registry, no merchant workflow builder and no run history.

Workaround: Consume webhook events and run app-owned automation on the app server.

• Manifest: dashboard.actions

App billing and usage metering

Not yet available

Manifest pricing is display-only. There is no app-charge, recurring-billing or usage-metering API, so apps are free or bill outside Queek.

Workaround: Bill on the app-hosted page with an off-platform provider; gate features by installation in the app database.

App-owned files and uploads

Available

Apps can upload JPEG, PNG and WebP images, list the images uploaded by the same app connection, change their alt text, see where each one is used in the store and delete the ones nothing uses.

Good to know:

• Each upload is one JPEG, PNG or WebP image up to 10 MiB, 4,472 pixels on either side and 6 megapixels.
• Store up to 500 images.
• Make up to 300 uploads per day and 10 per minute.
• Use up to 256 MiB of storage counting generated sizes at three times the original.
• An app can change and delete only the images its own installation uploaded; images the merchant uploaded, or another app uploaded, answer not found.
• Only the alt text of an image can be changed. To replace a picture, upload a new image, move its users to it and delete the old one.
• An image used on a product (any image slot, a gallery, a video poster or a variant image), as the store logo or banner, or in a metafield value cannot be deleted: the answer is a conflict that lists those places. An app can never detach an image from them.
• Images placed on a storefront page or in a theme setting by address rather than by id are not tracked, so deleting such an image breaks that placement.
• Apps cannot upload documents or animated images, import a file from a URL, or accept shopper uploads.

Workaround: Downscale large photos in the app before upload, because a 12 megapixel phone photo is over the limit. For other file types or for merchant-uploaded files, use the merchant dashboard; app image settings can reference a URL.

• Routes: GET api/v1/merchant/files, POST api/v1/merchant/files, PATCH api/v1/merchant/files/{file}, GET api/v1/merchant/files/{file}/references, DELETE api/v1/merchant/files/{file}
• Scopes: merchant-media-read, merchant-media-create, merchant-media-update, merchant-media-delete

POS extensions

Not yet available

The POS is a first-party client with device sign-in and sync. App manifests have no POS target and there is no scoped POS bridge, so a third-party app cannot add tiles, cart actions or panels.

Workaround: Apps use the Merchant API where their credential permits; nothing renders inside the POS.

Realtime channel for apps

Available

Queek has no realtime channel for apps, and none is needed: an app runs its own socket server and loads it in a storefront embed, is told of new shopper messages by the conversation_messages/create webhook, and replies through the conversations API.

Good to know:

• Apps cannot publish to Queek’s own merchant or storefront channels or subscribe to visitor presence or typing.

Workaround: Run your own socket server and load it in a storefront embed; learn of new shopper messages from the webhook and reply through the conversations API.

• Routes: POST api/v1/merchant/conversations/{conversation}/messages
• Webhooks: conversation_messages/create

Registerable sales channels

Available

Apps can register channel publications and curate products and collections through the Merchant API, and imported orders carry publication attribution. Product search can be narrowed to one of the app’s publications. A headless or mobile app sells through the store’s own client API key; its orders are not attributed to a publication unless the app imports them.

Good to know:

• At most 10 publications per installation.
• At most 50 refs per write.
• Only the store’s own collections can be published; global collections are refused.
• Filtering by collection and publication covers manual collections only; smart collection membership is not listable.
• Built-in sales channels are managed by Queek and cannot be changed by apps.
• Product search can be narrowed to one of the calling installation’s publications (publication = its p_id or key); another app’s or an unknown publication answers 404, an archived one 410, and a search cursor is bound to that publication.
• Checkout attribution is not provided: an order’s publication is set only by the order import, and there is no shopper checkout context for it.
• Additions appear through a publication plus updated_after read; removals are found only by reconciling the full list, and collections are re-listed.
• Nothing is pushed to the app.

Workaround: Narrow product search to the publication, send shoppers to the store’s own product page, and import the order to record attribution.

• Routes: GET api/v1/merchant/publications, POST api/v1/merchant/publications, PATCH api/v1/merchant/publications/{publication}/resources
• Scopes: merchant-publications-read, merchant-publications-create, merchant-publications-update

App versions, review and release

Available

Apps keep immutable versions with versioned config, release control and review submission. Version history, review status, reviewer notes and the review thread can be read through the developer routes, but there is no dedicated rollback operation.

Good to know:

• There is no dedicated rollback operation.

Workaround: Drive registration, versions, release and submission through the developer routes, and list versions to see history.

• Routes: POST api/v1/biz/vendor/developer/apps/{app}/versions/{version}/release, POST api/v1/biz/vendor/developer/apps/{app}/submit

Call an AI runtime from an app

Not offered by design

Apps bring their own model. Queek does not host a model for apps to call.

App credentials have no endpoint for invoking Queek AI services, and the merchant AI tools are not an app runtime.

Good to know:

• Apps cannot invoke Queek AI through their app credentials or receive app-scoped usage and billing.

Workaround: Call an AI provider from the app server and keep provider credentials and usage controls there.

Checkout UI extensions

Not offered by design

Checkout stays one platform path so the price and the payment are exactly what the shopper saw; collect extra input on product blocks, through order attributes, or on an app page before checkout.

Apps have no surface inside the checkout flow. Checkout stays closed because pricing and payment integrity depend on one platform path.

Workaround: Collect input and payment on the app-hosted page before handing off to checkout.