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

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

• 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

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

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

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.

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.