Dashboard and merchant tools

Capabilities for dashboard and merchant API. 14 capabilities on this page: 14 available, 0 partly available, 0 not yet available. 1 more is 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.

Dashboard

Merchant alerts (in-app bell)

Available

Apps can page the merchant through the in-app bell with a severity, title and message, a dedupe key that collapses repeats, and a link to the app’s page in the dashboard. Alerts are rate-capped per installation. Delivery is the bell only: there is no push, text, email, per-staff targeting or delivery receipt from apps.

Good to know:

• In-app bell only, on purpose: an app message never triggers push, text or email to the merchant.
• An alert reaches the staff who may see installed apps; an app cannot pick a recipient or learn who read it.
• Each installation is capped per hour, and error-severity alerts per day; past a cap the call answers 429 with Retry-After, and a repeated dedupe key within its window is dropped.
• The bell link opens the app’s own page in the dashboard; an app cannot choose another destination.

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.

• Routes: POST api/v1/merchant/app/alerts
• Scopes: merchant-app_alerts-create

App details page data

Available

The merchant app-details view serves the access table, privacy block, proxy address, extension counts and install timeline for an installed app.

Good to know:

• Served for active installations only.

• Routes: GET api/v1/biz/vendor/app-store/{slug}/details

Embedded app page with session token

Available

The dashboard frames the app merchant page in a sandboxed view with short-lived session tokens minted per installation and user.

Good to know:

• Token lifetime is short; the framed origin is frozen at the install-time grant until an origin change is re-consented.

• Routes: POST api/v1/biz/vendor/app-session-token

• Manifest: extensions.merchant_page_url

Declared app nav and pins

Available

Manifest-declared sidebar entries rendered under the open app, resolved per installation, with per-user per-store pins.

Good to know:

• Pinning is per the open app; no global pin board.

• Manifest: extensions.nav

Dashboard sheet blocks, actions and print

Available

Apps can mount blocks on order and product sheets, an action on order sheets that records an appointment on the order and notifies the app, and a print template in the order print dialog.

Good to know:

• Blocks mount on order and product sheets only, actions on order sheets only, and print on the order print dialog only; there are no other dashboard targets.
• An action runs one effect from a closed list, today order_appointment; apps cannot define their own effects.
• There are no nav badges or unread counts.

Workaround: Deep-link into the embedded app page for any target, effect or badge a sheet mount cannot express.

• Manifest: dashboard.blocks, dashboard.actions, dashboard.print

Merchant API

Forms and collected records

Available

Apps create and manage their own collected form definitions, submit records under them, and list, read, update and triage records under definitions they own.

Good to know:

• Installation keys can access only records under their own collected definitions; merchant-held and other-installation records are unavailable. Uninstall makes former app records merchant-held. Apps cannot delete records or receive record webhooks.
• A json field keeps numeric-string keys (a map such as 4262: {...} stays a map), but JSON objects are stored unordered: key order is not preserved, an object whose keys are exactly 0, 1, 2… reads back as a list, and an empty object reads back as an empty list.

Workaround: Use the merchant Submissions screen to review merchant-held records; an app can process only its own definitions.

• Routes: POST api/v1/merchant/records, GET api/v1/merchant/records, GET api/v1/merchant/records/{record}, PATCH api/v1/merchant/records/{record}
• Scopes: merchant-collected-definitions-manage, merchant-collected-records-submit, merchant-collected-records-read, merchant-collected-records-update

Shopper text declarations

Available

Installation-bound sheet declaring which products take shopper text on a line, and under which of the app’s line_text fields; the label comes from the manifest and a required field is verified at checkout.

Good to know:

• A key must be a line_text field of the extensions the merchant granted; up to 3 fields per product, max_length 1 to 500, never above the manifest value (100 when the manifest sets none); 200 products per sheet; the whole sheet is replaced on every call.

• Routes: PUT api/v1/merchant/app/line-inputs

• Scopes: merchant-app-requirements-write

