Reference values

Webhook topics, tokens, rate limits, extension and manifest limits, credential endpoints and error codes for Queek apps.

Values published by the platform that apps depend on. Scopes are listed on Merchant API scopes.

Webhook topics

An app subscribes to topics by declaring them in the webhook_topics manifest key. Delivery, signing and retries are described on Webhooks.

Resource	Topics
`orders`	`orders/create`, `orders/paid`, `orders/updated`, `orders/fulfilled`, `orders/cancelled`
`products`	`products/create`, `products/update`, `products/delete`
`customers`	`customers/create`, `customers/update`, `customers/delete`, `customers/data_request`, `customers/redact`
`customers_email_marketing_consent`	`customers_email_marketing_consent/update`
`customers_marketing_consent`	`customers_marketing_consent/update`
`inventory_levels`	`inventory_levels/update`
`locales`	`locales/create`, `locales/update`, `locales/destroy`
`translations`	`translations/update`, `translations/delete`
`checkouts`	`checkouts/create`, `checkouts/update`
`refunds`	`refunds/create`
`conversation_messages`	`conversation_messages/create`

Handoff events

Signed server-to-server events sent to the app for the install lifecycle.

app/installed
app/uninstalled
app/resync
app/scopes_update
app/settings_updated

App credential endpoints

Endpoints an app server calls with its app token.

Method	Path	Purpose
`GET`	`/api/v1/apps/installations`	List installations
`POST`	`/api/v1/apps/installations/{installation}/access_tokens`	Mint an installation token
`POST`	`/api/v1/apps/installations/{installation}/resync`	Resync an installation
`POST`	`/api/v1/apps/installations/{installation}/scopes/revoke`	Revoke granted scopes

Tokens

Token	Lifetime	Clock skew allowed	Minting limit	Other
Session token (embedded page)	60 seconds (1 minute)	20 seconds	30 per minute	—
Installation token	3,600 seconds (1 hour)	—	6,500 per minute	Slots: `2`
App token (JWT)	600 seconds (10 minutes)	120 seconds (2 minutes)	—	—

Rate limits for app surfaces

Limits specific to app credentials, the storefront proxy and dashboard extensions. The per-key quota that applies to Merchant API calls is on Idempotency and rate limits.

Limit	Value
App list requests	120 per minute
App resync requests	30 per minute
Failed app credential checks	60 per minute
Wait between resyncs of one installation	3,600 seconds (1 hour)
Installation token requests, per vendor	10 per minute
Installation token requests, per IP address	30 per minute
Storefront app proxy requests	120 per minute
Dashboard app list requests	60 per minute
Dashboard block requests	120 per minute
Dashboard action requests	30 per minute
Dashboard print requests	30 per minute

Storefront app proxy

Setting	Value
Methods	`GET`, `POST`
Path	`api/v1/client/apps/{appSlug}/{path}`
Maximum size	262,144 bytes (256 KiB)
Connect timeout	3 seconds
Timeout	5 seconds
Signature clock skew allowed	300 seconds (5 minutes)
Request limit	120 per minute
Customer id sharing switch	`apps.proxy_share_customer_id_enabled`
Post	Manifest key: `extensions.proxy.allow_post`; Content type: `application/json`; Max bytes: `65536`; Per minute: `20`; Per minute install: `600`; Kill switch: `apps.proxy_post_enabled`; Signed params: `method`, `body_sha256`, `idempotency_key`; Relayed statuses: `200`, `201`, `202`, `204`, `400`, `409`, `422`

Storefront extensions

Setting	Values
Block targets	`product`
Block types	`app_block`, `app_embed`
Embed targets	`body`
Embed capabilities	`chat-bubble`, `banner`, `popup`, `scroll-top`
Field types	`date`, `time`, `select`
Line input primitives	`line_text`
Line text limits	Max length: `500`; Default max length: `100`; Fields per manifest: `3`; Property key max length: `64`
Available if	`declared_products`

Dashboard extensions

Setting	Values
Targets	`order-details`, `product-details`, `order-print`
Block targets	`order-details`, `product-details`
Action targets	`order-details`
Print targets	`order-print`
Action effects	`order_appointment`
Field types	`date`, `time`, `select`, `text`, `slot-list`
Visibility conditions	`order.has_appointment`, `order.is_paid`, `product.has_files`

Manifest limits

How the manifest is written is described on App manifest.

Accepted values

Setting	Values
Top-level keys	`slug`, `name`, `description`, `icon`, `developer`, `version`, `distribution`, `category`, `tagline`, `description_long`, `highlights`, `logo_url`, `pricing`, `developer_url`, `privacy_url`, `support_url`, `demo_url`, `video_url`, `scopes`, `optional_scopes`, `webhook_topics`, `settings`, `install_url`, `uninstall_url`, `settings_url`, `webhook_url`, `extensions`, `dashboard`, `payment_provider`
Setting types	`string`, `secret`, `number`, `boolean`, `select`
Pricing models	`free`, `free_trial`, `paid`

Maximum entries

Item	Maximum
Storefront blocks	10
Navigation entries	10
Storefront embeds	3
Dashboard blocks	10
Dashboard actions	10
Print layouts	5
Schema fields	12
Print fields	20
Select options	50
Listing highlights	5

Maximum text length

Field	Characters
Name	120
Developer name	120
Field label	120
Select option	120
Tagline	80
Pricing note	80
Block title	80
Print label	80
Description	2,000
Long description	2,000
Highlight	90
Icon	64
Media id	64
Version	32
Key	64
Help text	500
Block description	500
Navigation label	40
Embed title	80
URL	2,048

The 99 codes in the platform's shared error vocabulary, as they appear in the error.code field, grouped by the area they belong to. The error shape is described on Versioning and errors, and the Merchant API codes on Errors. Treat a code you do not recognise by its HTTP status class.

Group	Codes
General	`bad_request`, `conflict`, `forbidden`, `gone`, `method_not_allowed`, `not_found`, `payload_too_large`, `route_not_available`, `server_error`, `service_unavailable`, `too_many_requests`, `unauthenticated`, `unknown_service`, `unsupported_media_type`, `validation_failed`
Keys, origins and scopes	`api_key_expired`, `api_key_mode_mismatch`, `api_key_revoked`, `client_key_required`, `insufficient_scope`, `invalid_client`, `invalid_client_key`, `origin_not_allowed`, `origin_required`, `private_key_required`, `vendor_access_denied`
Idempotency	`idempotency_key_in_progress`, `idempotency_key_required`, `idempotency_key_reuse`
Apps and installations	`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`, `channel_gateway_unreachable`, `requires_slot`, `resync_cooldown`
Metafields and metaobjects	`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`
Translations	`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`
Products and payments	`payment_amount_mismatch`, `unknown_product_ref`, `unknown_variant_ref`
Plans, gateways and mail senders	`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`, `plan_inactive`, `subscription_feature_locked`, `vendor_mail_sender_forbidden`, `vendor_mail_sender_key_unavailable`, `vendor_mail_sender_not_configured`, `vendor_mail_sender_plan_required`, `vendor_mail_sender_verification_failed`
Other	`ai_unavailable_in_test_mode`, `bank_unverifiable`, `bank_unverified`, `delivery_location_unserved`, `invalid_pin`, `invalid_refund_amount`, `messaging_window_closed`, `nothing_to_refund`, `order_not_refundable`, `otp_required`, `payment_method_unavailable`, `payout_hold`, `pin_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`, `store_build_gated`, `store_region_missing`, `transaction_pin_required`, `variant_required`