The Shopify app development guide.
Public or private, embedded or standalone, GraphQL or REST, submission to the App Store. Every decision an app developer faces, with the tradeoffs.
Five decisions. Each one shapes the build.
Building a Shopify app means making five decisions before writing code. Public (App Store) or custom (private install on one store)? GraphQL Admin API or REST? Embedded (renders inside the admin via App Bridge) or standalone? React framework on Remix or Next.js? Hosted on Shopify's recommended Cloudflare Workers + Hydrogen-style stack, or your own infrastructure? The right answers depend on the audience, the complexity, and the team's existing skills. Get them aligned before scoping; misalignment late surfaces as a six-month rebuild. Published by Prasun Anand.
Public app or custom (private) app?
The first decision is distribution model. Public apps go through Shopify's App Review process and become listed in the App Store. Custom apps (formerly "private") install on a single store with no review, no listing, no public discoverability. The choice depends entirely on whether you want one merchant or many.
Public apps. Distribution to thousands of merchants, recurring revenue through Shopify's billing API, App Store presence with listing optimization opportunities, App Review process taking two to six weeks for first approval, mandatory GDPR webhooks (customer data request, customer redact, shop redact), ongoing maintenance for new Shopify API versions, listing localization for international markets. The path for SaaS-style ambitions.
Custom apps. Single-store install, no review process, full Admin API access without App Store gatekeeping, no billing complexity, no GDPR webhook requirement (still recommended for compliance), no localization burden. The path for one-off integrations: a custom B2B portal, an internal ops tool, an integration with a specific ERP that only one merchant needs.
The hybrid: build a custom app for your first paying client, validate the use case, then convert to a public app for distribution. We have done this path multiple times; the conversion adds two to four weeks of engineering work for the App Store submission requirements (GDPR webhooks, billing flow, listing assets, App Review fixes). The full public-vs-custom decision matrix including the App Store revenue economics is in Shopify public vs private app.
GraphQL is the primary API now.
Shopify's GraphQL Admin API has been the primary surface since 2024. REST Admin API is in maintenance mode with some endpoints already deprecated. New apps build on GraphQL; existing REST integrations need migration plans on Shopify's published deprecation timeline.
The advantages. Single request for nested data: get a product with variants + images + inventory levels in one call instead of four. Cost-based throttling: pay for actual query complexity (typed cost in points) rather than per-request limits, which makes large queries cheaper than equivalent REST workflows. Strong schema: the API documents itself, IDE tooling can autocomplete and validate, breaking changes surface at build time instead of runtime. Forward compatibility: Shopify ships new fields as additions to the schema, never as breaking changes within an API version.
The migration path for REST. Identify every REST endpoint your app uses. Find the GraphQL equivalent (Shopify's docs cross-reference REST endpoints to GraphQL queries / mutations). Rewrite the data layer to use GraphQL. The work is two to eight engineering weeks depending on app complexity. Plan it; do not skip it. The deprecation timeline accelerated through 2024 and apps still on REST will hit hard deadlines on specific endpoints.
The depth on GraphQL — including the cost model, the bulk operations API for large data pulls, and the typical query patterns for catalog / orders / inventory — is in Shopify GraphQL Admin API.
Embedded is the default in 2026.
Embedded apps render inside the Shopify admin via App Bridge. Merchants never leave the Shopify UI. Standalone apps run on their own URL with OAuth authentication. Shopify's design system, the App Store ranking signals, and merchant expectations all favor embedded for new apps.
Embedded benefits. The merchant experience is seamless — settings live next to the products and orders in the admin, navigation feels native, the back button works as expected. Authentication is session tokens through App Bridge with automatic refresh; no separate login. The Polaris design system gives you a UI library that matches the rest of the admin without extra design work. App Store ranking favors embedded; standalone apps get penalized in placement.
Standalone benefits, when they apply. Apps that serve non-merchant users (customer-facing portals, B2B buyer experiences, partner-facing portals) cannot embed because the audience does not have admin access. Apps that need desktop-class UI surfaces the embedded environment cannot provide (real-time collaborative editing, complex visualization tools) sometimes need standalone for the screen real estate. Apps that integrate with multiple commerce platforms (Shopify plus BigCommerce plus WooCommerce) often go standalone to avoid platform-specific UI work.
App Bridge depth — the session token model, the iframe communication patterns, the resource picker integration — is covered in detail in Shopify embedded vs standalone.
App Review takes two to six weeks.
Shopify's App Review process exists to keep the App Store from filling with broken or deceptive software. The first review usually returns three to ten review issues that need fixing before approval. Plan for two review rounds in your launch timeline; budget six to eight weeks from first submission to live listing.
Common rejections. Incomplete GDPR webhook implementation (the three mandatory webhooks must be wired and respond correctly to test calls). Billing flow that does not handle all edge cases (free trial expiry, plan changes, cancellation, store transfers). Installation flow with bugs (most often: OAuth callback handling on edge cases). Listing copy that does not accurately describe functionality (overstated capability, missing limitations). Privacy policy URL invalid or insufficient. Support contact path missing or broken.
The quality bar. Shopify's reviewers are generally constructive — the issues they raise are real ones that would surface as merchant complaints later if shipped. We treat App Review as free QA. The detailed pre-submission checklist covering all 14 mandatory items, plus the listing optimization patterns that improve conversion in the App Store, are in Shopify app submission checklist.
The billing API. Shopify's billing handles trials, recurring charges, usage-based billing, and one-time charges through the AppSubscription mutations in GraphQL. Implement once, get global payment processing, automated invoicing, and tax handling for free. The 80/20 split — Shopify takes 0 percent of an app's first USD 1M annual revenue, 15 percent above that — is the most generous in the marketplace economy.
Webhooks need idempotent handlers and HMAC verification.
Webhooks are the way Shopify notifies your app of events: order created, product updated, customer created, app uninstalled. Three categories matter — business webhooks for app functionality, mandatory GDPR webhooks for App Store approval, and the app/uninstalled webhook for cleanup. Every handler must be idempotent and HMAC-verified.
Idempotency. Shopify's webhook delivery is at-least-once. The same event can fire twice if the first delivery times out and Shopify retries. Handlers that create database rows or send emails on every webhook delivery will create duplicates. The fix: store the webhook ID (X-Shopify-Webhook-Id header) and check for prior processing before doing any work. Standard pattern, not optional.
HMAC verification. Every webhook request includes an X-Shopify-Hmac-Sha256 header with an HMAC signature derived from the request body and your app's shared secret. Verify the HMAC on every request; reject any that fail. Without verification, anyone can POST fake events to your webhook endpoints. With verification, only Shopify can. The implementation is 5 to 10 lines of code in any web framework; skip it and you ship a security hole.
The mandatory GDPR webhooks. customers/data_request when a merchant requests a customer's data (you respond by sending the merchant the customer's data your app stores). customers/redact when a customer requests deletion (you delete their data). shop/redact when a store uninstalls your app and 48 hours have passed (you delete all data for that shop). Shopify's App Review tests these endpoints with synthetic requests; they must respond correctly.
Six answers.
Should I build a public or private Shopify app?
Private (custom) for one-store internal tools. Public (App Store) for distribution to multiple merchants. The decision is really about distribution model. Custom apps install only on stores where you have an admin account, no review process, no billing infrastructure. Public apps go through Shopify's App Review process (two to six weeks), need GDPR compliance webhooks, payment integration through Shopify's billing API, and ongoing maintenance for new Shopify API versions. If your goal is recurring revenue from many merchants, public is the path. If you are building a one-off integration for your own store or a specific client, custom wins.
What is the difference between GraphQL Admin API and REST Admin API?
GraphQL is Shopify's primary API since 2024 — REST is in maintenance mode and some endpoints already deprecated. GraphQL lets you fetch exactly the data you need in a single request: get a product with its variants, images, and inventory levels in one call where REST would require four. Cost-based throttling on GraphQL is also more efficient — you pay for the actual query complexity rather than per-request limits. Build new apps on GraphQL. Existing REST integrations should plan migration; the deprecation roadmap is published quarterly in Shopify's developer changelog.
Should my app be embedded or standalone?
Embedded apps render inside the Shopify admin via App Bridge — the merchant never leaves the Shopify UI. Standalone apps run on their own URL with the merchant authenticating via OAuth. Embedded is now the strongly recommended path for new apps; Shopify's app surface design assumes embedded, the App Store rewards embedded with better placement, and merchants expect the in-admin experience. Standalone is appropriate only for apps that serve non-merchant users (customer-facing portals, B2B buyer experiences) or apps that need a desktop-class UI surface the embedded environment cannot provide.
How long does Shopify App Store submission take?
Two to six weeks for the first review, depending on app complexity and reviewer queue. The first round usually returns three to ten review issues that need fixing. Common rejections: incomplete GDPR webhook implementation, billing flow not handling all edge cases, app installation flow with bugs, listing copy that does not accurately describe functionality. Plan for two review rounds in your launch timeline. Shopify's App Review team is generally constructive — the issues they raise are real ones that would surface as merchant complaints later if shipped. Treat the review as free QA.
What is App Bridge and why does every embedded app need it?
App Bridge is the JavaScript library that handles communication between an embedded Shopify app and the Shopify admin. It manages authentication (session tokens with one-hour expiry, automatic refresh), navigation (so the back button works correctly inside the embedded iframe), modals, toasts, and resource picker UI. App Bridge 4 (current as of 2024) replaced the older App Bridge 2 with a cleaner API and React hooks. Without App Bridge, the iframe authentication and cross-origin restrictions make embedded apps unworkable. Every embedded app installs App Bridge as the first dependency.
How do Shopify app webhooks work?
Webhooks are the way Shopify notifies your app when events happen on a merchant's store: order created, product updated, customer created, app uninstalled. Your app subscribes to specific topics and receives HTTP POST requests when matching events fire. Three categories matter: business webhooks (orders, products, customers, inventory) for app functionality; mandatory GDPR webhooks (customer data request, customer redact, shop redact) required for App Store approval; and the app/uninstalled webhook for cleanup. Webhook delivery is at-least-once, so handlers must be idempotent. HMAC verification on every request protects against spoofing.
App Bridge plus GraphQL. Done right.
More from Ben.
Account Manager · UK B2B · London · 3 posts on the site
Published .