Introduction

The phrase shopify app scopes defines the exact permissions an app asks for when it connects to a Shopify store. If you are a Shopify store owner or an entrepreneur building apps or installing third party integrations, understanding scopes is essential to protect customer data, reduce risk, and ensure apps do only what they need to do.

This guide explains what shopify app scopes are, why they matter for privacy and security, and how to choose and implement the minimum set of scopes for common use cases. You will find concrete examples of scope strings, step by step implementation advice, a practical checklist, cost estimates for tools and hosting, common mistakes to avoid, and a timeline for development and app review. Read on to learn how to keep your store secure while enabling the features you need from apps like Klaviyo, ReCharge, Bold Commerce, or custom integrations.

How Shopify App Scopes Work

Shopify app scopes are permission flags used during OAuth (Open Authorization) to grant an app access to specific parts of a merchant store through Shopify APIs (Application Programming Interface). When an app requests scopes, the merchant sees a consent screen listing each scope. The set of granted scopes determines which API endpoints the app can call and whether it can read or write particular resources.

Scope examples:

• read_products and write_products for product data.
• read_orders and write_orders for orders.
• read_customers and write_customers for customer records.
• unauthenticated_read_product_listings for Storefront API public listings.

There are two major API families to consider: the Admin API and the Storefront API. Admin API scopes typically start with read_ or write_ and map to core store entities. Storefront API scopes often cover public storefront behavior and can be restricted to unauthenticated use.

Access mode matters. Shopify supports online access tokens tied to an admin user session and offline access tokens that persist after the merchant leaves. Offline tokens are persistent and often required for background jobs like syncing inventory overnight.

Online tokens expire and are useful when actions must be performed as the acting user.

Real world example: an email marketing app like Klaviyo needs read_customers and read_orders to segment and match purchase behavior. Asking write_products would be unnecessary and likely rejected by a merchant and Shopify app review, unless the app actually modifies product data.

Actionable insight: Request the smallest set of scopes that allow your feature set. For a shipping label app you often only need write_orders, read_shipping, and read_shop. Over-asking increases friction, risks review rejection, and creates security exposure.

Core Principles of Shopify App Scopes

Principle 1 - Least privilege. Always design with the minimum permissions required. Least privilege reduces attack surface if credentials leak and improves merchant trust during install.

Principle 2 - Transparency and justification. During Shopify App Store submission and merchant installs, you must clearly state why each scope is necessary. For sensitive scopes like read_customers or write_orders, prepare a one sentence justification and show UI/UX that explains how data will be used.

Principle 3 - Token lifecycle and access modes. Distinguish offline and online access. Use offline tokens for background processing like nightly syncs, and online tokens when actions must align with a user session and audit trail.

Build refresh flows for online tokens and safe storage for offline tokens.

Principle 4 - Segmentation and least-exposure architecture. If an app only needs read access to orders for analytics, separate components that write to data into a different service with a separate set of credentials and stricter access. Consider microservice patterns or serverless functions for scoped operations.

Numbers and example decisions: If your app syncs sales data to a BI (Business Intelligence) tool once per hour, choose:

• offline access token
• scopes: read_orders, read_products, read_customers
• storage: encrypted database column or secrets manager
• rate limit plan: expect Shopify Admin API limits of 2 calls per second per store with burst credit; design batching to avoid throttling.

Implementation insight: Track scope grants in your database. Store an array or normalized table listing each granted scope and the time it was granted. When you add a feature that needs a new scope, prompt merchants to reauthorize with the new scope only when they try to use that feature.

Step by Step to Choose and Implement Shopify App Scopes

Step 1 - Map features to scopes. Create a simple spreadsheet mapping features to required scopes. Example columns: feature, API endpoints, minimum scopes, access mode, justification for app review.

Checklist example:

• Feature: Abandoned cart emails
• API endpoints: Orders, Checkouts
• Minimum scopes: read_orders, read_checkouts
• Access mode: offline
• Justification: to identify abandoned carts and send targeted emails

Step 2 - Implement OAuth flow. Use Shopify OAuth to request scopes. Use official Shopify libraries or platform SDKs when possible.

scopes = ['read_products', 'read_orders', 'read_customers']

Step 3 - Handle token storage and rotation. Use a secrets manager or encrypted database column. If using online tokens, follow session strategies and implement token refresh or reauthenticate when it expires.

