> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salesive.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Scopes & permissions
> Every scope a Salesive app can request, the endpoints each one unlocks, and how Salesive enforces them.
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, plus outbound email). Requests to any other
resource (wallet, staff, payments, settings, 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](#outbound-messaging-send-notifications--emails).
* **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.
## 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_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_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_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` |
| `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.
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.
```json theme={null}
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.
```json theme={null}
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](/apps/oauth-install#step-2-redirect-the-merchant-to-consent)):
```text theme={null}
&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.
## Next steps
Register your app, configure its listing, and submit it for review.