Skip to content

Scopes

The scope sets you pick from when an app connects, and what each scope lets a connection do.

Updated

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 takes file:write too, and deleting one also takes product: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:delete erases a customer.
  • review: reviews and their stats. review:write replies to them, and review:moderate hides and unhides them.
  • attendee: attendee:checkin checks 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 takes customer: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_balance and list_notifications;
  • the account tools list_merchants and get_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 has list_merchants among its tools, whatever its sets, and it answers every business the connection reaches, each with up to 20 of its stores. Pass store to list_merchants to 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).

Every scope and its tools

Scope Tools that need it
affiliate:read list_commissions, commission_stats, list_affiliate_payouts, list_affiliates
affiliate:write record_affiliate_payout, set_affiliate, remove_affiliate, revert_affiliate
attendee:checkin check_in_event_attendee, undo_event_attendee_check_in, event_check_in_stats, list_check_in_events
automation:read list_all_automations, list_automation_runs, get_automation
automation:write create_automation, update_automation, pause_automation, resume_automation
automation:delete delete_automation
certificate:read list_certificates, list_certificate_issues, certificate_stats
certificate:write issue_certificate, create_certificate, update_certificate, revoke_certificate_issue
certificate:delete delete_certificate
custompage:read list_pages, get_page
custompage:write create_page, update_page, publish_page, unpublish_page
custompage:delete delete_page
customer:read customer_stats, list_grants, list_feeds, list_licenses, get_license, license_stats, list_license_activations, verify_license, refresh_license_token, list_license_signing_keys, list_entitlements, list_customers, list_customer_activity, list_product_customers, product_customer_stats, list_checkouts, get_customer, list_event_attendees, event_attendee_stats, list_customer_answers, list_product_requests
customer:write grant_access, revoke_grant, update_feed, revoke_feed, unblock_feed, update_license, disable_license, enable_license, record_license, deactivate_license_activation, rotate_license, activate_license, deactivate_license, rotate_license_signing_keys, set_customer_answers, approve_product_request, decline_product_request, promote_product_request
customer:delete erase_customer
discount:read list_discounts, get_discount, discount_stats
discount:write create_discount, update_discount, archive_discount, restore_discount, restrict_discount, attach_discount, detach_discount
discount:delete delete_discount
entry:read list_entries, list_entry_details, get_entry, entry_stats, list_entry_sections, list_entry_tags, list_sections
entry:write create_entry, update_entry, publish_entry, unpublish_entry, reorder_entries, create_section, rename_section, remove_section
entry:delete delete_entry
file:read list_attachments, get_body_schema, read_body, list_prompts, get_prompt, list_assets, get_asset, get_quota, list_media_outputs, get_media_output, get_asset_url, product_file_stats, list_asset_deliveries, list_asset_uses
file:write set_body, edit_body, publish_body, discard_staged, attach_asset, update_attachment, reorder_attachments, detach_attachment, create_prompt, update_prompt, set_product_poster, generate_media_output, update_media_output, publish_media_output, create_asset, create_upload, create_inline_upload, complete_upload, cancel_upload, update_asset, move_asset, replace_asset
file:delete delete_prompt, delete_media_output, delete_asset
integration:read list_integrations
integration:write set_integration
organization:read get_organization, get_balance, list_payouts, preview_plan_store, preview_plan_change, list_notifications, list_webhooks, get_webhook, list_webhook_deliveries, list_merchants, get_merchant
organization:write update_organization, set_organization_logo, change_plan, confirm_plan_change, cancel_plan_change, set_auto_upgrade, set_auto_add_ons, create_notification, update_notification, create_webhook, update_webhook, roll_webhook_secret, resend_webhook_delivery
organization:delete delete_notification, delete_webhook
portfolio:read get_portfolio, get_portfolio_valuation, list_holdings, list_announced_files, list_portfolio_events, list_portfolio_snapshots, search_symbols, quote_symbols
portfolio:write update_portfolio, update_holding, record_portfolio_event
price:read list_prices, simulate_checkout
price:write create_price, update_price, highlight_price, archive_price, restore_price
price:delete delete_price
product:read list_categories, list_products, get_product, product_summaries, list_tiers, list_prompts, get_prompt, list_access_requirements, list_resource_access, product_stats, catalog_stats, product_traffic_stats, list_product_questions, list_event_sessions, get_event_cancellation, list_software_events
product:write create_product, update_product, publish_product, unpublish_product, discontinue_product, reinstate_product, unlist_product, relist_product, create_tier, update_tier, reorder_tiers, create_prompt, update_prompt, delete_prompt, set_product_poster, set_access_requirement, clear_access_requirement, create_product_question, update_product_question, create_event_session, update_event_session, record_software_event, update_software_event
product:delete delete_product, delete_tier, delete_product_question, delete_event_session, delete_software_event
quiz:read list_attempts, get_attempt, list_quizzes, get_quiz, quiz_stats
quiz:write create_quiz, update_quiz
quiz:delete delete_quiz, clear_attempts, delete_attempt
revenue:read No tool needs it alone: without it, amounts read back as null, and a webhook for an event carrying them is refused.
review:read list_reviews, review_stats
review:write reply_to_review
review:moderate hide_review, unhide_review
site:read get_store, get_settings, get_plan_usage, get_domain, list_redirects, check_path
site:write update_settings, update_store, connect_domain, check_domain, remove_domain, set_store_icon, create_redirect, update_redirect
site:delete delete_redirect
subscription:read subscription_stats, list_subscriptions, list_subscription_periods, list_subscription_transitions, get_subscription
subscription:write cancel_subscription, resume_subscription
transaction:read store_stats, order_stats, store_totals, traffic_stats, conversion_stats, call_stats, list_orders, get_order, list_order_items, list_order_settlements, list_order_refunds, list_order_affiliates, list_revocations, list_event_refunds
transaction:write record_refund, record_order, create_revocation, retry_revocation_refund, cancel_event, retry_event_refund

Type to search…

↑↓ navigate↵ selectEsc close