A scope names a resource and an action, as resource:action: product:read reads products, product:write creates and changes them, and product:delete removes them. Every tool needs one or more scopes, which its page in the Tools reference names.
What a connection holds
When an app connects, you pick one set for each business on the consent screen (see Sign-in and consent). In each business, the connection holds that set’s scopes, cut to your own permissions there: it never gets more than your seat allows. A connection reaching several businesses lists every tool any of them may call, and each call is checked against the business of the store it acts on.
A connection’s scopes are fixed for its whole life. To give an app more, connect it again and pick a wider set.
The sets
| Set | On the consent screen | What it covers |
|---|---|---|
catalog |
Catalog | Products, prices and discounts. |
content |
Content | The website, pages, files, quizzes and certificates. |
sales |
Sales | Orders, revenue, subscriptions and affiliates. |
customers |
Customers | Customers, reviews and event check-in. |
portfolio |
Portfolio | Portfolios and their holdings. |
everything |
Everything | Everything an app may do through Sherpo’s MCP server. |
Each set holds read, write and, where there is one, delete scopes. There is no read-only set.
| Set | Scopes |
|---|---|
catalog |
discount:read, discount:write, discount:delete, price:read, price:write, price:delete, product:read, product:write, product:delete |
content |
certificate:read, certificate:write, certificate:delete, custompage:read, custompage:write, custompage:delete, entry:read, entry:write, entry:delete, file:read, file:write, file:delete, quiz:read, quiz:write, quiz:delete, site:read, site:write, site:delete |
sales |
affiliate:read, affiliate:write, revenue:read, subscription:read, subscription:write, transaction:read, transaction:write |
customers |
attendee:checkin, customer:read, customer:write, customer:delete, review:read, review:write, review:moderate |
portfolio |
portfolio:read, portfolio:write |
everything |
Every scope below. |
What each resource covers
product: products, their tiers, who may access them, a software product’s activity, and product, catalog and product traffic stats. A release that ships files takesfile:writetoo, and deleting one also takesproduct:write, since its files leave the product’s downloads.price: prices, including highlighting, archiving and restoring them.discount: discounts, what they apply to, and their stats.entry: entries, the lessons, posts or episodes inside a product, and their sections.custompage: the store’s pages.file: files and uploads, attachments, rich text bodies, prompts, product posters and video versions, plus storage use and where each file is used and delivered.quiz: quizzes and their attempts.certificate: certificates and the certificates issued.site: the store itself: its settings, plan usage, icon and redirects.transaction: orders, with their items, settlements, refunds and affiliates, plus store, order, traffic, conversion and API call stats. It also records orders and refunds.revenue: amounts. See below.subscription: subscriptions, their periods and changes, and their stats. It also cancels and resumes them.affiliate: affiliates, their commissions and payouts.customer: customers, their activity and checkouts, and the access they hold.customer:deleteerases a customer.review: reviews and their stats.review:writereplies to them, andreview:moderatehides and unhides them.attendee:attendee:checkinchecks attendees in at an event’s door and undoes it, and reads the door’s counts and the events to check in. Alone, it never reads the guest list, which takescustomer:read. A check-in it makes still runs the event’s check-in automations and issues its certificates of attendance, though it reads neither.organization: the business: its profile and logo, balance, payouts, plan, notifications and webhooks.integration: the store’s integrations and their settings.automation: automations and their runs.portfolio: portfolios, holdings, their valuation, events and snapshots, and symbol search and quotes.
revenue:read
revenue:read names no tool. Without it, amounts read back as null, for example an order’s amount, total and fees. A webhook for an event that carries amounts is refused too. The sales and everything sets hold it.
What needs Everything
Only the everything set holds the organization, integration and automation scopes. So these need Everything:
- webhooks;
- integrations and automations;
- the business’s own tools, such as
get_organization,get_balanceandlist_notifications; - the account tools
list_merchantsandget_merchant, which read your businesses and their stores. A connection reaching one business answers only that one. A connection on the seller’s Connections page always haslist_merchantsamong its tools, whatever its sets, and it answers every business the connection reaches, each with up to 20 of its stores. Passstoretolist_merchantsto look up the business of another store the connection reaches.
Tools you can’t call aren’t listed
The server lists only the tools the connection may call, so an agent connected with the catalog set never sees the order or customer tools. Calling a tool the connection lacks a scope for answers HTTP 403 with insufficient_scope (see Errors), except on a connection reaching several businesses when another of them holds the scope, which is a tool error (see Sign-in and consent).