Scopes & permissions

Scopes are the granular permissions your app requests at install. The merchant sees them on the consent screen and approves them; Salesive then enforces them on every API call your app makes. Request the minimum set your app needs — apps asking for fewer permissions are easier for merchants to trust and approve.

How enforcement works

Store-bound — an app token is tied to the single store it was installed on. Salesive resolves the store server-side from the installation, so you never send a store id, and a token can never reach another store’s data.
Scope-checked — each endpoint requires a specific scope. A request without the required scope is rejected with 403.
Resource-limited — apps can reach only the resources listed below (orders, carts, catalog, customers, wishlists, reviews, categories, shipping, discounts, blogs, notifications, tasks, notes, metafields, scripts, comments, domains, roles, payouts, Shipday, KYC, files, settings, billing, checkout extensions, workflow triggers, plus outbound email). Requests to any other resource (wallet, staff, payments, themes, …) are rejected with 403, regardless of scope.
Rate-limited — outbound messaging scopes (SEND_NOTIFICATIONS, SEND_EMAILS) are rate limited per installation; over-limit requests get 429. See Outbound messaging.
Revoked on uninstall — deactivating the installation (uninstall) invalidates the app’s tokens immediately.

Read scopes (READ_*) cover GET endpoints; write scopes (WRITE_*) cover create/update endpoints and include their read counterpart’s endpoints where relevant. A few irreversible owner-only actions (e.g. deleting an order or a customer record) are reserved for the store owner and are not available to apps even with a write scope.

Default grant — store & user context

Every installed app can call one endpoint without requesting any scope. It returns basic store and user info so your app can display the merchant’s store name, logo, and contact details on first load without needing a full permission grant:

GET /api/v1/app/context
Authorization: Bearer <app_token>

Response:

{
  "store": {
    "id": "...",
    "name": "Acme Store",
    "type": "restaurant",
    "logo": "https://...",
    "favicon": "https://...",
    "tagline": "Best jollof in town",
    "description": "...",
    "currency": { "code": "NGN", "symbol": "₦", "name": "Nigerian Naira" },
    "country": { "name": "Nigeria", "code": "NG" },
    "state": "Lagos",
    "location": {
      "address": "12 Lekki Phase 1",
      "city": "Lagos",
      "phone": "+234...",
      "email": "hello@acme.com"
    },
    "business": { "name": "Acme Ltd", "phone": "...", "email": "..." },
    "socialMedia": { "instagram": "...", "facebook": "..." }
  },
  "user": {
    "id": "...",
    "name": "Amara Okonkwo",
    "email": "amara@acme.com",
    "phone": "+234...",
    "avatar": "https://...",
    "storeRole": "owner"
  }
}

