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, catalog, customers, categories, shipping, discounts, blogs, notifications, tasks, notes, scripts, comments, domains, roles, payouts, Shipday, KYC, files, settings, 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. 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	`POST /orders/pos`, `PUT /orders/:id`
`READ_CARTS`	Receive storefront cart & checkout webhooks	Webhook-only — `carts/*` events (notify-only, no fetch API)
`READ_INVENTORY`	View the store catalog — products / menu / services	`GET /products`, `GET /foods`, `GET /services` (+ `/:id`, `/search`)
`WRITE_INVENTORY`	Create, update and delete catalog items	`POST/PUT/DELETE /products`, `/foods`, `/services`, `POST /products/bulk/*`
`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 & receive wishlist events	`GET /wishlist`, `GET /wishlist/:id`
`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	Webhook-only — `reviews/created` events (notify-only, no fetch API)
`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	`GET /domains`, `GET /domains/check-availability`
`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_SETTINGS`	View store preferences and checkout settings	`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`

WRITE_DOMAINS exists but is not grantable to apps — changing a store’s domains stays a human, owner-level action. Likewise, role, payout and custom-domain writes are reserved for the store owner and are not available to apps even with a read scope.

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), or /services (business) — all covered by the single READ_INVENTORY / WRITE_INVENTORY scope. If you don’t know the store type, request the catalog from each and use whichever returns items.

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 exact set shown. The granted scopes are returned in the token response’s scope field — read it to confirm what you were actually granted.

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.

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

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

​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

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