# Queek app capabilities (for AI agents)
Schema: 1 · sha: 1d18d3d5795fd5835cb056cfbd1a87d66213192bf3a943ec282c2464bd29a3c2
Full machine-readable document: https://api.usequeek.com/docs/capabilities.json — fetch ONE need with jq `.needs[] | select(.id=="<id>")`, never trust memory for capability facts.

## Use cases (verdict first)
### analytics_reporting — buildable
Analytics and reporting app: Store performance dashboards and event-driven insights per installation.
- platform.analytics (critical, supported)
- webhooks.core (optional, supported)
- webhooks.delivery (optional, supported)
- sync.bulk (optional, supported)

### automation — blocked
Automation app: Merchant-built workflows with app triggers and actions.
- platform.automation (critical, missing)
- webhooks.core (optional, supported)
- webhooks.delivery (optional, supported)
- sync.bulk (optional, supported)

### b2b — blocked — optional gaps: markets.currency (missing)
B2B wholesale app: Company buyers, negotiated catalogs and terms for wholesale storefronts.
- b2b.catalogs (critical, missing)
- customers.segments (optional, supported)
- discounts.checkout_validation (critical, missing)
- markets.currency (optional, missing)

### bookings — buildable
Bookings app: Availability slots on product pages, hold tokens, merchant calendar on the dashboard sheet.
- storefront.blocks (critical, supported)
- storefront.proxy (critical, supported)
- merchant.requirements (critical, supported)
- dashboard.sheets (optional, supported)
- orders.read_import_status (optional, supported)
- webhooks.core (optional, supported)

### discounts_loyalty — buildable — optional gaps: loyalty.points (missing), loyalty.gift_cards (partial)
Discounts and loyalty app: Points earning and redemption plus merchant-created discounts and coupons.
- discounts.primitives (critical, supported)
- discounts.storefront_redeem (critical, supported)
- loyalty.points (optional, missing)
- loyalty.gift_cards (optional, partial)
- customers.read (optional, supported)
- merchant.metafields (optional, supported)

### erp_accounting_sync — buildable
ERP and accounting sync: Keep an external ledger in sync with orders, stock, customers and payouts.
- orders.read_import_status (critical, supported)
- inventory.stock (critical, supported)
- customers.read (optional, supported)
- webhooks.core (critical, supported)
- webhooks.delivery (optional, supported)
- sync.bulk (optional, supported)
- sync.safety (critical, supported)
- payments.payouts (optional, supported)

### forms — buildable
Forms app: Merchant-built forms rendered on the storefront with submissions collected per installation.
- storefront.blocks (critical, supported)
- storefront.proxy (critical, supported)
- storefront.proxy_post (optional, supported)
- merchant.forms_records (critical, supported)
- platform.media (optional, supported)

### marketplace_feed — buildable — optional gaps: markets.currency (missing)
Marketplace channel feed: Publish the catalog to an external marketplace and pull its orders back in.
- channels.feed (critical, supported)
- platform.sales_channels (critical, supported)
- markets.currency (optional, missing)
- inventory.stock (critical, supported)
- orders.read_import_status (critical, supported)
- sync.safety (critical, supported)

### notifications — buildable
Notifications app: Merchant alerts from an installed app in the dashboard bell, deduplicated and rate-capped, with a link to the app’s page. Push, text, email, per-staff targeting and delivery receipts are not available to apps.
- dashboard.alerts (critical, supported)
- platform.realtime (optional, supported)
- merchant.staff (optional, supported)
- webhooks.core (optional, supported)

### payment_gateway — blocked
Payment gateway app: A third-party gateway that takes payment inside checkout and settles orders.
- payments.provider_registration (critical, supported)
- payments.session_lifecycle (critical, missing)
- payments.operations (critical, supported)
- payments.refund_events (critical, supported)
- payments.payouts (optional, supported)
- merchant.order_actions (optional, supported)
- webhooks.core (critical, supported)
- dashboard.embed (optional, supported)

### pos_extension — blocked
POS extension app: Tiles, cart actions and panels inside the point-of-sale client.
- platform.pos (critical, missing)
- developer.sdk (optional, supported)
- dashboard.alerts (optional, supported)
- webhooks.core (optional, supported)

### reviews — buildable — optional gaps: storefront.customer_account (missing)
Reviews app: Import product reviews, read every review of the store, reply to reviews and approve or hide them. Storefront display of imports requires merchant approval and an explicit choice to include unverified reviews. Queek sends no review requests on an app’s behalf: the app sends its own when the orders/fulfilled webhook announces a completed order.
- reviews.product_reviews (critical, supported)
- storefront.blocks (critical, supported)
- storefront.customer_account (optional, missing)
- dashboard.sheets (optional, supported)
- webhooks.core (optional, supported)