Step 4 - Implement permission checks in code. Before calling an endpoint, validate that the token has the required scope. Deny feature access and prompt reauthorization if not.

Step 5 - Prepare for app review and merchant installs. Document why each scope is needed, add in-app UI that informs merchants what will happen with their data, and include a data deletion flow for when merchants uninstall. Shopify requires a webhook for app/uninstalled to purge stored data on removal if you claim to do so.

Practical numbers and timelines:

• Mapping and planning: 0.5 to 2 days.
• OAuth and basic token handling: 1 to 3 days with existing SDKs.
• Scope-based feature gating and UI prompts: 1 to 3 days.
• End-to-end testing including Shopify App Store notes and webhook uninstall flow: 2 to 5 days.
• App review time: 7 to 21 business days typical depending on scope sensitivity and correctness.

Example real companies and scopes:

• ReCharge (subscription billing) requires write_orders and read_customers for recurring charge workflows.
• Bold Commerce features often need write_products or write_script_tags for storefront modifications.
• Klaviyo typically needs read_customers and read_orders for segmentation and personalized email.

Actionable code check: For each API call wrap with scope assertion so you do not accidentally call an endpoint without permission.

Best Practices and Compliance for Shopify App Scopes

Design for auditability. Log scope grants, token creation times, and which admin user installed the app. Keep logs for at least 90 days for troubleshooting and app review evidence.

Provide an uninstall and data deletion policy. Shopify expects apps to remove merchant data when an uninstall webhook triggers unless previously agreed otherwise. Implement a webhook listener for app/uninstalled and run a deletion job within 7 days.

Adopt encryption and secret management:

• Use AWS Secrets Manager, Google Secret Manager, or HashiCorp Vault for production secrets.
• For small shops, encrypt tokens using a server side key and rotate keys every 90 days.

Monitor rate limits and plan for scale. Shopify Admin API uses a leaky bucket model with a per-store rate limit.

• Example: Instead of calling read_orders per order, fetch orders in 50 order batches with “updated_at_min” and “limit” parameters.
• Use GraphQL bulk operations for large exports. Bulk operations can return millions of records in a few minutes instead of hundreds of small REST requests.

Prepare for sensitive scopes and privacy reviews.

• GDPR (General Data Protection Regulation) compliance note if you operate in or serve European customers.
• A clear privacy policy hosted on an HTTPS domain.
• A business justification for each sensitive scope during the Shopify app review.

Split permissions by role and product offering. If you sell multiple modules, consider separate apps for heavy-write features such as product modification versus analytics-only features. This reduces required scopes per app and can increase merchant adoption.

Real world cost example for compliance and infrastructure:

• Shopify Partners account: free.
• Legal template or privacy policy review: $200 to $2,000 depending on counsel.
• Hosting and secrets: $20 to $200 per month for a small app on providers like Vercel, Render, or DigitalOcean.

Tools and Resources

Developer tools and platforms:

• Shopify CLI - free. Use for app scaffolding, theme work, and local development with Shopify.
• ngrok - local tunnel for testing webhooks and OAuth. Pricing: free tier for basic tunnels, paid plans start at $5 per month for reserved domains and more stable tunnels.
• Postman - API testing. Free tier available, paid plans start at $12 per user per month for team features.
• @shopify/shopify-api (Node.js) and ShopifyAPI Python library - official SDKs, free.

Hosting and deployment:

• Vercel - free hobby tier, Pro $20 per user per month. Good for serverless storefront components.
• Render - free tier for static services, web services from $7 per month. Good for small apps.
• DigitalOcean - basic droplets start at $4 to $6 per month. Useful for more control and background workers.
• AWS Elastic Beanstalk or ECS - pricing varies; expect $25 to $100 per month for small production deployments.

Databases and secrets:

• Heroku removed free dynos; consider Railway, Render, or DigitalOcean managed Postgres. Expect $5 to $15 per month for small DBs.
• AWS Secrets Manager - $0.40 per secret per month plus API charges. HashiCorp Vault community is free but self-hosted.

Testing and monitoring:

• Sentry - error monitoring. Free tier available, paid starting at $29 per month.
• LogDNA, Papertrail - log retention starts around $7 per month.

Libraries and middleware:

