Scopes API

The Scopes API lets you manage your app's access scopes at runtime. You can query which scopes are currently granted, request additional optional scopes from the merchant (which opens a permission grant modal), and revoke optional scopes you no longer need.

Tip

To learn more about declaring and requesting access scopes, as well as required vs. optional scopes, refer to manage access scopes.

Anchor to Use casesUse cases

Scope management: Query, request, and revoke optional access scopes dynamically within your app.
Progressive permissions: Request additional scopes only when a merchant needs specific features.
Scope verification: Check which scopes are currently granted before making API calls that require them.
Merchant consent: Trigger the merchant consent flow for optional scopes directly from your app UI.

Anchor to MethodsMethods

The scopes API is available on the shopify global. All methods are asynchronous and return a Promise.

Anchor to query query () => Promise<> required: Returns the current access scopes for this app on this shop, including which are granted, required, and optional.
Anchor to request request (scopes: string[]) => Promise<> required: Opens a permission grant modal asking the merchant to grant the specified scopes.

The scopes must be access scope handles (for example, 'read_products' or 'write_orders') that are declared as optional in your app configuration.

See the permission grant modal documentation for more details.
Anchor to revoke revoke (scopes: string[]) => Promise<> required: Revokes the specified optional scopes from this app on this shop.

The scopes must be access scope handles (for example, 'read_products' or 'write_orders') that are currently granted and declared as optional. Required scopes cannot be revoked.

ScopesDetail

granted
The scopes currently granted to this app on this shop. This includes both required and optional scopes.
```
string[]
```
optional
The scopes declared as optional in your app configuration. These may or may not be currently granted — check `granted` to see which are active.
```
string[]
```
required
The scopes declared as required in your app configuration. These are always granted at install time and cannot be revoked by the app.
```
string[]
```

ScopesRequestResponse

detail
The updated scopes for this app on this shop after the merchant's response.
```
ScopesDetail
```
result
The merchant's response: `'granted-all'` if they accepted all requested scopes, or `'declined-all'` if they declined.
```
UserResult
```

UserResult

The merchant's response to a scopes request: `'granted-all'` if they accepted all requested scopes, or `'declined-all'` if they declined.

'granted-all' | 'declined-all'

ScopesRevokeResponse

detail
The updated scopes for this app on this shop after the revocation.
```
ScopesDetail
```

Examples

js

const {granted, required, optional} = await shopify.scopes.query();

console.log(granted); // => ['read_products', 'write_products', 'read_orders']

console.log(required); // => ['read_products', 'write_products']

console.log(optional); // => ['read_orders', 'write_orders']

Examples

Description

Query the current scopes for your app on this shop. The response includes which scopes are granted, which are required, and which are declared as optional in your app configuration.

js

const {granted, required, optional} = await shopify.scopes.query();

console.log(granted); // => ['read_products', 'write_products', 'read_orders']
console.log(required); // => ['read_products', 'write_products']
console.log(optional); // => ['read_orders', 'write_orders']

Description
Request the merchant to grant additional optional scopes. This opens a permission grant modal where the merchant can accept or decline. The scopes you request must be declared as optional in your app configuration, and each value must be a valid access scope handle such as 'read\_products' or 'write\_orders'.
js
```
const response = await shopify.scopes.request([
  'read_products',
  'write_discounts',
]);

if (response.result === 'granted-all') {
  console.log('Merchant granted access');
} else if (response.result === 'declined-all') {
  console.log('Merchant declined access');
}

console.log(response.detail.granted);
```
Description
Revoke optional scopes that your app no longer needs. The response includes the updated list of granted scopes. Only optional scopes can be revoked — required scopes cannot be removed.
js
```
const response = await shopify.scopes.revoke(['read_products']);

console.log(response.detail.granted);
```

Anchor to RelatedRelated

ReferenceManaging Access Scopes

APIReact Router Scopes API

Was this page helpful?