### sales_channel — buildable
Sales channel app: A new selling surface with its own catalog publication and attributed orders.
- platform.sales_channels (critical, supported)
- channels.feed (critical, supported)
- conversations.api (optional, supported)
- webhooks.core (optional, supported)
- platform.media (optional, supported)
- storefront.search (optional, supported)

### shipping_carrier — blocked
Shipping carrier app: Live carrier rates at checkout, label purchase, tracking on orders.
- shipping.zones (optional, supported)
- shipping.carrier_rates (critical, missing)
- shipping.fulfillment (critical, supported)
- shipping.tracking (critical, supported)
- webhooks.core (critical, supported)
- dashboard.embed (optional, supported)

### storefront_chat — buildable — optional gaps: merchant.carts (missing)
Storefront chat app: A chat bubble on the storefront with merchant inbox, visitor identity and live messages.
- storefront.embeds (critical, supported)
- storefront.proxy (critical, supported)
- platform.realtime (critical, supported)
- storefront.identity (optional, supported)
- conversations.api (optional, supported)
- merchant.carts (optional, missing)
- customers.read (optional, supported)
- dashboard.embed (optional, supported)

### subscriptions — blocked
Subscriptions app: Recurring shopper purchases with subscription plans, renewal billing and lifecycle states.
- subscriptions.selling_plans (critical, missing)
- payments.session_lifecycle (critical, missing)
- orders.read_import_status (critical, supported)

### tax — blocked — optional gaps: markets.currency (missing)
Tax app: Jurisdiction-aware tax calculation and store tax maintenance from an app.
- tax.calculation (critical, missing)
- tax.configuration (optional, supported)
- markets.currency (optional, missing)

### translation — buildable — optional gaps: markets.currency (missing)
Translation app: Translate store catalogue, pages and theme strings and serve them per published locale; policy pages stay manual-write by advisory flag and writes carry at most 100 keys per call.
- markets.translations (critical, supported)
- markets.currency (optional, missing)
- dashboard.sheets (optional, supported)
- webhooks.core (optional, supported)
- developer.cli (optional, supported)

## Needs by area (status + workaround)
### auth
- [supported] auth.app_jwt: App-credential API
- [supported] auth.handoffs: Install lifecycle handoffs
- [supported] auth.optional_scopes: Optional scopes (request at runtime)
- [supported] auth.session: Embedded session tokens

### b2b
- [missing] b2b.catalogs: Company catalogs and price lists — workaround: Keep the business-buyer mapping in the app database; it cannot change the platform price.

### channels
- [supported] channels.feed: Product feed and external order import

### content
- [supported] content.posts: Blog-post reads and markdown writes

### conversations
- [supported] conversations.api: Conversation and message API for apps — workaround: To change who answers, or to message a shopper who has not written first, use the merchant dashboard inbox.

### customers
- [supported] customers.read: Customers and followers
- [supported] customers.segments: Segments, tags and consent — workaround: Create a static segment with the matching customer ids and send the complete member list on every update. Keep any attribute that is not a customer id in the app database and write its matches into the segment.
- [supported] customers.wishlists: Customer wishlists — workaround: Build the shopper interface in your own storefront code and call the storefront wishlist endpoints with the signed-in shopper’s token. Read any customer’s list from the Merchant API with the customer detail scope.

### dashboard
- [supported] dashboard.alerts: Merchant alerts (in-app bell) — workaround: Use the bell for alerts that can wait for the merchant to open the dashboard. For urgent or targeted messages, the app contacts the merchant itself over its own channel.
- [supported] dashboard.details: App details page data
- [supported] dashboard.embed: Embedded app page with session token
- [supported] dashboard.nav: Declared app nav and pins
- [supported] dashboard.sheets: Dashboard sheet blocks, actions and print — workaround: Deep-link into the embedded app page for any target, effect or badge a sheet mount cannot express.

### developer
- [supported] developer.cli: Command-line app flow
- [supported] developer.dev_stores: Dev stores and test data
- [supported] developer.sdk: App SDK (install, session, scopes)
- [supported] developer.toolkit: AI builder toolkit and live capacity doc

