Skip to content
Dukkan DevelopersDocs
العربيةSign in

Scope reference

Every scope, what it unlocks in endpoints and webhook topics, and the sentence the merchant sees.

Updated 10 Sept 20263 min read
On this page

This page is for anyone deciding what their app requests. By the end you know every scope, exactly what it unlocks, how the merchant sees it, and the special rules around the customer-data scope.

Rules#

  • You request scopes per app version in the portal; the merchant grants them per store on the consent screen. Scopes never widen silently; widening means a new version and a new consent.
  • Effective scopes = granted ∩ the granting member's live permissions. An endpoint without an effective scope returns 403 with code forbidden.
  • Subscribing to a webhook topic requires the read scope that governs its payload, and delivery stops immediately when that scope is lost.
  • Reviewers check that the listing justifies every scope. Request the minimum.

The table#

Scope Unlocks Webhook topics Sentence the merchant sees
products:read GET /products, GET /products/{id} product.created, product.updated, product.deleted Read products and their variants
inventory:read GET /inventory/movements; also discloses stock_after in the written-movement response inventory.movement_created Read inventory levels and movements
inventory:write POST /inventory/movements; the restock option of POST /orders/{id}/refunds — Adjust inventory levels
orders:read GET /orders, GET /orders/{id} (without customer data) order.created, order.status_changed, order.paid, fulfillment.requested, fulfillment.created, fulfillment.updated, refund.created Read orders, line items and fulfillment status
orders:write PATCH /orders/{id}/status; PATCH /orders/{id} (note, tags, the app's own attributes) — Update order status, note and tags
orders:create POST /orders (orders with prices the app sets, including custom lines) — Create orders with prices the app sets
fulfillments:write POST /orders/{id}/fulfillments, PATCH /orders/{id}/fulfillments/{fulfillmentId} (including COD collection proposals) — Create and update fulfillments and tracking
refunds:write POST /orders/{id}/refunds — Issue refunds on behalf of the merchant
discounts:read GET /discounts — Read discounts and promotions
clients:read the customer and shipping_address fields of GET /orders/{id} never in any webhook Read customer names and contact details (requires the data processing agreement)
clients:write creating and updating customer records; the customer endpoints arrive in a later revision, the scope is in the vocabulary now never in any webhook Create and update customer records: names, phone numbers and addresses (requires the data processing agreement)

app.uninstalled needs no scope and always arrives. Topics and payloads are in the events reference.

Dependency notes#

  • inventory:write is required to return goods to stock with a refund (restock); without it only the money refund is accepted.
  • fulfillments:write is money-adjacent: it can propose a cash collection the merchant then confirms. Review treats it as a sensitive scope, like refunds:write.
  • A movement written through inventory:write returns stock_after only when the install also holds inventory:read.
  • orders:create does not include reading orders: the 201 body is the only read it grants. Request orders:read as well if you list or fetch orders later, and orders:write if you update the note or tags after creation. The merchant sees the caption "These orders appear in your admin marked with the app name. Stock is reduced like any other order." under it. Details in Orders created by apps.
  • orders:create is treated as a sensitive scope in review, like refunds:write: it creates orders and reduces stock, so the listing must say why.

Customer data (clients:read, clients:write)#

Customer names, phone numbers, emails and delivery addresses sit behind two dedicated scopes: clients:read reads them and clients:write creates and updates customer records. Four things are different about them:

  1. The data processing agreement comes first. Your team owner must accept the current agreement version (2026-08-19) before the server accepts a version that requests either scope; see Data processing. A version bump drops both scopes until it is accepted again. Accepting the DPA also covers creating and updating customer records on the merchant's behalf.
  2. A separate section on the consent screen, unchecked by default, for both scopes.
  3. Never in webhook payloads. Fetch order details through the API; every access lands in the merchant's audit trail.
  4. Deleted on revocation. You commit to deleting the customer data you processed when an install is revoked.

Without clients:read the fields are simply omitted from order responses; you do not get null, you get no field. The one exception is POST /orders: its 201 body echoes the customer details your app supplied, because you already hold them.