An app that stops editing products may still need to read them. Shopify’s 7 October changelog describes a new mutation for that situation: from Admin GraphQL API version 2027-01, eligible apps can downgrade optional write scopes to their matching read scopes.
The scope downgrade announcement applies to apps using Shopify-managed installation. It says existing apps don’t need to take action. For app teams planning to reduce permissions, the useful distinction is between removing access entirely and retaining the read access their workflow still requires.
Check eligibility before planning the call
The mutation affects the calling app’s installation. Each requested permission must appear in optional_scopes, allow writes and have a matching read scope. Required scopes can’t be downgraded through this operation.
Inventory the app’s current jobs and the permissions each needs. A reporting feature may require reads while a retired product-editing feature no longer requires writes. Record that reasoning beside the proposed scope change. Don’t assume the new mutation applies to every permission in an app configuration.
Confirm the API version in the implementation plan. The announcement names 2027-01 as the starting version, so this isn’t a reason to expect the mutation in an older production API. Keep release-candidate testing and live availability clearly labelled.
Understand the difference from revocation
Shopify explains that revoking a write scope with appRevokeAccessScopes also removes read access when the write permission was its only source. The downgrade mutation addresses the case where an app still needs that read access.
For a fictional catalogue reporting app, retiring its product-editing screen could make write_products unnecessary while its reports still depend on reads. The announcement uses that permission pair as its example. An app owner should verify the actual granted permissions and feature dependencies before changing them.
Include background jobs in that review. A user-facing editing feature may have disappeared while a scheduled task still writes data. Finding that dependency before the downgrade gives the team a chance to retire or redesign the task.
Treat validation as part of the workflow
If any requested scope fails validation, Shopify says the request is rejected and the installation’s scopes remain unchanged. Write scopes that aren’t currently granted are ignored. The response includes downgraded and userErrors; check both.
Build a test case for a valid optional write scope and a case containing an invalid request. Confirm that the app handles the response without reporting a successful permission reduction when nothing changed. These are suggested acceptance checks based on the announced behaviour.
Save the requested scope list and response in the app team’s normal change record. Keep sensitive tokens out of that record. A successful HTTP request alone doesn’t show that the intended scopes changed.
Verify the features that should remain
After a successful test downgrade, exercise the read-only jobs the app is meant to retain. Also try the retired write path in the isolated test environment and check that its failure produces a useful message. Don’t discover those dependencies by changing a merchant’s live installation first.
If the team uses an AI coding assistant for this work, ask it to validate the operation against the relevant schema and keep execution behind normal review. Our Shopify development guide covers schema validation and the risks of automated live changes.
Assign an implementation owner to the scope inventory and test plan.
Author