The user object is the merchant who installed the app. storeRole is "owner" if the installing user owns the store, or "staff" if they are a staff member — useful for conditionally showing admin-level controls in your app UI. No financial, payment, or credential fields are included. See Store and user context for the full response shape and every store and user field. If you are using the App Starter, this endpoint is pre-wired at GET /api/context?shop=<id> on your app’s own server and your frontend can call apiGet(\/context?shop=$`)` directly.

The app token is store-bound — the store comes from the installation, not from any header or query you send. You cannot call this endpoint on behalf of a store you aren’t installed on.

Available scopes

You request scopes as a space-separated list in the scope parameter, e.g. READ_ORDERS WRITE_ORDERS READ_INVENTORY.

Scope	Grants	Example endpoints
`READ_ORDERS`	View orders, order stats and counts	`GET /orders`, `GET /orders/:id`, `GET /orders/stats`
`WRITE_ORDERS`	Create and update orders. Cancelling additionally needs the `WRITE_ORDERS_CANCEL` runtime permission	`POST /orders/pos`, `PUT /orders/:id`, `POST /orders/:id/fulfill`, `POST /orders/:id/cancel`
`WRITE_REFUNDS`	Mark orders as refunded (with `WRITE_ORDERS`)	`POST /orders/:id/refund`
`READ_CARTS`	Receive the storefront cart and checkout webhook events. The event is notify-only: identifiers, no cart contents	`carts/item_added`, `carts/updated`, `carts/item_removed`, `carts/cleared`, `carts/abandoned`
`READ_CART_CONTENTS`	Read a shopper’s cart, and add the cart aggregate (item count and total value) to cart events when the app also holds `READ_CARTS`	`GET /carts`, `GET /carts/:customerId`
`READ_INVENTORY`	View the store catalog: products / menu / services / digital products, and buyer access on digital stores	`GET /products`, `GET /foods`, `GET /services`, `GET /digital-products`, `GET /digital-access` (+ `/:id`, `/search`)
`WRITE_INVENTORY`	Create, update and delete catalog items, and grant or revoke buyer access on digital stores	`POST/PUT/DELETE /products`, `/foods`, `/services`, `/digital-products`, `POST /products/bulk/*`, `POST /digital-access/grant`
`READ_CATEGORIES`	View categories	`GET /categories`, `GET /categories/:id`
`WRITE_CATEGORIES`	Manage categories	`POST /categories`, `PUT /categories/:id`, `DELETE /categories/:id`
`READ_CUSTOMERS`	View customers	`GET /customers`, `GET /customers/:id`
`WRITE_CUSTOMERS`	Create and update customers	`POST /customers`, `PUT /customers/:id`
`READ_CUSTOMER_ANALYTICS`	Adds device, browser, OS, IP & approximate location to customer reads (sensitive shopper PII)	`GET /customers`, `GET /customers/:id` (adds `user.deviceInfo`)
`READ_WISHLIST`	View customer wishlists, and receive the wishlist events	`GET /wishlist`, `GET /wishlist/:id`, `wishlists/item_added`, `wishlists/item_removed`
`READ_SHIPPING`	View shipping options, rates and shipments	`GET /shipping/options`, `GET /shipping/rates`, `GET /shipping/shipments`
`WRITE_SHIPPING`	Manage shipping options and shipments	`POST /shipping/options`, `POST /shipping/shipments`, `PATCH /shipping/shipments/:id/status`
`READ_DISCOUNTS`	View coupons and discounts	`GET /coupons`, `GET /coupons/:id`
`WRITE_DISCOUNTS`	Create and manage coupons	`POST /coupons`, `PUT /coupons/:id`, `DELETE /coupons/:id`
`READ_BLOGS`	View blog posts	`GET /blogs`, `GET /blogs/:id`
`WRITE_BLOGS`	Create and manage blog posts	`POST /blogs`, `PUT /blogs/:id`, `DELETE /blogs/:id`
`READ_REVIEWS`	Receive storefront `reviews/created` webhooks and re-fetch the review	`reviews/created` events, and `GET /reviews/:id`
`READ_NOTIFICATIONS`	View the merchant’s notifications	`GET /notifications`, `GET /notifications/unread-count`
`WRITE_NOTIFICATIONS`	Mark the merchant’s notifications as read	`PATCH /notifications/read-all`, `PATCH /notifications/:id/read`
`READ_TASKS`	View tasks	`GET /tasks`, `GET /tasks/:id`, `GET /tasks/:id/responses`
`WRITE_TASKS`	Create and manage tasks	`POST /tasks`, `PUT /tasks/:id`, `DELETE /tasks/:id`
`READ_NOTES`	View notes	`GET /notes`, `GET /notes/:id`
`WRITE_NOTES`	Create and manage notes	`POST /notes`, `PUT /notes/:id`, `DELETE /notes/:id`
`READ_SCRIPTS`	View custom storefront scripts & tracking	`GET /scripts`, `GET /scripts/:id` (also under `/tracking`)
`WRITE_SCRIPTS`	Manage custom storefront scripts & tracking	`POST /scripts`, `PUT /scripts/:id`, `DELETE /scripts/:id`
`WRITE_COMMENTS`	Reply to and moderate storefront comments	`POST /comments/:id/reply`, `DELETE /comments/:id`
`READ_DOMAINS`	View the store’s domains and read DNS records. Granted to every installation by default, declared or not, so the DNS and domain write routes can require it without an extra consent step	`GET /domains`, `GET /domains/check-availability`, `GET /domains/:id/dns`, `GET /domains/:id/dns/records`, and required by every DNS/domain write route alongside the runtime grant
`READ_ROLES`	View staff roles & permissions	`GET /roles`, `GET /roles/:id`, `GET /roles/pages`
`READ_PAYOUTS`	View payouts & payout methods	`GET /payouts`, `GET /payouts/:id`, `GET /payouts/supported`
`READ_SHIPDAY`	View Shipday delivery status	`GET /shipday/status`, `GET /shipday/carriers`, `GET /shipday/sync/:id`
`WRITE_SHIPDAY`	Dispatch & manage Shipday deliveries	`POST /shipday/dispatch`, `PUT /shipday/assign/:id/:carrierId`, `PUT /shipday/status/:id`
`READ_KYC`	View store verification (KYC) status	`GET /kyc/status`
`WRITE_KYC`	Start & refresh store verification (KYC)	`POST /kyc/session`, `POST /kyc/refresh`
`READ_FILES`	View files and media in the store gallery	`GET /files`, `GET /files/:id`
`WRITE_FILES`	Add, update, and remove externally-hosted images & videos from the gallery	`POST /files`, `PUT /files/:id`, `DELETE /files/:id`
`READ_METAFIELDS`	Read metafields and their definitions: shared namespaces plus your own app namespace, never another app’s. Also receives `metafields/*` webhooks	`GET /metafields`, `GET /metafields/:id`, `GET /metafield-definitions` (+ `/:id`)
`WRITE_METAFIELDS`	Create, replace and delete metafields and definitions in your app namespace and in shared namespaces. See Metafields	`PUT /metafields`, `POST /metafields/set`, `DELETE /metafields/:id`, `POST`/`PUT`/`DELETE /metafield-definitions`
`READ_CHARGES`	View the charges and subscriptions your app created, and receive billing webhooks	`GET /app-billing/charges`, `GET /app-billing/subscriptions` (+ `/:id`)
`WRITE_CHARGES`	Charge the merchant, once or by subscription, and cancel subscriptions. The merchant still approves every charge	`POST /app-billing/charges`, `POST /app-billing/subscriptions`, `POST /app-billing/subscriptions/:id/cancel`
`WRITE_WORKFLOW_TRIGGERS`	Start the store’s workflows by firing the workflow triggers your app declares. Your app cannot see or change the workflows	`POST /workflow-triggers/:triggerId`
`WRITE_SHIPPING_RATES`	Quote shipping rates buyers can pick at checkout (ecommerce and restaurant stores)	`PUT`/`GET`/`DELETE /checkout-extensions/shipping-rates`, see Checkout extensions
`WRITE_CHECKOUT_VALIDATION`	Check the cart when an order is placed, and stop it with a message	`PUT`/`GET`/`DELETE /checkout-extensions/cart-validation`, see Checkout extensions
`WRITE_DISCOUNT_FUNCTIONS`	Offer automatic discounts at checkout: money off lines or the whole order, applied under the platform’s caps	`PUT`/`GET`/`DELETE /checkout-extensions/discount`, see Checkout functions
`WRITE_CHECKOUT_FUNCTIONS`	Hide or rename the payment methods and delivery options the store already offers at checkout. Cannot add one, change a price or an amount	`PUT`/`GET`/`DELETE /checkout-extensions/payment` and `/delivery`, see Checkout functions
`WRITE_CUSTOMER_ACCOUNT_EXTENSIONS`	Add one block to the signed in shopper’s account area	`PUT`/`GET`/`DELETE /checkout-extensions/customer-account`, see Customer account extensions
`READ_SETTINGS`	View store preferences and checkout settings; receive `shop/updated`	`GET /settings`
`WRITE_SETTINGS`	Update store preferences and checkout settings	`PUT /settings`
`SEND_NOTIFICATIONS`	Send the merchant an in-app/push notification (rate limited)	`POST /notifications`
`SEND_EMAILS`	Email the merchant, the store’s customers, or its subscribers (rate limited)	`POST /emails`

READ_CARTS gates the cart events themselves and has no fetch endpoint of its own. READ_CART_CONTENTS gates GET /carts and GET /carts/:customerId on its own, and adds the cart aggregate to cart events only when the app also holds READ_CARTS. READ_WISHLIST gates both the wishlist reads and the wishlist events, so neither of those two is a webhook-only scope.

WRITE_DOMAINS and WRITE_DNS are runtime permissions, not OAuth scopes, so they are not part of the install consent screen. See Runtime permissions. Role, payout and custom-domain writes remain reserved for the store owner and are not available to apps even with a read scope.

What Salesive will grant

Not every name in the catalog is available to a marketplace app. At authorization, Salesive checks the requested list against two rules and stores only what passes. Grantable catalog. A marketplace app can hold only the scopes that map to an app-reachable endpoint, which is the list in the table above. A scope outside that list is dropped. MCP clients keep the wider catalog because their tokens are not scope-gated the same way. Customer data approval. READ_CUSTOMERS, WRITE_CUSTOMERS and READ_CUSTOMER_ANALYTICS are granted only when your app is official or an admin has set customerDataApproved on it. Salesive reviews customer data access separately because these scopes expose shopper PII. Until that review happens the three scopes are dropped even if your app lists them. Once you hold them, you must also handle data protection notices. Every response that describes the consent screen says what was dropped and why:

{
  "requestedScopes": ["READ_ORDERS", "WRITE_ORDERS"],
  "deniedScopes": [
    {
      "permission": "READ_CUSTOMERS",
      "label": "View customers",
      "reason": "This app has not been approved to access customer data. Salesive reviews customer data access separately, so these permissions cannot be granted yet."
    }
  ]
}

requestedScopes is what the merchant will see and what the authorize step will store. deniedScopes is the explanation to show in your own UI or logs. GET /oauth/authorize and POST /api/v1/apps/marketplace/:slug/install-consent both return this shape. The token response’s scope field is the final grant. The gate is applied again when the authorization code is written, so a caller cannot widen the list between the consent screen and the token exchange.

A non-grantable scope is reported with the reason This permission is not available to marketplace apps. A customer data scope without approval reports the separate review reason. Unknown names that are not in the catalog at all are dropped silently.

Runtime permissions

Five capabilities are granted after install, from inside the app, rather than as OAuth scopes. The merchant approves each one in a dashboard modal and picks how long it lasts. A grant dies with the installation, so a reinstall starts clean.

Permission	What it covers	Scope
`AUTO_LAUNCH`	Expand the app from the background without the merchant tapping the dock	Store wide
`CLIPBOARD_READ`	Read text from the merchant’s clipboard	Store wide
`WRITE_ORDERS_CANCEL`	Cancel orders on the merchant’s behalf, an irreversible action	Store wide
`WRITE_DOMAINS`	Add and remove custom domains, and change the store subdomain	Store wide
`WRITE_DNS`	Add, change and remove individual DNS records	One domain, optionally limited to specific record types

Neither domain permission reaches the full DNS zone replace: PUT /domains/:id/dns is refused for app tokens. WRITE_DOMAINS is domain lifecycle only and does not grant any DNS write. Request them through the App Bridge; see DNS records for the DNS endpoints, protection rules and limits.

Files — externally-hosted only. WRITE_FILES lets apps register images and videos whose bytes are hosted on an external service (your CDN, S3 bucket, etc.) — only the URL is stored in the gallery. Only image/* and video/* MIME types are accepted; size is recorded as 0 since no storage is consumed on Salesive’s servers. Apps may update or delete only files they registered (files whose size is 0). Merchant-uploaded files (stored on Salesive’s file service) must be managed from the store dashboard.

Settings scope. READ_SETTINGS / WRITE_SETTINGS cover the store’s preferences and checkout behaviour: notification toggles (push, payment, order, shipping, sales, visitor), allowOrderWithoutShipping, disableShipmentInStorefront, and posTaxRate. Store identity fields (name, logo, business info, social media) are available without any scope via GET /app/context and are writeable by humans only. Analytics, wallet, payment method, and theme settings are not accessible to apps.

The authoritative, always-current list is in the OAuth discovery document (scopes_supported) and via the Developer console scope picker, which only offers scopes that map to a reachable endpoint.

The catalog differs by store type. A store’s catalog lives at /products (ecommerce), /foods (restaurant menu), /services (business), or /digital-products (digital store), all covered by the single READ_INVENTORY / WRITE_INVENTORY scope. Read store.type (ecommerce, restaurant, business or digital) from GET /app/context to know which one to call. /digital-products and /digital-access answer 403 on every store type other than digital. See Digital stores.

Outbound messaging (send notifications & emails)

Two scopes let your app reach out to people instead of just reading and writing store data. Because they generate messages, they are rate limited per installation and constrained to the store’s own audience — your app can never message an arbitrary address.

Send a notification — `SEND_NOTIFICATIONS`

POST /notifications sends an in-app + push notification to the merchant (the store owner). The recipient is fixed server-side; you cannot target another user.

POST /api/v1/notifications
{ "title": "Sync complete", "message": "We imported 42 new orders.", "url": "https://your-app.com/report" }

Limit: 5 notifications per day per installation. Over the limit returns 429.

Send an email — `SEND_EMAILS`

POST /emails sends an email to one of three audiences. Recipients are resolved server-side from the store’s own records, so you supply only the audience — never raw email addresses.

POST /api/v1/emails
{ "audience": "subscribers", "subject": "Spring sale", "title": "20% off this week", "message": "...", "actionText": "Shop now", "actionUrl": "https://store.example.com" }

`audience`	Who receives it
`merchant`	The store owner
`customers`	The store’s active customers
`subscribers`	The store’s newsletter subscribers (subscribed only)

Limit: 10 send requests per hour per installation, each fanning out to at most 1,000 recipients. Subscriber unsubscribes are always honoured. Over the limit returns 429.

Email content is delivered through Salesive’s branded notification template (subject, title, message, optional actionText + actionUrl) — arbitrary HTML is not accepted. Sending to customers and subscribers is done on the merchant’s behalf; respect their consent and applicable anti-spam law.

Requesting scopes

Include the scopes in the authorization redirect (see Install flow):

&scope=READ_ORDERS%20WRITE_ORDERS%20READ_INVENTORY

The merchant approves the set Salesive will actually grant, which can be shorter than what you asked for. The granted scopes are returned in the token response’s scope field; read it to confirm what you were granted, and read deniedScopes on the consent response to see what was dropped and why.

Adding scopes later

If a future version of your app needs more access, add the new scopes to your app and send the merchant through the consent flow again to grant the additional permissions. Existing installs keep working with their originally granted scopes until they re-consent. Customer data scopes need customerDataApproved (or official status) before they can be granted, so ask for that review before you send merchants back through consent.

Handling permission errors

A 403 on an API call means one of:

Missing scope — your token wasn’t granted the scope that endpoint requires. Request it at install and have the merchant re-consent.
Out-of-scope resource — the endpoint belongs to a resource apps can’t access in this release.

Always check the response message, and fail gracefully — surface a clear “this app needs the X permission” message to the merchant rather than retrying.

Building apps

How enforcement works

Default grant — store & user context

Available scopes

What Salesive will grant

Runtime permissions

Outbound messaging (send notifications & emails)

Send a notification — `SEND_NOTIFICATIONS`

Send an email — `SEND_EMAILS`

Requesting scopes

Adding scopes later

Handling permission errors

Next steps

Build & publish your app

​How enforcement works

​Default grant — store & user context

​Available scopes

​What Salesive will grant

​Runtime permissions

​Outbound messaging (send notifications & emails)

​Send a notification — SEND_NOTIFICATIONS

​Send an email — SEND_EMAILS

​Requesting scopes

​Adding scopes later

​Handling permission errors

​Next steps

Build & publish your app

How enforcement works

Default grant — store & user context

Available scopes

What Salesive will grant

Runtime permissions

Outbound messaging (send notifications & emails)

Send a notification — `SEND_NOTIFICATIONS`

Send an email — `SEND_EMAILS`

Requesting scopes

Adding scopes later

Handling permission errors

Next steps