Scopes
The 123 scopes across 195 operations, generated from the spec — a key carries scopes, and scopes are its whole permission.
A key holds scopes; scopes are the whole permission. Grant the smallest set that covers
the calls the integration makes — an operation outside them is a 403 insufficient_scope,
never a silent partial answer. See Authentication & keys for
who can grant what.
Every row below comes from the Requires scope sentence on the operation itself, so this
table says exactly what the API enforces. The reference pages repeat the scope per operation.
| Scope | Operations |
|---|---|
merchant-analytics-customers-read | GET /analytics/customers |
merchant-analytics-products-read | GET /analytics/products |
merchant-analytics-sales-read | GET /analytics/sales |
merchant-analytics-traffic-read | GET /analytics/traffic |
merchant-app-requirements-write | PUT /app/requirementsPUT /app/line-inputs |
merchant-app_alerts-create | POST /app/alerts |
merchant-app_metafields-read | GET /app/metafields |
merchant-app_metafields-update | PATCH /app/metafieldsPATCH /metafield-definitions/{definition}DELETE /metafield-definitions/{definition} |
merchant-app_payment_secret-create | POST /app/payment-provider/signing-secret |
merchant-app_setup-update | PUT /app/setup |
merchant-business_profile-read | GET /store |
merchant-checkouts-read | GET /abandoned-checkouts |
merchant-collected-definitions-manage | GET /collected-definitionsPOST /collected-definitionsPATCH /collected-definitions/{definition} |
merchant-collected-records-read | GET /recordsGET /records/{record} |
merchant-collected-records-submit | POST /records |
merchant-collected-records-update | PATCH /records/{record} |
merchant-collections-create | POST /collections/bulk |
merchant-collections-detail | GET /collections/{collection} |
merchant-collections-read | GET /collections |
merchant-collections-update | PUT /collections/{collection}POST /collections/{collection}/products/pinPOST /collections/{collection}/products/reorder |
merchant-conversations-read | GET /conversationsGET /conversations/{conversation}GET /conversations/{conversation}/messages |
merchant-conversations-reply | POST /conversations/{conversation}/messages |
merchant-conversations-update | POST /conversations/{conversation}/mark-read |
merchant-coupons-create | POST /coupons |
merchant-coupons-read | GET /coupons |
merchant-coupons-update | PATCH /coupons/{coupon} |
merchant-customer-segments-create | POST /customer-segments |
merchant-customer-segments-delete | DELETE /customer-segments/{segment} |
merchant-customer-segments-read | GET /customer-segmentsGET /customer-segments/{segment}POST /customer-segments/preview |
merchant-customer-segments-update | PATCH /customer-segments/{segment} |
merchant-customers-consent-update | POST /customers/{customer}/email-marketing-consent |
merchant-customers-detail | GET /customers/{customer}GET /customers/{customer}/wishlist-items |
merchant-customers-read | GET /customersGET /customers/followers |
merchant-customers-sms-consent-update | POST /customers/{customer}/sms-marketing-consent |
merchant-customers-update | PUT /customers/{customer}/tags |
merchant-discounts-create | POST /discounts |
merchant-discounts-detail | GET /discounts/{discount} |
merchant-discounts-read | GET /discounts |
merchant-discounts-update | PATCH /discounts/{discount}POST /discounts/{discount}/publishPOST /discounts/{discount}/unpublish |
merchant-exports-create | POST /exports |
merchant-exports-read | GET /exports/{export} |
merchant-inventory-detail | GET /inventory/products/{product}/history |
merchant-inventory-read | GET /inventoryGET /inventory/levelsGET /inventory/low-stockGET /inventory/out-of-stock |
merchant-inventory-update | POST /inventory/levels/adjustmentsPOST /inventory/adjustments |
merchant-invoices-create | POST /invoicesPOST /orders/{order}/invoice |
merchant-invoices-delete | DELETE /invoices/{invoice} |
merchant-invoices-fiscal-reference | POST /invoices/{invoice}/fiscal-reference |
merchant-invoices-read | GET /invoicesGET /invoices/{invoice}GET /orders/{order}/invoice |
merchant-invoices-record-payment | POST /invoices/{invoice}/paymentsPOST /invoices/{invoice}/payments/{payment}/void |
merchant-invoices-update | PATCH /invoices/{invoice}POST /invoices/{invoice}/issue |
merchant-invoices-void | POST /invoices/{invoice}/voidPOST /invoices/{invoice}/credit-notes |
merchant-items-create | POST /products |
merchant-items-delete | DELETE /products/{product} |
merchant-items-detail | GET /products/{product}/imagesGET /products/{product}/market-pricesGET /products/{product}GET /products/{product}/variants |
merchant-items-read | GET /productsGET /storefront/search |
merchant-items-update | POST /products/{product}/imagesPATCH /products/{product}/images/{image}DELETE /products/{product}/images/{image}PUT /products/{product}/market-pricesPUT /products/{product}POST /products/publishPOST /products/{product}/variantsPATCH /products/{product}/variants/{variant}DELETE /products/{product}/variants/{variant} |
merchant-locales-read | GET /locales |
merchant-locales-write | POST /localesPATCH /locales/{locale}DELETE /locales/{locale}POST /locales/{locale}/default |
merchant-markets-read | GET /marketsGET /markets/optionsGET /markets/{market} |
merchant-markets-write | POST /marketsPATCH /markets/{market}DELETE /markets/{market} |
merchant-media-create | POST /files |
merchant-media-delete | DELETE /files/{file} |
merchant-media-read | GET /filesGET /files/{file}/references |
merchant-media-update | PATCH /files/{file} |
merchant-metafields-create | POST /metafield-definitions |
merchant-metafields-read | GET /metafield-definitions |
merchant-metafields-update | PATCH /products/{product}/metafieldsPATCH /products/{product}/variants/{variant}/metafields |
merchant-metaobjects-create | POST /metaobject-definitionsPOST /metaobjects |
merchant-metaobjects-read | GET /metaobject-definitionsGET /metaobjects |
merchant-options-create | POST /addon-groups |
merchant-options-delete | DELETE /addon-groups/{group} |
merchant-options-detail | GET /addon-groups/{group} |
merchant-options-read | GET /addon-groups |
merchant-options-update | PATCH /addon-groups/{group}POST /products/{product}/addonsDELETE /products/{product}/addons/{group} |
merchant-orders-create | POST /orders |
merchant-orders-import | POST /orders/import |
merchant-orders-read | GET /ordersGET /orders/{order}GET /orders/{order}/refund-suggestion |
merchant-orders-refund-create | POST /orders/{order}/refunds |
merchant-orders-status-update | POST /orders/{order}/statusPOST /orders/{order}/assign-rider |
merchant-orders-update | PATCH /orders/{order}PATCH /orders/{order}/shipment |
merchant-pages-create | POST /pages |
merchant-pages-delete | DELETE /pages/{page} |
merchant-pages-detail | GET /pages/{page} |
merchant-pages-read | GET /pages |
merchant-pages-update | PATCH /pages/{page} |
merchant-payout-batches-read | GET /payoutsGET /payouts/{payout} |
merchant-payout-ledger-read | GET /payout-transactionsGET /payout-transactions/{transaction} |
merchant-posts-create | POST /posts |
merchant-posts-delete | DELETE /posts/{post} |
merchant-posts-detail | GET /posts/{post} |
merchant-posts-read | GET /posts |
merchant-posts-update | PUT /posts/{post} |
merchant-product_reviews-moderate | PATCH /product-reviews/{review}/status |
merchant-product_reviews-read | GET /product-reviewsGET /product-reviews/{review} |
merchant-product_reviews-respond | POST /product-reviews/{review}/response |
merchant-publications-create | POST /publications |
merchant-publications-read | GET /publications |
merchant-publications-update | PATCH /publications/{publication}/resources |
merchant-purchase_orders-create | POST /purchase-orders |
merchant-purchase_orders-detail | GET /purchase-orders/{po} |
merchant-purchase_orders-read | GET /purchase-orders |
merchant-purchase_orders-update | POST /purchase-orders/{po}/cancelPOST /purchase-orders/{po}/orderPOST /purchase-orders/{po}/closePOST /purchase-orders/{po}/receive |
merchant-returns-create | POST /returns |
merchant-returns-read | GET /returnsGET /returns/{return}GET /orders/{order}/returnable |
merchant-returns-update | POST /returns/{return}/approvePOST /returns/{return}/declinePOST /returns/{return}/cancelPOST /returns/{return}/closePOST /returns/{return}/reopenPOST /returns/{return}/receive |
merchant-review_settings-read | GET /review-settings |
merchant-review_settings-update | PATCH /review-settings |
merchant-reviews-import | POST /reviews/import |
merchant-reviews-read | GET /reviews |
merchant-shipping-create | POST /shipping-zones |
merchant-shipping-read | GET /shipping-zones |
merchant-shipping-update | PUT /shipping-zones/{zone} |
merchant-stock_adjustments-read | GET /inventory/adjustments |
merchant-suppliers-create | POST /suppliers |
merchant-suppliers-read | GET /suppliers |
merchant-suppliers-update | PATCH /suppliers/{supplier} |
merchant-taxes-create | POST /taxes |
merchant-taxes-read | GET /taxesGET /taxes/{tax} |
merchant-taxes-update | PATCH /taxes/{tax} |
merchant-team-directory-read | GET /team-directory |
merchant-translations-machine | POST /translations/machine/quotePOST /translations/machine |
merchant-translations-read | GET /translatable-resourcesGET /translatable-resources/{type}/{id} |
merchant-translations-write | PUT /translations/{type}/{id}DELETE /translations/{type}/{id} |
A write scope also returns, in that write’s own response, the record it wrote — listing or reading records needs the matching read scope.
Translations scopes
Four scopes cover every language and translation operation: merchant-locales-read,
merchant-locales-write, merchant-translations-read and merchant-translations-write.
merchant-translations-read reads the translatable content of every resource type —
products, product options and option values, collections, categories, pages, posts, menus and
theme strings — and merchant-translations-write writes and removes translations on all of
them. No scope of the resource itself (such as merchant-pages-read or merchant-items-read) is
needed to translate it. See Translate store content.
merchant-translations-machine is separate: it lets an app ask Queek to machine-translate the
store’s own content, which is charged to the store’s credits and saves the results as
translations. It is shown to the merchant at install, and the merchant can switch it off for each
app. See Machine translation.