### discounts
- [partial] discounts.cart_transform: Transform cart lines and bundles — workaround: Use quantity-threshold discounts for tiers, priced add-on groups for options, and a product with its own price for a fixed bundle.
- [missing] discounts.checkout_validation: App checkout validation rules — workaround: Enforce merchant-side rules through discount targeting and coupon limits when you create them.
- [supported] discounts.primitives: Discounts and coupons create/publish
- [supported] discounts.storefront_redeem: Shopper coupon redemption on the storefront — workaround: Read the paid order after checkout: its coupon_code names the discount code the shopper used (null when none) and its discount_total shows the effect. Webhooks carry the same object.

### inventory
- [supported] inventory.stock: Inventory, purchase orders and stock alerts — workaround: Use a small `limit` when listing products with many variants: each product lists all of its variants, with no per-product cap. Create and edit suppliers, and cancel a purchase order, in the merchant dashboard.

### loyalty
- [partial] loyalty.gift_cards: Gift cards and store credit — workaround: Sell the card as a product, issue a fixed-amount code on orders/paid, and when a code is partly used lower its value to the remainder and raise its usage limit. Keep any balance record in the app’s own database.
- [by design] loyalty.points: Loyalty points ledger — Apps keep their own points ledger and reward customers with discount codes created through the Merchant API. — workaround: Credit points off paid-order webhooks in the app database and reward with coupons; reconcile reversals off cancelled-order events.

### markets
- [missing] markets.currency: Regional catalogs and display currency — workaround: Run one store per currency region and convert for display on the app-hosted page.
- [supported] markets.translations: Translated commerce content — workaround: Read current digests from the translatable-resource show endpoint, echo them on write, and chunk larger jobs into batches of 100 items. Re-read after a theme publish. Policy pages accept manual writes.

### merchant
- [supported] merchant.forms_records: Forms and collected records — workaround: Use the merchant Submissions screen to review merchant-held records; an app can process only its own definitions.
- [supported] merchant.line_inputs: Shopper text declarations
- [supported] merchant.metafields: Metafields, metaobjects and app data
- [supported] merchant.order_actions: Order status, payment approval and riders
- [supported] merchant.product_addons: Priced add-on groups on products
- [supported] merchant.products: Products, variants and images
- [supported] merchant.records_read: Apps read and update their own collected records — workaround: Use the merchant Submissions screen to review merchant-held records; an app can process only its own definitions.
- [supported] merchant.requirements: Booking requirements sheet
- [supported] merchant.staff: Staff directory read
- [by design] merchant.carts: Active carts — Carts belong to the shopper session. Apps do not read live carts; they see the order once it is placed. — workaround: Share the storefront cart URL into the chat and read the converted order through the order webhooks.

### messaging
- [by design] messaging.send: Send shopper messages — Apps send through their own email or SMS provider. Queek provides consent state and events, not a send API. — workaround: Send through an app-owned provider. Read Queek’s campaign audience and channel consent state, report consent and suppression changes through the consent endpoints, and handle STOP replies with the provider.

### orders
- [supported] orders.read_import_status: Orders read, create, import and status
- [missing] orders.returns: Returns and exchanges — workaround: Handle returns in the app-hosted flow, then refund the order with POST /orders/{order}/refunds; send the returned lines in line_items to put the stock back.

### payments
- [supported] payments.operations: Refund an order
- [supported] payments.payouts: Payout and settlement reads
- [supported] payments.provider_registration: Register an app payment provider — workaround: A merchant who needs a provider Queek does not yet carry can connect one of the supported providers in the dashboard.
- [supported] payments.refund_events: Refund and payment events
- [missing] payments.session_lifecycle: Create and resolve payment sessions — workaround: An installed app can import orders already charged on its external platform with POST /orders/import. This records the payment but does not create or resolve a payment session.

### platform
- [supported] platform.analytics: Analytics query and app events — 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.
- [missing] platform.automation: Workflow automation — workaround: Consume webhook events and run app-owned automation on the app server.
- [missing] platform.billing: App billing and usage metering — workaround: Bill on the app-hosted page with an off-platform provider; gate features by installation in the app database.
- [supported] platform.media: App-owned files and 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.
- [missing] platform.pos: POS extensions — workaround: Apps use the Merchant API where their credential permits; nothing renders inside the POS.
- [supported] platform.realtime: Realtime channel for apps — 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.
- [supported] platform.sales_channels: Registerable sales channels — workaround: Narrow product search to the publication, send shoppers to the store’s own product page, and import the order to record attribution.
- [supported] platform.versions: App versions, review and release — workaround: Drive registration, versions, release and submission through the developer routes, and list versions to see history.
- [by design] platform.ai_runtime: Call an AI runtime from an app — Apps bring their own model. Queek does not host a model for apps to call. — workaround: Call an AI provider from the app server and keep provider credentials and usage controls there.
- [by design] platform.checkout_ui: Checkout UI extensions — 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. — workaround: Collect input and payment on the app-hosted page before handing off to checkout.