Metafields, metaobjects and app data

Available

Structured per-store config and app data through definitions, values, metaobjects and the installation-owned collected-records path.

Good to know:

• No app-namespaced convention: colliding keys across apps are possible.

• Scopes: merchant-metafields-create, merchant-metaobjects-create

Order status, payment approval and riders

Available

Move orders through the status machine, manually record qualifying offline payments as received, assign self-delivery riders, and patch shipment and app-namespaced extension fields.

Good to know:

• Manual approval requires payment_status awaiting_confirmation, a method other than online or wallet, and a payment that is not already paid. Cancelled or rejected orders cannot be updated. It records the payment and marks the order paid, does not verify provider receipt, and does not call a provider. Extension writes remain under the installation namespace.

• Routes: POST api/v1/merchant/orders/{order}/status

• Scopes: merchant-orders-status-update

Priced add-on groups on products

Available

Stores define priced choice-list groups and attach them to products through 7 Merchant API rows; the product object and products/* webhooks carry them additively under addons (bounded at 20 groups with 20 items each). Add-ons are not variants: a variant axis combines name and values into product variants and its price lives on the variant, while an add-on group carries its own prices.

Good to know:

• Queek apps author add-on data through these rows; they cannot run pricing logic at cart time.

• Arbitrary price-rewrite apps (bundles, rule-based pricing) stay unserved: Transform cart lines and bundles is still missing.

• A product that sells through variants refuses attach with 422; add-on prices ride as-is, outside the customer-price path.

• Routes: GET api/v1/merchant/addon-groups, GET api/v1/merchant/addon-groups/{group}, POST api/v1/merchant/addon-groups, PATCH api/v1/merchant/addon-groups/{group}, DELETE api/v1/merchant/addon-groups/{group}, POST api/v1/merchant/products/{product}/addons, DELETE api/v1/merchant/products/{product}/addons/{group}

• Scopes: merchant-options-read, merchant-options-detail, merchant-options-create, merchant-options-update, merchant-options-delete

Products, variants and images

Available

List, retrieve, create, replace and delete products with variants and images; bulk publish.

Good to know:

• Full-body update only; variants and images are partial.

• The product object carries priced choice-list add-ons under addons (see Priced add-on groups on products).

• Routes: GET api/v1/merchant/products

• Scopes: merchant-items-read, merchant-items-create

Apps read and update their own collected records

Available

Apps can list, read and update collected records under definitions they own.

Good to know:

• Installation keys can access only records under their own collected definitions; merchant-held and other-installation records are unavailable. Uninstall makes former app records merchant-held. Apps cannot delete records or receive record webhooks.

Workaround: Use the merchant Submissions screen to review merchant-held records; an app can process only its own definitions.

• Routes: GET api/v1/merchant/records, GET api/v1/merchant/records/{record}, PATCH api/v1/merchant/records/{record}
• Scopes: merchant-collected-records-read, merchant-collected-records-update

Booking requirements sheet

Available

Installation-bound product requirements map declaring which products require line properties under the installation namespace; verified at checkout by the claim guard.

Good to know:

• Claim binding is installation-scoped; property keys only.

• Routes: PUT api/v1/merchant/app/requirements

• Scopes: merchant-app-requirements-write

Staff directory read

Available

An app can list the store staff directory: stable id, display name, role names and an active flag. Contact details, permissions and credentials are never exposed.

Good to know:

• Read-only and narrow: no email, phone, permissions or roles management; removed staff are never listed; inactive staff are listed with is_active false.

• Routes: GET team-directory

• Scopes: merchant-team-directory-read

Active carts

Not offered by design

Carts belong to the shopper session. Apps do not read live carts; they see the order once it is placed.

Apps cannot read live carts: carts stay storefront-only, on the anonymous cart session or the customer token. Carts a signed-in customer left unchanged are offered separately as abandoned checkouts.

Workaround: Share the storefront cart URL into the chat and read the converted order through the order webhooks.