Scopes consent
Scopes declared in your Mini's manifest.json describe the user data that your Mini can access through the Shop Minis SDK. Some hooks require specific scopes before they can return protected data, such as profile information, saved products, followed shops, or order history.
Scope consent gives users control over that access. A user can grant the scopes that your Mini requests, continue without granting them, or later disconnect your Mini from their Shop app account settings.
Anchor to How scope consent worksHow scope consent works
Scope consent follows these rules:
- Scopes are declared in your manifest. Add only the scopes that your Mini needs for its user-facing features. Scope requests are reviewed when your Mini is submitted.
- The consent prompt appears when it's needed. Shop asks for consent when your Mini uses a hook that requires a scope that the user hasn't granted yet. If your Mini calls that hook during initial load, then the prompt appears during initial load.
- The choice is all or nothing. The consent sheet asks for the scopes that still need consent. Users grant or reject those scopes together, without choosing individual scopes.
- Consent is remembered. After a user grants scopes, your Mini can use those granted scopes across sessions. Users can disconnect your Mini from their Shop app account settings, which removes previously granted scopes.
- New scopes create a partial consent state. If you add scopes in a later version, then returning users might have granted the older scopes but not the new ones. Ask for the missing scopes in context.
- Sensitive data might require another confirmation. Some experiences that use sensitive data, such as order history, might ask users for an additional confirmation before showing that data.
Anchor to Design for every consent stateDesign for every consent state
Granting scopes is optional. Your Mini should provide a useful experience whether the user grants, rejects, or hasn't yet granted scopes.
Use these patterns when you design scope-protected features:
- Explain the value before asking. Show what the user gets by granting access before you request consent.
- Keep the core experience usable. Don't block the entire Mini when one feature needs a scope.
- Provide a fallback state. If a feature can't run without a scope, then show an empty state, preview, or call to action instead of removing the feature.
- Respect rejection. Treat rejection as a normal user choice. Don't repeatedly show the consent sheet after the user declines.
- Plan for new scopes. When you add scopes in a later release, use a partial consent state to explain why you're asking for more access.
Anchor to Use consent hooks for explicit consent UXUse consent hooks for explicit consent UX
The SDK exposes two hooks for consent-aware UI:
useCheckScopesConsentreturns the current scope consent status for your Mini. Use it to check whether consent isgranted,partially_granted, ornot_granted.useRequestScopesConsentreturns arequestScopesConsent()function that shows the consent sheet. Use it in response to a clear user action, such as tapping a button for a feature that needs access.
After requestScopesConsent() resolves, call refetch() from useCheckScopesConsent to read the updated status.
Don't call requestScopesConsent() automatically when your Mini loads or on every render. Ask for consent after the user expresses intent to use a feature that needs scoped access.
Don't call requestScopesConsent() automatically when your Mini loads or on every render. Ask for consent after the user expresses intent to use a feature that needs scoped access.
A request might be temporarily unavailable if another permission or consent prompt is already showing, or if consent status is still loading. Handle this as a normal retry state in your UI.
Anchor to After a user rejects consentAfter a user rejects consent
If a user rejects a consent prompt, then hooks that require the missing scope can't access the protected data. Show the user a fallback state and let them continue using the rest of your Mini.
If you want to let the user reconsider, provide an in-context action that calls requestScopesConsent(). For example, an order history screen might show a Connect order history action after the user previously declined order access.