• Passport.js and Django Allauth for OAuth flows.
• Shopify App Bridge for embedded app UI.
• GraphQL client libraries such as Apollo or graphql-request for Admin API GraphQL calls.

Pricing and availability summary:

• Development tools: mostly free or low cost (ngrok and Postman free tiers).
• Hosting: $7 to $50 per month for small apps; $100+ for production-ready scale.
• Legal and compliance: $200 to $2,000 one time if you hire counsel.
• Developer time: contractor rates range $40 to $150 per hour based on region and expertise.

Common Mistakes and How to Avoid Them

Mistake 1 - Requesting too many scopes at install. Asking for write_ scopes when you only read increases friction and risk. Avoid by mapping features to scopes and showing a minimal consent screen.

Mistake 2 - Not handling uninstall webhooks. Failing to respond to app/uninstalled can violate Shopify policy and merchant expectations. Subscribe to the webhook and run a deletion or anonymization job within your SLA.

Mistake 3 - Storing tokens insecurely. Plaintext tokens in source code or public repositories are a common leak vector. Use secrets managers or encrypted database columns and rotate keys regularly.

Mistake 4 - Ignoring online vs offline access. Using only online tokens will break background jobs. Decide on access mode per feature and implement both flows if necessary.

Mistake 5 - Failing to prepare justification for sensitive scopes. During app review, be ready to explain why you need read_customers or write_orders. Provide screenshots and a detailed flow.

If you cannot justify, split features into separate apps.

How to avoid these:

• Use a scope mapping spreadsheet and review before coding.
• Implement automated tests that assert scope checks before API calls.
• Add install-time tooltips explaining each scope to merchants.
• Keep a change log for scope additions and notify merchants before asking for reauthorization.

FAQ

What are Shopify App Scopes and Why are They Needed?

Shopify app scopes are permission labels that define what an app can access on a merchant store through Shopify APIs. They are needed to protect merchant and customer data and to ensure apps only perform authorized actions.

How Do I Request Additional Scopes After an App is Installed?

Trigger a reauthorization OAuth flow that requests the additional scopes. Prompt the merchant with a clear justification and only ask when they attempt to use the feature that needs the extra permission.

What is the Difference Between Online and Offline Access Tokens?

Online tokens are tied to an admin user session and typically expire; they are used when actions should be performed as that user. Offline tokens are persistent and are used for background jobs and ongoing syncs that run without an active user session.

Will Requesting Read_customers Cause My App Review to Fail?

Not necessarily. Shopify requires a clear business justification, screenshots of the feature using customer data, and a privacy policy. If you provide clear reasons and demonstrate responsible handling, the review can pass.

How Should I Store Access Tokens Securely?

Store tokens in an encrypted database column or use a secrets manager like AWS Secrets Manager or HashiCorp Vault. Limit access to token storage and rotate keys periodically.

Can I Split Functionality Into Multiple Apps to Reduce Scopes?

Yes. Splitting features into specialized apps reduces the number of scopes each app requests, which can improve merchant trust and simplify app review. Consider separate analytics and write-enabled modules if practical.

Next Steps

1. Create a scope mapping spreadsheet. List each app feature, required Shopify API endpoints, and minimum scopes. Assign a short justification for app review.

2. Implement OAuth using Shopify CLI and an official SDK. Start with offline tokens for sync features and add online tokens as needed for user-scoped actions.

3. Build scope checks and feature gates. Block access if the token lacks required scopes and show clear reauthorization prompts.

4. Prepare documentation and app review materials. Include a privacy policy, a data deletion plan, and screenshots showing how each scope is used.

Technical checklist summary:

• Shopify Partners account created
• Scope mapping spreadsheet completed
• OAuth flow implemented and tested locally (ngrok)
• Token storage encrypted and secure
• App uninstall webhook implemented
• Privacy policy and app review justification ready

Timeline estimate for a single feature app:

• Planning and scope mapping: 1 to 2 days
• OAuth and token management: 2 to 5 days
• Feature code and scope gating: 3 to 7 days
• Testing and documentation: 2 to 5 days
• Shopify app review and launch: 1 to 3 weeks

By following these steps you will reduce risk, speed up app review, and build trust with merchants and customers.

Further Reading

• Top Shopify Embedded Apps
• Shopify App Bridge React Roundup
• Best Shopify Apps Marketing (2025 Roundup)
• Yotpo Shopify Apps Guide for Shopify Stores