Migrating an Existing Customer Access Scope to Optional

GraphQL Admin API Troubleshooting
1

Our app includes a feature that sends emails to customers, so it currently requests a customer data access scope during installation.

Shopify supports optional access scopes on 2024-10 Admin API version, we would like to make this sensitive scope optional. However, the scope was originally configured as required, and some existing merchants actively use the email feature.

We cannot simply remove the scope for all merchants and require them to manually approve it again, as this could disrupt existing functionality.

Is there a supported migration path that would allow us to:

  • Preserve the already approved scope for existing installations
  • Make the scope optional for new installations
  • Keep the email feature working without interruption for existing merchants

For example, could this be handled through an access-token migration, token rotation, or selective token expiration, rather than requiring every existing merchant to approve the scope again?

Any guidance on the recommended migration approach would be appreciated!

2

Hey @Angelina_Prokopeva :waving_hand: thanks for reaching out.

You should be able to move the scope from scopes to optional_scopes in shopify.app.toml, then deploy the change without any issue. Existing stores retain the scope as an approved optional scope, without a new prompt or revocation. Your app doesn’t need to request it again for those installations. New installations won’t receive the scope until your app requests it dynamically and the merchant approves it.

There’s no separate access-token migration step in the documented flow. and you can find the migration details here: Manage access scopes

Any protected customer data requirements that apply to the app still apply: Work with protected customer data

I also tested this migration in an earlier thread, where the developer confirmed the same behaviour and I updated our docs after my investigation:

Hope this helps!

3

@Wes-Dev-Shopify thank you for your reply, this is super helpful!