OAuth Scope Catalog

The scope families a plugin or store API key works with day to day on the Orbit Commerce public API (api.myorbitcommerce.net/v1/*, plus the /oauth/* token handshake). Most scopes are requestable by a third-party plugin; the remainder are labelled with the credential that can hold them. When a merchant installs your plugin they consent to the scopes you request; the granted set becomes the scopes claim on every token your plugin receives, and each endpoint checks for the scope it needs.

The same scope strings govern store API keys: the merchant picks the key's scopes at creation instead of consenting at install. Every resource scope below is grantable to a key, with three exceptions, each labelled where it appears:

• Plugin-only (billing:*, email:send, settings:*): these only make sense for an installed plugin and are rejected for keys.
• Assistant-only (page:*, store-settings:*): granted exclusively through the consent flow a merchant completes when connecting an AI assistant to their store; not offered in the key scope picker, not requestable by plugins. See Assistant-granted scopes.
• Reserved (import:*): named in the catalog but grantable to no credential today. See Reserved scopes.

This page is the public contract for the families it covers: every scope string here is exactly the string the API enforces, so copy them verbatim. It is not yet exhaustive — /v1 enforces further families (inventory, shipping, discounts, tags, gift cards, returns, quotes, suppliers and more) that this page has still to document. For how scopes are requested, consented to, and checked at runtime, see the Scopes guide; for the endpoint-by-endpoint detail — including the families not yet listed here — see the API Reference.

Naming convention. Scopes are <resource>:<action>. The resource is singular and kebab-case (product, customer, tracking-script — never products or trackingScripts). The action is usually one of list, read, create, update, delete; a small number of scopes use a purpose verb where a CRUD action would be misleading (order:fulfill, email:send, cart:adjust), and content resources with a draft/live split add publish (page:publish, blog-post:publish). So product:write is invalid (write is not an action — use update), and products:read is invalid (the resource must be singular).

A call made without a token — or with an invalid or expired one — returns 401 Unauthorized. A call made with a valid token that is missing the required scope also returns 401 Unauthorized; the error body names the missing scope (Missing required scopes: …). The one exception is subscribing to a webhook topic without the topic's scope, which returns 403 Forbidden.

Products — product:*

The product catalogue: variants, prices, inventory, images, and taxonomy associations. The most-used scope set for sync plugins (marketplaces, feed generators, import/export, reviews, search).

A plugin that only listens to product events through webhooks (product.created, product.updated) needs webhook:create to subscribe plus product:read for the topic. The webhook payload includes whatever your read scopes allow you to see.

Orders — order:*

Reads, create-on-behalf-of and status sync for marketplace plugins, plus fulfilment with tracking for shipping/3PL plugins.

order:update is deliberately narrow: pricing, line items, currency, and addresses are not editable through it (and a paid + fulfilled order seals those fields). order:fulfill is separate from order:update because fulfilling has customer-facing side effects — creating a fulfilment with tracking sends the store's Order Shipped email/SMS unless you pass notifyCustomer: false (do that when your plugin sends its own notification). Refunds and cancellation workflows stay owned by the storefront and dashboard.

Customers — customer:*

Read and write customer records — list and detail, plus create, update, and delete on behalf of a merchant (for example, mirroring a CRM into Orbit, or resolving and enriching buyer identity during order import).

Taxonomies — taxonomy:*

The product classification hierarchy (Orbit calls this "taxonomy"; some platforms call it a "category tree"). Read-only on the public API — taxonomy management happens in the dashboard.

In Orbit's vocabulary, a taxonomy is the classification tree. What other platforms call a "category" (a curated product collection) is a separate resource with its own scope family: see Categories below.

Categories — category:*

Curated product collections (the dashboard's Categories): manual or smart, each a browsable storefront destination. Distinct from taxonomies, the classification tree.

A category has no separate publish step: status is writable on create and update, so a category created active is browsable by shoppers on the same request. Hold your own drafts back by creating them inactive.

Brands — brand:*

The merchant's own brands. A brand is a storefront destination, not just a label: /brands/{handle} is a real route, the brand's description, logo, and SEO fields render on it, and the brand's name appears in the storefront product filter rail. (This is unrelated to the supplier-side brand catalogue, which is not on the public API.)

Carts — cart:*

On-demand read access to a live cart, plus the ability to own adjustment lines pushed onto one through the synchronous function.cart.adjustments extension point (conditional fees, surcharges — for example, a customs-duty or payment-surcharge plugin).

There is deliberately no list endpoint — enumerating a store's live carts is a privacy surface Orbit has not opened.

Custom fields — custom-field:read / custom-field:update

Custom field values on the store's own resources: the columns an import/export or sync plugin needs beyond the built-in fields. Values only, deliberately: definitions (the store's schema) are merchant-managed in the dashboard, and there is no public create/update/delete for them, so a plugin can never mutate a store's schema.

Owner types span the platform: PRODUCT, PRODUCT_VARIANT, CATEGORY, BRAND, ORDER, DRAFT_ORDER, CUSTOMER, PAGE, BLOG, BLOG_POST, and CRM_DEAL. The store is always resolved from your token; a storeId in the query or body is ignored.

Tracking scripts — tracking-script:*

Per-store conversion-tracking script management (Snapchat Pixel + CAPI, TikTok Pixel, Meta/Facebook Pixel, and similar). These scopes are store-scoped, which the :store suffix denotes.

A plugin that manages several providers (for example, a unified ad-pixel plugin) requests both scopes once.

Settings — settings:read:store / settings:update:store

Your plugin's own per-store configuration, as defined by its settingsSchema. Store-scoped (the :store suffix, as with tracking scripts).

The SDK wraps these as orbit.settings.get(), orbit.settings.getValue(key), and orbit.settings.update({ … }) — see the SDK guide.

Billing — billing:read / billing:update

Plugin monetisation, for plugins that charge merchants. Use the SDK's billing module (orbit.billing.*); these scopes gate what it can do.

A plugin that only displays pricing without taking payment needs billing:read only. See the billing section of the SDK guide for the full flow.

Email — email:send

Send transactional email through the platform's email service, so your plugin's mail goes out through the store's verified sender identity (DKIM), suppression list, and warm-up handling instead of hand-rolled SMTP.

Use it for merchant-facing notifications (sync reports, alerts) and store-branded customer messages your plugin owns. It is not a bulk-campaign API — sends inherit the platform's suppression and rate handling.

Outbound webhooks — webhook:*

Subscribe to store events for delivery to your plugin's own HTTPS endpoint. Most plugins that subscribe at runtime request all four scopes so they can manage their own subscriptions through the API. To subscribe to a topic you also need that topic's resource scope (for example, product:read for product.*) — see the Webhooks guide.

Navigation — navigation:*

Storefront menus and the links inside them. One family covers the menu and its items: an item cannot exist without its menu, so there is no separate navigation-item:*. Menus have no draft state and the storefront resolves them by handle, which makes every write here live: a menu edit is read by shoppers immediately.

Blogs — blog:*

The containers a store's articles are filed under. Most stores have one ("News", seeded at store creation) and only need more for genuinely separate publications. A blog is not itself a storefront page (there is no /blogs/{handle} route), but a store's blogs are listed on shopper-reachable surfaces, so creating one is visible without any post inside it. Posts are a separate scope family (blog posts below), so granting "write my articles" does not grant "delete the container they live in".

Blog posts — blog-post:*

The articles themselves, with a full draft/publish lifecycle. A post is created as a draft, becomes shopper-visible only through the separately-scoped publish step, and (unlike a page) has no separate draft copy once published: editing a published post rewrites the live article.

Media — media:read / media:create

The store media library: the images and files the dashboard's media manager holds.

There is no delete on the public surface; removing files from the library stays a dashboard action.

SEO — seo:read

A read-only health overview of the store's search-engine surface.

Redirects are their own resource family (next section), not part of seo:read.

Redirects — redirect:*

URL redirects, the tool for moving or retiring storefront paths without stranding saved links. There is deliberately no redirect:update: a redirect is small enough that the correction path is delete and recreate.

A redirect takes precedence over a live page at the same path, and nothing checks for that collision (the dashboard does not either), so confirm the source path is genuinely retired before creating one.

Analytics — analytics:read

Read-only reporting, mirroring the dashboard's analytics payloads.

Companies — company:*

B2B buyer accounts: the company record itself, its users (buyers who sign in and place orders on the company's behalf), pending invitations, and locations (billing/shipping addresses, each with its own assigned catalogue and payment term). Company users, invitations, and locations have no independent tenancy — a contact or invitation cannot outlive its company — so they read and write under company:* rather than a scope family of their own, the same way navigation items live under navigation:*.

Every /v1/companies request also requires the store to hold the B2B feature. Without it, reads still work — an ERP that pulls after a downgrade keeps working — but writes are refused with 403 Forbidden and body { "code": "FEATURE_FROZEN", "feature": "b2b" }.

PUT /v1/companies/by-external-id/{externalId} is an idempotent upsert keyed on your own ERP id: it requires both company:create and company:update, since it may do either. The path externalId always wins over one in the request body. It returns { "company": { … }, "created": true } on insert or "created": false on update — see the B2B/ERP integration guide for the full sync pattern.

Company users land pending-activation: POST .../users never accepts a password, and sendActivationEmail defaults to false so a bulk ERP import never surprise-emails a buyer. Set a role preset (admin, buyer, or viewer) for a quick grant, or send an explicit permissions object for the 11 individual flags — an explicit permissions always wins over role. Pass mainContact: true to also make the new user the company's main contact. To send (or resend) the set-password email later, once you're ready for the buyer to sign in, call POST .../users/{contactId}/send-activation.

Catalogues — b2b-catalog:*

Company-specific price books: per-product/variant price overrides, group pricing rules keyed on category, tag, brand, custom product type, or an individual product, and — for a restricted catalogue — the explicit set of products a company is allowed to see and buy.

Every /v1/catalogs request also requires the store to hold the B2B feature; the same read-always, write-refused-when-frozen split as company:* applies (403 Forbidden, { "code": "FEATURE_FROZEN", "feature": "b2b" }).

isRestricted: true on create means the company sees and buys only the products explicitly added with POST /v1/catalogs/{id}/products; false (the default) means every store product is visible, at whatever price the catalogue's overrides and rules resolve to. The vendor dashboard's price-preview/price-check tooling is deliberately not exposed on the public surface.

Payment terms — payment-term:*

Net-terms definitions — Net 30, a fixed due date, and so on — that a company location can be assigned. The assignment drives the due date on every B2B invoice an order under that location generates.

Every /v1/payment-terms request also requires the store to hold the B2B feature; same read-always, write-refused-when-frozen split (403 Forbidden, { "code": "FEATURE_FROZEN", "feature": "b2b" }).

B2B invoices — b2b-invoice:list / b2b-invoice:read

Read-only accounts-receivable view of a store's net-terms invoices — generated automatically when an order is placed under a company location that carries a payment term. There is no public create, update, record-payment, or void route: an invoice is a Stripe-backed order artifact, so ERPs pull its state through this surface (or through the b2b_invoice.* webhook topics) rather than minting one, and recording a payment or voiding stays a vendor-dashboard action.

Reads work regardless of B2B entitlement, the same as every other company:*-family surface — there simply is no write route here for the entitlement guard to refuse.

The response never includes stripeInvoiceId — that id must never leave the server. It does include hostedInvoiceUrl, a link to the Stripe-hosted invoice page you can hand a buyer or file alongside your own AR record.

Assistant-granted scopes

The two families below gate live /v1 endpoints, but neither a plugin install nor a store API key can hold them. Their endpoints carry consent semantics (tiered read / safe-write / live-write approval) that only the flow a merchant completes when connecting an AI assistant to their store can grant, so the dashboard's key scope picker does not offer them, requesting one on a key is rejected with 400, and they are not accepted in a plugin's oauth.scopes. They are documented here so the catalog is complete and so no integration mints a colliding string.

Pages — page:*

Storefront pages built with the Orbit page builder: draft/publish lifecycle, revision history, and the element catalog the page content is validated against.

Store settings — store-settings:*

Store-level configuration: what the store is, as opposed to settings:*:store above, which is a plugin's own per-store settings surface.

Reserved scopes — import:*

Defined in the catalog but grantable to no credential: not plugins, not API keys, not assistant connections. The core API has no import surface (product import lives elsewhere), so no /v1 endpoint enforces these strings; they are reserved so a future import surface reuses them instead of minting new ones.

Using this page

1. Find the endpoint you need in the API Reference.
2. Pick the matching scope from the tables above.
3. Declare it in your plugin's oauth.scopes (in the partner-dashboard plugin form, or via JSON import).
4. When a merchant installs your plugin, they see those scopes on the consent screen.
5. After install, your token's scopes claim contains everything you declared, and the API enforces that set on every call.

Request only the scopes you actually use — a smaller set is easier for merchants to approve and limits exposure if a token leaks. If you need something that isn't listed here, it isn't available on the public API yet; reach the team at developers@orbitcommerce.net rather than guessing a string, since any scope not in this catalog will never be granted.

Versioning

These scope strings are version-independent — /v1 and any future version share the same catalog. The OAuth handshake (/oauth/*) is rooted at the host (deliberately not under /vN), so your token flow never changes when the data API version bumps. New scopes are only ever added alongside the endpoints they protect; plugins that don't request a new scope are unaffected.

Last updated: 2026-08-28.