Scopes
Canonical scope reference
Every registered scope, its risk, real public coverage, requestability, platform-only reservations and reviewed capability contracts.
Scopes are app permissions, not human roles. A version requests them and a merchant Owner or Admin grants a subset at installation. The API still validates the active installation, tenant, exact version, token, and route-specific scope on every request.
Least privilege and merchant meaning
Ask only for a scope that maps to a documented operation your app uses. Show the merchant why each grant is needed and what data or action it covers. A high-risk label calls for stronger review; it does not make the capability operational.
Current registry truth
| Scope | Risk | Status | Actual public coverage and caveat |
|---|---|---|---|
app_data:manage | low | CURRENT | GET /api/v1/app-data, GET/PUT/DELETE /api/v1/app-data/{key}; private key-value data of this installation (16 KB per value, 10,000 keys), deleted on uninstall. |
catalog:read | low | CURRENT | GET /api/v1/catalog/products and GET /api/v1/catalog/products/{id} (options and variants); categories need categories:read. |
catalog:write | high | CURRENT | POST /api/v1/catalog/products, PATCH /api/v1/catalog/products/{id}; basic fields only, no media, variants, inventory or payment settings. |
categories:read | low | CURRENT | GET /api/v1/catalog/categories; active categories only. |
customers:read | high | CURRENT | GET /api/v1/customers and GET /api/v1/customers/{id}; names, phone, email and creation time only. |
customers:write_tags | high | CURRENT | POST /api/v1/customers/{id}/tags, DELETE /api/v1/customers/{id}/tags/{tag}; removes only assignments made by the same app. |
discounts:read | medium | CURRENT | GET /api/v1/discounts; currently active rules and codes; no redemptions. |
discounts:write | high | CURRENT | POST /api/v1/discounts, PATCH /api/v1/discounts/{id}; updates only codes the same app created; no deletion. |
inventory:read | medium | CURRENT | GET /api/v1/inventory/locations, /levels, /movements; quantities and identifiers; no notes or staff. |
inventory:write | high | CURRENT | POST /api/v1/inventory/adjustments; one movement per adjustment at an active location, never below reserved stock. |
media:read_products | low | PARTIAL | Requestable reviewed contract without a public operation yet; product image references come from catalog:read. |
orders:read | high | CURRENT | GET /api/v1/orders and GET /api/v1/orders/{id}; order summaries only. |
orders:read_items | high | CURRENT | GET /api/v1/orders/{id}/items; product/variant IDs, name snapshot, quantity and prices; no customer data. |
orders:write | high | PLANNED | Registered but disabled and not requestable; there is no generic order mutation. |
orders:write_fulfillments | high | CURRENT | POST /api/v1/orders/{id}/fulfillments; carrier and tracking, confirmed or preparing orders become shipped. |
orders:write_tags | medium | CURRENT | POST /api/v1/orders/{id}/tags, DELETE /api/v1/orders/{id}/tags/{tag}; removes only tags created by the same app. |
store:read | low | CURRENT | GET /api/v1/store; names, ID and subdomain; no private settings or bank details. |
webhooks:manage | medium | CURRENT | Manage subscriptions and receive only reviewed resource events under webhooks.events.v2. Private Staging delivery acceptance passed. |
Requestability and reviewed contracts
Every CURRENT scope above, plus media:read_products, is requestable by third-party app versions. orders:write stays disabled. Each reviewed version captures the operational contract identifier of its scopes (for example catalog.products.write.v1); tag scopes keep their existing identifiers official.order_tags.write.v1 and official.customer_tags.write.v1. A future expansion requires a new reviewed app version and fresh merchant consent; an old token cannot silently acquire the expanded permission. These scopes never authorize private database objects or undocumented endpoints.
Platform-only scopes
segments:write_membership, notifications:write, themes:write_extensions, forms:manage_submissions and assets:manage_digital belong to official first-party runtimes, and native:invoke belongs to reviewed native connectors. A third-party version that requests them is refused with scope_platform_only (or native_scope_platform_only). They grant no public API operation.
Fail-closed handling
Treat 401 as a missing or invalid token and 403 as a denied operation where documented. Never retry by escalating scopes, changing tenant identifiers, spraying tokens, or falling back to an internal credential. Ask the merchant to approve a reviewed version when a legitimate new grant is needed.