Storefront API vs Admin API: Which Should Developers Use?

The Admin API operates with staff-level permissions: create products, fulfill orders, adjust inventory, read customer PII. It requires OAuth for apps or a custom app access token scoped to explicit Admin API permissions. Never expose Admin API tokens in browser JavaScript or mobile apps; any leak grants write access to the merchant's business data.

The Storefront API is buyer-scoped. Tokens (public or private) allow reading catalog data, managing a cart, and initiating checkout. It cannot delete products, read all orders, or export customer lists. That reduced surface is intentional: headless storefronts, mobile apps, and kiosk UIs run Storefront API calls client-side or on a thin BFF (backend-for-frontend) without holding admin keys.

Choosing the wrong API is a security incident waiting to happen. If your React storefront uses Admin API 'just to fetch products,' rotate that token immediately and migrate to Storefront API with properly exposed metafields.

Storefront API GraphQL supports products, collections, menus, pages, cart mutations (cartCreate, cartLinesAdd, cartLinesUpdate), and checkout URLs via cart.checkoutUrl. It is the backbone of Hydrogen, Next.js commerce stacks, Nuxt storefronts, and native mobile apps.

Typical flow: server or edge function holds a Storefront API private token, client sends queries for PLP/PDP data, cart mutations run in the buyer session with cart ID persisted in cookies or localStorage. Checkout still happens on Shopify-hosted checkout unless you are on Shopify Plus with custom checkout extensions.

Limitations matter: no draft orders, no refund APIs, no bulk admin queries, and metafields must be explicitly exposed on definitions. Real-time inventory uses availableForSale and quantityAvailable fields; high-velocity flash sales may still oversell at checkout boundary the same as AJAX cart themes.

Admin API GraphQL (REST is legacy) powers Shopify apps: ERP sync, WMS fulfillment, CRM integrations, subscription billing backends, and custom admin UI embedded in Shopify admin. Mutations like productCreate, orderMarkAsPaid, and inventoryAdjustQuantities belong here.

Custom apps installed on a single store use offline access tokens for background jobs and online tokens for per-user admin requests. Public apps go through OAuth with granular scopes; request minimum scopes and use webhooks (orders/create, products/update) instead of polling.

Admin API rate limits are cost-based (GraphQL query complexity). Bulk operations (bulkOperationRunQuery) handle large catalog exports. For theme developers who do not build apps, direct Admin API usage is rare unless you operate a separate middleware service for B2B portals or internal dashboards.

Classic Online Store 2.0 theme development is Liquid-first. Products, collections, and cart state are server-rendered; AJAX cart uses /cart/*.js endpoints, not GraphQL. Metafields are read in Liquid; dynamic sources connect editor settings to metafields without API calls.

Reach for Storefront API inside a theme only for isolated client-side features: live personalization, 'Recently viewed' from an external index, or hybrid widgets. Even then, prefer Theme App Extensions with app proxies or embedded app blocks so secrets stay server-side.

Admin API has no place in theme assets. If a freelancer puts Admin API fetch in theme.js, that is an automatic security finding. Use app proxies (/apps/your-app/*) to call your backend, which holds Admin credentials, and return sanitized JSON to the theme.

Use Storefront API when: building headless/Hydrogen/custom frontend, mobile app commerce, buyer-facing cart and catalog outside Liquid, or public kiosk with read-only catalog plus cart.

Use Admin API when: building a Shopify app, syncing inventory from warehouse software, generating invoices, managing products programmatically, or reading order/customer data for support tools.

Use Liquid + Cart AJAX when: customizing the Online Store theme, optimizing conversion on standard checkout, or delivering OS 2.0 sections, which covers most D2C brands ADSPOC serves.

Hybrid architectures are common: Liquid theme for SEO-stable PDPs plus a React mini-app on /apps/lookbook powered by Storefront API. Document which layer owns cart authority; never split cart state across Liquid session and headless cart without a unified checkout handoff.