### reviews
- [supported] reviews.product_reviews: Product reviews: import, read, reply and moderate — workaround: Ask the merchant to switch Queek’s own review request off, then send review requests from the app’s own channel when the orders/fulfilled webhook arrives, reading the shopper’s contact and consent with the customer scopes. Ask the merchant to enable unverified reviews in the storefront blocks, summaries or testimonials that should show imports.

### shipping
- [missing] shipping.carrier_rates: Live carrier rates at checkout — workaround: Keep merchant-configured flat zones, or quote live rates on the app-hosted page before handing the shopper to checkout.
- [supported] shipping.fulfillment: Fulfil shipped orders — workaround: Subscribe to orders/paid, write carrier and tracking through the shipment endpoint, then move the order status. For self-delivery and pickup orders assign the store rider and move the status instead.
- [supported] shipping.tracking: Shipment tracking writes
- [supported] shipping.zones: Static shipping zones and rates
- [by design] shipping.delivery_customization: Tailor checkout delivery options — Queek presents one resolved Delivery option per order; shape the offer with shipping zones and the store’s own delivery settings. — workaround: Shape the offer with the merchant-configured fulfilment modes for each store.

### storefront
- [supported] storefront.blocks: Product-page app blocks
- [missing] storefront.customer_account: Shopper account extensions — workaround: Serve account-adjacent features on the app-hosted page with the customer reads.
- [supported] storefront.embeds: Site-wide storefront embeds — workaround: First-party apps can be registered through the Developer page until queek app deploy is updated to accept embeds.
- [supported] storefront.identity: Shopper identity to apps — workaround: Read the passed customer id for signed-in shoppers. For anyone else, capture identity on the app-hosted page behind the deep link from the block.
- [supported] storefront.page_composition: Compose storefront pages — workaround: Write the page as a draft through the pages API and ask the merchant to review and publish it in the storefront editor; use an app block for app-owned content in supported placements.
- [supported] storefront.proxy: Storefront app proxy (read)
- [supported] storefront.proxy_post: Storefront proxy writes — workaround: Declare allow_post and a submit element in the block schema and deploy with the queek CLI (a release newer than 0.15.5) or the Developer page. For any other surface, send the POST from storefront code on the store’s own origin or deep-link to an app-hosted page.
- [supported] storefront.search: App-scoped product search — workaround: Follow next_cursor for more products. For collections, pages and posts call the public storefront search (GET api/v1/client/store/search), which resolves the store from its host and needs no app credentials, or list collections with merchant-collections-read. Implement app-specific suggestions, synonyms and facets on the app server.
- [missing] storefront.web_pixels: Run consent-aware tracking pixels — workaround: Ask the merchant to enter the network id in the dashboard Ad pixels card, or use the app backend for server-side events it can observe through the webhooks; do not install shopper-side tracking through Queek.
- [by design] storefront.theme_assets: Manage storefront theme assets — Queek does not let apps inject scripts into storefronts or edit theme files. Use storefront embeds and product-page app blocks instead. — workaround: Use registered storefront blocks for app content, or ask the merchant to make theme edits in the storefront editor.

### subscriptions
- [missing] subscriptions.selling_plans: Recurring purchases — workaround: Bill repeat purchases outside Queek and create each order through normal checkout when it is due.

### sync
- [supported] sync.bulk: Bulk export and change feed — workaround: Request an export for the first full load, then poll products, orders and customers with updated_after, starting each poll at least five minutes before the previous poll started. Deduplicate by resource id, keep other filters fixed, consume webhooks including products/delete and customers/delete, and reconcile occasionally against a fresh export (or a full list walk) with what the app holds.
- [supported] sync.safety: Idempotency, cursors and rate policy — workaround: Send an idempotency key on every write, page with cursors, and wait for Retry-After on a 429.

### tax
- [missing] tax.calculation: App-calculated tax at checkout — workaround: Ship jurisdiction logic in the app-hosted flow and keep the store rows aligned with it.
- [supported] tax.configuration: Tax rows through the app API — workaround: For jurisdiction logic, keep it in the app-hosted flow and write the resulting rows here.

