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, 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 get429. 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.Available scopes
You request scopes as a space-separated list in thescope 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.
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.
audience | Who receives it |
|---|---|
merchant | The store owner |
customers | The store’s active customers |
subscribers | The store’s newsletter subscribers (subscribed only) |
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 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
A403 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.
Next steps
Build & publish your app
Register your app, configure its listing, and submit it for review.