OAuth Scope Catalog
Every OAuth scope a third-party plugin can request on the Orbit Commerce public API (api.myorbitcommerce.net/v1/*, plus the /oauth/* token handshake). 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.
This page is the public contract — the scope strings here are exactly the strings the API enforces. Copy them verbatim. For how scopes are requested, consented to, and checked at runtime, see the Scopes guide; for the endpoint-by-endpoint detail, see the API Reference.
Naming convention. Scopes are
<resource>:<action>. The resource is singular and kebab-case (product,customer,tracking-script— neverproductsortrackingScripts). The action is one oflist,read,create,update,delete. Soproduct:writeis invalid (writeis not an action — useupdate), andproducts:readis 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 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).
| Scope | Grants |
|---|---|
product:list | GET /v1/products (filtered, paginated), GET /v1/products/sync (lightweight sync variant), POST /v1/products/batch-lookup. Required for any plugin that iterates the catalogue. |
product:read | GET /v1/products/{id}. Pair with product:list for plugins that fetch detail after listing. |
product:create | POST /v1/products. Used by import plugins and marketplace inbound (Amazon → Orbit, eBay → Orbit). |
product:update | PATCH /v1/products/{id}, PATCH /v1/products/bulk-update. Used by sync plugins to push price, inventory, and SEO updates from external sources. |
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, plus create-on-behalf-of and status sync for marketplace plugins.
| Scope | Grants |
|---|---|
order:list | GET /v1/orders. Iteration for sync and reporting plugins. |
order:read | GET /v1/orders/{id}. Order detail. |
order:create | POST /v1/orders. Used by marketplace plugins that import orders from an external platform as native Orbit orders. |
order:update | PATCH /v1/orders/{id}. Sync an order's status, paymentStatus, or notes — e.g. when a marketplace fulfilment or cancellation changes. |
order:update is deliberately narrow: pricing, line items, currency, and addresses are not editable through it (and a paid + fulfilled order seals those fields). The rest of order lifecycle — refunds, cancellation workflows — stays 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).
| Scope | Grants |
|---|---|
customer:list | GET /v1/customers, GET /v1/customers/by-email/{email}. Used by reviews ("which customer left this review?"), order-import plugins (resolving buyer identity), and marketing/CRM plugins. |
customer:read | GET /v1/customers/{id}. Customer detail. |
customer:create | POST /v1/customers. Create a customer — e.g. mirroring a CRM contact into Orbit, or registering a buyer imported from a marketplace. |
customer:update | PATCH /v1/customers/{id}. Update a customer's details. |
customer:delete | DELETE /v1/customers/{id}. Remove a customer. |
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.
| Scope | Grants |
|---|---|
taxonomy:list | GET /v1/taxonomies. Hierarchy walk for feed plugins (category mapping). |
taxonomy:read | GET /v1/taxonomies/{id}, GET /v1/taxonomies/by-handle/{handle}. |
In Orbit's vocabulary, a taxonomy is the classification tree. What other platforms call a "category" (a curated product collection) is a separate concept and is not on the public API yet.
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.
| Scope | Grants |
|---|---|
tracking-script:read:store | GET /v1/tracking-scripts/{provider}. Reads the active script for one provider on the current store. |
tracking-script:update:store | PUT /v1/tracking-scripts/{provider} (upsert; clear a script by writing an empty value). |
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).
| Scope | Grants |
|---|---|
settings:read:store | GET /v1/settings. Returns your plugin's settings merged with the schema defaults. |
settings:update:store | PUT /v1/settings. Partial-merge update; values are validated against your settingsSchema. |
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.
| Scope | Grants |
|---|---|
billing:read | Read-only billing: plans, subscription status, and the merchant's saved payment methods (orbit.billing.getPlans(), getStatus(), getPaymentMethods()). |
billing:update | Create charges and manage subscriptions: subscribe, change plan, cancel, restore (orbit.billing.requestPurchase(), subscribeToPlan(), cancelSubscription(), restoreSubscription()). |
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.
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.
| Scope | Grants |
|---|---|
webhook:list | GET /v1/webhooks. List your subscriptions. |
webhook:read | GET /v1/webhooks/{id}/deliveries. Recent delivery history for a subscription (useful for debugging). |
webhook:create | POST /v1/webhooks. Subscribe to a topic at runtime. |
webhook:delete | DELETE /v1/webhooks/{id}. Unsubscribe. |
Using this page
- Find the endpoint you need in the API Reference.
- Pick the matching scope from the tables above.
- Declare it in your plugin's
oauth.scopes(in the partner-dashboard plugin form, or via JSON import). - When a merchant installs your plugin, they see those scopes on the consent screen.
- After install, your token's
scopesclaim 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-05-31.