# Scopes A scope is one permission on one kind of store data. You register the scopes your app needs in the developer console, and the authorize request can ask for all of them or a subset. The access token carries exactly the scopes the merchant approved. ## Scopes an app can request[​](#scopes-an-app-can-request "Direct link to Scopes an app can request") The descriptions come from the OpenAPI description. The consent screen shows each scope in the merchant's language. | Scope | Description | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `analytics:read` | Read store analytics and KPIs. | | `customers:read` | Read customers and each customer's orders. | | `delivery:send` | Hand orders to the store's courier. | | `landing_pages:read` | Read landing pages, their sections, publish checks and AI generation status. | | `landing_pages:write` | Create, update, publish and delete landing pages and their sections. | | `orders:read` | Read orders, their items and courier shipment state. | | `orders:write` | Create orders, change their status and cancel them. | | `pixels:read` | Read tracking pixels (access tokens are never returned). | | `pixels:write` | Add, update and delete tracking pixels. | | `products:read` | Read products and categories, with each product's images, variants, input fields, offers, quantity rules and stock. | | `products:write` | Create, update and delete products and categories, with each product's images, variants, input fields, offers, quantity rules and stock. | | `promos:read` | Read promo codes. | | `promos:write` | Create, update and delete promo codes. | | `shipping:read` | Read shipping rates and settings, linked couriers, courier coverage and the wilaya and commune lists. | | `shipping:write` | Change shipping rates and settings, and link, test, unlink or sync couriers. | | `store:read` | Read the store profile, design, home page sections and themes. | | `store:write` | Update the store profile, design, home page sections and theme. | | `whatsapp:read` | Read the WhatsApp order message templates, the WhatsApp wallet balance and the message log. | | `whatsapp:send` | Send WhatsApp order messages to buyers, each paid from the store's WhatsApp wallet. | ## Rules for app scopes[​](#rules-for-app-scopes "Direct link to Rules for app scopes") * Only the scopes in the table above can be registered on an app or granted to it. Any other scope in the authorize request fails with `invalid_scope`. * Apps cannot request `ai:generate`. It starts AI generations that spend the merchant's AI credits. * Apps cannot request `usage:read`, `webhooks:read` or `webhooks:write`. Your app receives webhooks through the webhook URL on its registration, not through `/v1/webhooks`. * An omitted or empty `scope` parameter grants every scope registered on the app. * Ask for the fewest scopes your app needs. The merchant sees one line per resource on the consent screen before approving. ## Endpoints each scope opens[​](#endpoints-each-scope-opens "Direct link to Endpoints each scope opens") This is the list the OpenAPI description declares. A few writes need the read scope as well: `POST /v1/orders`, `PATCH /v1/orders/{id}` and `POST /v1/orders/{id}/cancel` need `orders:read` and `orders:write`, `POST /v1/products` and `PATCH /v1/products/{id}` need `products:read` and `products:write`, and `POST /v1/landing-pages`, `PATCH /v1/landing-pages/{id}` and `POST /v1/landing-pages/{id}/publish` need `landing_pages:read` and `landing_pages:write`. These writes answer with the updated record, and reading it needs the read scope. Without that scope the write still runs, then the call answers `403` with a message such as `Missing scope: orders:read`, and a retry with the same `Idempotency-Key` gets that stored `403` back. Register and request both scopes. | Scope | Endpoints | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `analytics:read` | `GET /v1/analytics` | | `customers:read` | `GET /v1/customers`, `GET /v1/customers/{id}`, `GET /v1/customers/{id}/orders` | | `delivery:send` | `POST /v1/orders/{id}/send-to-delivery` | | `landing_pages:read` | `GET /v1/landing-page-section-types`, `GET /v1/landing-pages`, `GET /v1/landing-pages/{id}`, `GET /v1/landing-pages/{id}/check`, `GET /v1/landing-pages/{id}/sections`, `GET /v1/landing-pages/generate/{id}` | | `landing_pages:write` | `POST /v1/landing-pages`, `PATCH /v1/landing-pages/{id}`, `DELETE /v1/landing-pages/{id}`, `POST /v1/landing-pages/{id}/publish`, `POST /v1/landing-pages/{id}/sections`, `POST /v1/landing-pages/{id}/sections/batch`, `POST /v1/landing-pages/{id}/sections/reorder`, `PATCH /v1/landing-pages/{id}/sections/{section_id}`, `DELETE /v1/landing-pages/{id}/sections/{section_id}` | | `orders:read` | `GET /v1/orders`, `GET /v1/orders/{id}` | | `orders:write` | `POST /v1/orders`, `PATCH /v1/orders/{id}`, `POST /v1/orders/{id}/cancel` | | `pixels:read` | `GET /v1/pixels` | | `pixels:write` | `POST /v1/pixels`, `PATCH /v1/pixels/{id}`, `DELETE /v1/pixels/{id}` | | `products:read` | `GET /v1/categories`, `GET /v1/categories/{id}`, `GET /v1/products`, `GET /v1/products/{id}`, `GET /v1/products/{id}/addons`, `GET /v1/products/{id}/offers`, `GET /v1/products/{id}/quantity-rules`, `GET /v1/products/{id}/stock` | | `products:write` | `POST /v1/categories`, `POST /v1/categories/reorder`, `PATCH /v1/categories/{id}`, `DELETE /v1/categories/{id}`, `POST /v1/products`, `PATCH /v1/products/{id}`, `DELETE /v1/products/{id}`, `POST /v1/products/{id}/addons`, `POST /v1/products/{id}/images`, `PATCH /v1/products/{id}/images/{image_id}`, `DELETE /v1/products/{id}/images/{image_id}`, `POST /v1/products/{id}/offers`, `POST /v1/products/{id}/quantity-rules`, `POST /v1/products/{id}/stock`, `PUT /v1/products/{id}/variants` | | `promos:read` | `GET /v1/promo-codes` | | `promos:write` | `POST /v1/promo-codes`, `PATCH /v1/promo-codes/{id}`, `DELETE /v1/promo-codes/{id}` | | `shipping:read` | `GET /v1/shipping/coverage`, `GET /v1/shipping/providers`, `GET /v1/shipping/rates`, `GET /v1/shipping/settings`, `GET /v1/wilayas`, `GET /v1/wilayas/{id}/communes` | | `shipping:write` | `POST /v1/shipping/providers`, `POST /v1/shipping/providers/default`, `POST /v1/shipping/providers/test`, `DELETE /v1/shipping/providers/{provider}`, `POST /v1/shipping/rates`, `POST /v1/shipping/rates/sync`, `PATCH /v1/shipping/settings` | | `store:read` | `GET /v1/store`, `GET /v1/store/design`, `GET /v1/store/design/fields`, `GET /v1/store/home-sections`, `GET /v1/store/home-layout`, `GET /v1/themes` | | `store:write` | `PATCH /v1/store`, `PATCH /v1/store/design`, `PATCH /v1/store/home-sections`, `PUT /v1/store/home-layout`, `POST /v1/store/home-layout/sections`, `PATCH /v1/store/home-layout/sections/{id}`, `DELETE /v1/store/home-layout/sections/{id}`, `POST /v1/store/home-layout/reorder`, `POST /v1/store/theme`, `POST /v1/store/fast-checkout-theme`, `POST /v1/store/variant-style` | | `whatsapp:read` | `GET /v1/whatsapp/templates`, `GET /v1/whatsapp/balance`, `GET /v1/whatsapp/messages` | | `whatsapp:send` | `POST /v1/orders/{id}/whatsapp` | `GET /v1/whoami` needs no scope. `GET /v1/ping` needs no token. A call without the scope it needs answers `403` with the code `forbidden` and a message that names the scope, for example `Missing scope: orders:read`. ## Endpoints closed to app tokens[​](#endpoints-closed-to-app-tokens "Direct link to Endpoints closed to app tokens") These answer `403` with the message `Apps cannot use this endpoint` whatever scopes the token holds: `/v1/keys`, `/v1/webhooks`, `/v1/changes` and `POST /v1/changes/{id}/undo`. The merchant keeps key management, webhook subscriptions and the undo history. The assistant connection endpoints `GET /v1/connection` and `POST /v1/connection/active-store` answer `403` without `store:read` or `store:write`, and `404` otherwise, because an app token was not created through an assistant connection. ## Scopes and webhooks[​](#scopes-and-webhooks "Direct link to Scopes and webhooks") Every order event (`order.created`, `order.confirmed`, `order.processing`, `order.shipped`, `order.delivered`, `order.cancelled`, `order.returned`) carries the buyer's name, phone and address. Your install receives order events only when the merchant granted `orders:read`. The `app.uninstalled` event is sent whatever the scopes. See [webhooks](https://dzbuild.dev/webhooks.md). ## What the merchant sees[​](#what-the-merchant-sees "Direct link to What the merchant sees") The consent screen groups scopes by resource and shows one line per resource: the write line when the app asks for write access, the read line otherwise. The line is written in the merchant's language. Changing the scopes registered on the app does not change tokens already issued; a store gets the new scopes when the merchant installs the app again.