Downgrade app access scopes from write to read

Starting with Admin GraphQL API version 2027-01, apps that use Shopify-managed installation can call appDowngradeAccessScopes to replace optional write scopes with their matching read scopes. No action is required for existing apps.

What changed

The mutation affects only the calling app’s installation. Requested scopes must be declared in optional_scopes and must be write scopes with matching read scopes. Required scopes can’t be downgraded. Write scopes that aren’t currently granted are ignored. If any requested scope fails validation, the request is rejected and the installation’s scopes remain unchanged.

Revoking a write scope with appRevokeAccessScopes also removes its read access when the read scope was only granted through the write scope. Use appDowngradeAccessScopes when your app still needs that read access.

Who’s affected

This change applies to apps that use Shopify-managed installation and declare optional write scopes with corresponding read scopes. The mutation is available starting with Admin GraphQL API version 2027-01.

What to do

If your app no longer needs write access, call appDowngradeAccessScopes with the optional write scopes you want to downgrade. For example, downgrade write_products to read_products when your app no longer needs to create or update products:

mutation {
  appDowngradeAccessScopes(scopes: ["write_products"]) {
    downgraded {
      handle
    }
    userErrors {
      field
      message
    }
  }
}

The downgraded field returns the write scopes that were successfully changed. Check userErrors for any validation failures.

Related docs

• appDowngradeAccessScopes reference
• API Access Scopes