### webhooks
- [supported] webhooks.carts_chat: Abandoned-cart topics — workaround: Poll GET abandoned-checkouts with updated_since and deduplicate on the cart id and updated_at; use orders/create to detect completion.
- [supported] webhooks.core: Orders, products, customers, inventory, locales webhooks
- [supported] webhooks.delivery: Delivery retries, replay and ordering — workaround: Dedupe on the event id and on the resource and operation, and reconcile against cursor reads.
- [supported] webhooks.lifecycle: Lifecycle as subscribable topics — workaround: Declare the handoff URLs and verify the envelope signature on your server.
- [supported] webhooks.privacy: Erasure and redaction topics — 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.

## Primitives digest
- merchant scopes: 100 (analytics, app, app_alerts, app_setup, business_profile, checkouts, collected, collections, conversations, coupons, customer, customers, discounts, exports, inventory, items, locales, media, metafields, metaobjects, options, orders, pages, payout, posts, product_reviews, publications, purchase_orders, reviews, shipping, stock_adjustments, suppliers, taxes, team, translations)
- non-delegable prefixes: merchant-api_keys-, merchant-roles-, merchant-users-, merchant-employees-, merchant-partners-, merchant-pos-, merchant-apps-, merchant-items-update-all, merchant-settings-payments-
- webhook topics (25): orders/create, orders/paid, orders/updated, orders/fulfilled, orders/cancelled, products/create, products/update, products/delete, customers/create, customers/update, customers/delete, customers/data_request, customers/redact, customers_email_marketing_consent/update, customers_marketing_consent/update, inventory_levels/update, locales/create, locales/update, locales/destroy, translations/update, translations/delete, checkouts/create, checkouts/update, refunds/create, conversation_messages/create
- storefront blocks: targets [product] types [app_block, app_embed] fields [date, time, select] shopper text [line_text] (max_length 1-500, default 100, up to 3 per manifest)
- dashboard: targets [order-details, product-details, order-print] effects [order_appointment]
- handoffs: app/installed, app/uninstalled, app/resync, app/scopes_update, app/settings_updated
- app endpoints: GET api/v1/apps/installations; POST api/v1/apps/installations/{installation}/access_tokens; POST api/v1/apps/installations/{installation}/resync; POST api/v1/apps/installations/{installation}/scopes/revoke
- proxy: GET,POST api/v1/client/apps/{appSlug}/{path} (max 262144 bytes)
- session token TTL: 60s; installation token TTL: 3600s
- error codes: ai_unavailable_in_test_mode, api_key_expired, api_key_mode_mismatch, api_key_revoked, app_embed_not_ready, app_grant_insufficient, app_handoff_failed, app_installation_gone, app_installation_pending, app_ip_not_allowed, app_proxy_failed, app_proxy_gone, app_token_revoked, bad_request, bank_unverifiable, bank_unverified, channel_gateway_unreachable, client_key_required, conflict, custom_domain_provisioning_failed, custom_gateway_forbidden, custom_gateway_kyc_required, custom_gateway_not_configured, custom_gateway_not_verified, custom_gateway_plan_required, custom_gateway_store_ineligible, custom_gateway_verification_failed, delivery_location_unserved, forbidden, gone, idempotency_key_in_progress, idempotency_key_required, idempotency_key_reuse, insufficient_scope, invalid_client, invalid_client_key, invalid_pin, invalid_refund_amount, messaging_window_closed, metafield_definition_missing, metafield_filter_unsupported_type, metafield_namespace_reserved, metafield_value_invalid, metaobject_definition_missing, metaobject_field_invalid, metaobject_reference_invalid, metaobject_type_reserved, method_not_allowed, not_found, nothing_to_refund, order_not_refundable, origin_not_allowed, origin_required, otp_required, payload_too_large, payment_amount_mismatch, payment_method_unavailable, payout_hold, pin_required, plan_inactive, private_key_required, refund_amount_below_minimum, refund_amount_exceeds_refundable, refund_line_invalid, refund_payment_not_found, refund_provider_unavailable, refund_provider_unsupported, refunds_disabled, requires_line_text, requires_slot, resync_cooldown, route_not_available, server_error, service_unavailable, store_build_gated, store_region_missing, subscription_feature_locked, too_many_requests, transaction_pin_required, translation_digest_stale, translation_locale_is_default, translation_locale_is_primary, translation_locale_not_published, translation_max_published_locales, translation_unknown_key, translation_unknown_locale, unauthenticated, unknown_product_ref, unknown_service, unknown_variant_ref, unsupported_media_type, validation_failed, variant_required, vendor_access_denied, vendor_mail_sender_forbidden, vendor_mail_sender_key_unavailable, vendor_mail_sender_not_configured, vendor_mail_sender_plan_required, vendor_mail_sender_verification_failed