How to Set Up Headless Shopify: Step-by-Step Guide

A headless Shopify storefront can give a brand more control over design, content, performance, and integrations while preserving Shopify’s commerce capabilities. However, setting one up involves more than connecting a React application to a product API.

A production storefront must handle product discovery, variants, pricing, inventory, carts, customer accounts, markets, analytics, SEO, checkout, third-party services, and failure states. It must also give content and commerce teams a practical way to operate the store after launch.

This guide walks through that complete process using Shopify’s Hydrogen and Oxygen stack as the primary route. It also explains where a custom framework or hosting provider may fit.

What Is Headless Shopify?

Headless Shopify is an eCommerce setup where Shopify manages products, inventory, customers, orders, and checkout, while the customer-facing storefront is built separately.

The storefront connects to Shopify through APIs:

• Storefront API: Handles products, collections, search, carts, localization, and checkout URLs.
• Customer Account API: Manages authenticated customer profiles, orders, payments, fulfilment, discounts, and refunds.
• Admin API: Supports private administrative operations and backend integrations.

Businesses can build the storefront using Shopify’s React-based Hydrogen toolkit and deploy it through Oxygen. They can also use another compatible frontend framework and hosting platform.

Before You Begin: Confirm That Headless Is Appropriate

Headless is worth considering when a standard Shopify theme cannot efficiently support the required customer experience, content model, integrations, markets, or development workflow.

It is not a necessary upgrade for every store. If your primary challenges involve weak traffic, poor merchandising, unclear positioning, or a slow theme caused by unoptimized media and scripts, a full rebuild may add cost without solving the underlying problem.

Before proceeding, document:

Once these requirements are clear, you can decide what belongs in Shopify, what belongs in the frontend, and which additional services are genuinely necessary.

Step 1: Choose Your Headless Shopify Architecture

There are two common routes.

Option A: Hydrogen with Oxygen

Hydrogen is Shopify’s official React-based toolkit for building custom storefronts. It provides commerce-focused utilities, Storefront API integration, caching patterns, routes, cart functionality, SEO support, and other foundations.

Oxygen is Shopify’s hosting platform for Hydrogen storefronts. It supports edge deployment, preview environments, environment variables, logs, and deployments connected to GitHub or a custom CI/CD workflow.

This route is usually the best starting point when:

• The project is new and centered on Shopify.
• The team works comfortably with React.
• Tight integration with Shopify’s APIs is valuable.
• The business wants a more opinionated commerce foundation.
• Oxygen meets the hosting and operational requirements.

Option B: Your Own Stack

Shopify’s Storefront API can also support custom storefronts built outside Hydrogen. This can suit businesses that already standardize on a particular framework, hosting provider, observability platform, or deployment process.

This route offers more architectural freedom but also requires the team to make more decisions about rendering, caching, sessions, cart persistence, analytics, security, and API clients.

Choose the stack your team can maintain, not merely the framework with the most impressive demo.

Step 2: Prepare the Shopify Store

Before connecting a frontend, configure the Shopify backend properly.

Add representative products, variants, collections, menus, media, prices, inventory, shipping rules, discounts, policies, and markets. Development with placeholder products often hides issues that appear later with real option combinations, long titles, unavailable variants, regional catalogues, or complex media.

Also identify the systems that remain authoritative:

• Shopify for products, inventory and orders
• A CMS for editorial content
• A PIM for product information, if applicable
• An ERP for operational or financial data
• A search platform for advanced discovery
• A customer data or analytics system for behavioral information

Do not duplicate ownership unnecessarily. If two systems can edit the same field without a clear synchronization rule, content and product data will eventually conflict.

Step 3: Install the Appropriate Shopify Sales Channel

The sales channel depends on your delivery route.

• Use the Hydrogen channel when building a Hydrogen storefront with Oxygen.
• Use the Headless channel when self-hosting Hydrogen or building with another stack.

These channels connect a custom storefront to Shopify, provide access to the Storefront API and Customer Account API, and help manage storefront credentials and order attribution.

Avoid tutorials that instruct you to create a legacy private app. That workflow is outdated. Use Shopify’s current Hydrogen or Headless channel instead.

Ensure that relevant products are published to the custom storefront’s sales channel. A valid API connection will not return products that are unavailable to that channel or market.

Step 4: Create a Hydrogen Project

For the Shopify-native route, ensure your development environment meets the current Node.js and npm requirements stated in Shopify’s Hydrogen documentation.

Create a quick-start project:

npm create @shopify/hydrogen@latest -- --quickstart

The --quickstart option creates a project with Shopify’s recommended starter choices and Mock.shop product data. Remove that flag if you want to select the setup options individually.

Move into the generated project and start the development server:

cd hydrogen-quickstart
shopify hydrogen dev

The starter includes routes and patterns for common storefront requirements, including products, collections, cart, search, accounts, policies, robots.txt, and the XML sitemap.

Treat it as a foundation rather than a finished store. Review the generated architecture before adding custom design and integrations.

Step 5: Link Hydrogen to Your Shopify Store

The new project initially uses Mock.shop data. Link it to the Shopify store:

npx shopify hydrogen link

Follow the prompts to sign in, choose the Shopify store, and select or create a Hydrogen storefront.

Next, pull the storefront’s environment variables:

npx shopify hydrogen env pull

This supplies the project with values such as the store domain, Storefront API credentials, storefront ID, and Customer Account API settings.

Restart the development server and verify that the application displays products from the intended Shopify store.

Never commit secret tokens or production credentials to the repository. Separate local, preview, and production environments, and expose only values designed for public use to browser code.

Step 6: Understand How Storefront Data Is Queried

Shopify’s Storefront API uses GraphQL. Instead of receiving a fixed response, the storefront requests the fields required by a page or component.

A simplified product query may look like this:

query Product($handle: String!) {
  product(handle: $handle) {
    id
    title
    description
    featuredImage {
      url
      altText
      width
      height
    }
    options {
      name
      optionValues {
        name
      }
    }
    selectedOrFirstAvailableVariant {
      id
      availableForSale
      price {
        amount
        currencyCode
      }
    }
  }
}

In a real product page, the team must also handle:

• Several product options and variant combinations
• Unavailable and sold-out variants
• Market-specific price and availability
• Product media and accessible alternative text
• Metafields and metaobjects
• Subscriptions or selling plans
• Recommendations, bundles and related products
• Structured data and canonical URLs
• Errors and missing products

Request only the fields each route needs. Large, repeated GraphQL queries increase response time and make the storefront harder to maintain. Reuse fragments where they improve consistency, and choose caching rules according to how frequently the underlying data changes.

Step 7: Build the Essential Commerce Journeys

A storefront is not complete when products appear on the homepage. Implement and test the complete route from discovery to purchase.

Navigation, collections and search

Build menus, collection pages, filters, sorting, pagination, predictive search, and empty states around real catalogue behavior. Confirm that merchandising changes in Shopify appear as expected.

Product pages

Support product options, variant selection, pricing, availability, media, quantity rules, selling plans, delivery information, recommendations, and required metafields.

Cart

Use Shopify’s cart flow to create a cart, add and update lines, apply buyer context and discount information, and retrieve the checkout URL. Decide how cart state persists across sessions and devices.

Checkout handoff

The custom storefront hands the buyer to Shopify’s checkout using the URL associated with the cart. Do not describe the Storefront API as providing unrestricted checkout customization; checkout capabilities depend on Shopify’s supported checkout extensibility and plan features.

Test discounts, Shop Pay, accelerated payment methods, gift cards, duties, taxes, delivery methods, and market context where applicable.

Customer accounts

Use the Customer Account API for Shopify’s current authenticated account experience. Plan login callbacks, profile access, orders, returns-related information, address management, and the relationship between authenticated customers and carts.

Customer Account API authentication requires an appropriate public HTTPS callback during development; localhost alone is not supported for that authentication flow.

Step 8: Connect Content and Third-Party Services

Not every headless store needs a separate CMS. Shopify pages, blogs, metaobjects, and metafields may be sufficient for a commerce-led site with straightforward content.

Consider a headless CMS when the business needs:

• Complex editorial page structures
• Reusable content across channels
• Advanced preview and approval workflows
• Independent localization
• Scheduled campaigns
• Collaboration across large content teams

Define how CMS entries reference Shopify products and collections. Avoid copying prices or availability into the CMS because those values can become outdated.

Audit every storefront app before migration. Reviews, search, subscriptions, loyalty, wish lists, personalization, analytics, consent, and promotional tools may require an API or custom component. If an app only supplies a Liquid snippet or theme block, it will not automatically appear in the headless storefront.

For each integration, document:

• Data owner and direction of synchronization
• Authentication method
• API limits and caching
• Webhooks or update mechanism
• Customer-data exposure
• Failure behavior and fallbacks
• Monitoring and support ownership

Step 9: Implement SEO, Analytics and Consent Before Launch

Do not leave SEO and analytics until development is finished. A custom storefront must deliberately reproduce capabilities that a Shopify theme may have provided automatically.

Technical SEO checklist

• Preserve valuable URLs or map them with permanent redirects.
• Render indexable product, collection and content pages.
• Generate unique titles and meta descriptions.
• Add canonical URLs.
• Implement product, breadcrumb, article and organization structured data where appropriate.
• Generate accurate XML sitemaps and robots.txt.
• Maintain crawlable internal links.
• Handle pagination and faceted-navigation URLs deliberately.
• Return correct status codes for unavailable and removed pages.
• Optimize images, fonts, scripts and Core Web Vitals.
• Implement hreflang and locale-aware canonicals for international stores.

Analytics and consent checklist

• Define the canonical event taxonomy.
• Track product views, collection views, searches, cart actions and checkout initiation.
• Pass stable product, variant, currency and market identifiers.
• Validate campaign attribution across the storefront-to-checkout transition.
• Prevent duplicate events.
• Respect consent choices before activating relevant scripts.
• Compare analytics totals with Shopify and payment data.

Establish baselines before migration so the team can distinguish genuine performance changes from tracking errors.

Step 10: Test the Storefront as a Commerce System

Test with real catalogue structures and real operational rules, not only ideal demo data.

Cover:

• Products with one, several and unavailable variants
• Inventory changes and sold-out items
• Discounts, gift cards and promotional combinations
• Anonymous and authenticated carts
• Account login, logout, orders and addresses
• Different markets, languages and currencies
• Search queries, zero results and misspellings
• Shipping restrictions and delivery methods
• Slow or unavailable third-party APIs
• Expired sessions and API errors
• Mobile devices, browsers and assistive technology
• Metadata, canonicals, structured data and redirects
• Analytics and consent states
• Load, caching and performance behavior

Automated tests are valuable for stable critical flows, but they do not replace exploratory testing with merchandisers, customer-support staff, marketers and real devices.

Step 11: Deploy to Oxygen or Your Hosting Platform

For a Hydrogen storefront using Oxygen, create a preview deployment with:

npx shopify hydrogen deploy

Select the preview environment and review the generated deployment before promoting it to production.

Oxygen supports multiple environments, preview deployments, logs, environment variables, and continuous deployment through GitHub or custom CI/CD.

If you self-host, confirm that the chosen platform supports the runtime and rendering model used by the application. Configure environment variables, caching, domains, TLS, logs, alerts, deployment permissions, and rollback procedures.

Before changing the production domain:

1. Freeze high-risk content and URL changes.
2. Crawl the old and new storefronts.
3. Validate the redirect map.
4. Complete checkout and payment tests.
5. Confirm analytics and consent behavior.
6. Prepare rollback criteria.
7. Assign launch-day owners.
8. Reduce DNS TTL early enough for the migration plan.
9. Monitor errors, traffic, indexing and revenue immediately after launch.

Step 12: Operate and Improve the Store After Launch

Headless Shopify is custom software, so launch is the beginning of its operating life.

Assign ownership for:

• Availability, latency and error monitoring
• Dependency and security updates
• Shopify API-version upgrades
• Integration failures and webhook health
• Core Web Vitals and frontend performance
• SEO crawling and indexation
• Analytics quality
• Incident response and rollback
• Documentation and knowledge transfer
• Conversion experiments and roadmap development

Shopify APIs are versioned, and supported integrations can change. Schedule regular technical reviews rather than waiting until an upgrade becomes urgent.

Common Headless Shopify Setup Mistakes

Starting with a framework instead of a requirement

Technology should follow the customer, operational and commercial problem. Otherwise, the project may recreate a theme storefront using a more expensive architecture.

Assuming every Shopify app will work

Theme blocks and Liquid snippets do not automatically transfer to a custom frontend. Audit app APIs and headless support before committing to the migration.

Rebuilding too much

Keep suitable commerce functions in Shopify. Customizing every capability increases cost, risk and maintenance without necessarily improving the customer experience.

Treating speed as automatic

Headless provides performance control, not guaranteed performance. Set budgets for JavaScript, images, fonts and third-party scripts, then measure them continuously.

Migrating without an SEO specification

URL changes, missing metadata, client-only rendering, redirect gaps and incorrect canonicals can erase organic visibility. SEO requirements belong in architecture, development and QA.

Forgetting the people operating the store

A technically elegant stack can still fail if marketers and merchandisers cannot preview, publish or update it efficiently. Validate editorial workflows before launch.

When Should You Hire a Headless Shopify Specialist?

An experienced internal team may be able to manage the implementation. External support becomes valuable when the project involves unfamiliar APIs, complex integrations, several markets, a high-risk SEO migration, or a fixed commercial launch.

The partner should be able to explain why headless is appropriate, which systems should remain in Shopify, how apps will be replaced or integrated, and how the storefront will be owned after launch.

F22 Labs can support discovery, UX/UI, Hydrogen development, Shopify API integration, testing, migration and post-launch improvement. If your requirements justify a custom storefront, you can hire Shopify experts for the complete implementation or to extend an existing internal team.

Frequently Asked Questions

Do I need Shopify Plus to build a headless Shopify store?

Not every headless storefront requires Shopify Plus. Confirm the plan against the checkout, B2B, international, automation, and organizational features required by your implementation rather than assuming headless and Plus are inseparable.

Is Hydrogen required for headless Shopify?

No. Hydrogen is Shopify’s official React-based toolkit and offers a convenient Shopify-native route, but the Storefront API can support other compatible frontend frameworks and hosting platforms.

What is the difference between Hydrogen and Oxygen?

Hydrogen provides Shopify-focused tools for building a React storefront. Oxygen is Shopify’s global deployment platform for Hydrogen applications, offering environments, previews, logs and edge delivery.

Can Shopify apps work with a headless storefront?

Backend apps may continue working, while features rendered through Liquid or theme blocks require an API, custom frontend component or alternative. Audit every customer-facing app before selecting the architecture.

How does checkout work in headless Shopify?

The storefront creates and updates a cart through Shopify’s APIs, then sends the customer to the cart’s Shopify checkout URL. Available checkout customizations depend on Shopify’s supported extensibility and plan.

Is headless Shopify automatically better for SEO?

No. Headless provides control over rendering and technical SEO, but metadata, structured data, canonicals, sitemaps, redirects, internal links and international targeting must all be implemented and tested correctly.

How long does it take to set up headless Shopify?

A proof of concept can be created quickly, but production timelines depend on design, catalogue complexity, integrations, markets, content migration, accounts, SEO, analytics and QA. Complex replatforming commonly takes several months.

Final Thoughts

Getting started with headless Shopify is technically straightforward: create a storefront, connect it to Shopify’s APIs, and deploy it. Building a dependable commerce experience is the more substantial task.

The best implementations begin with clear requirements, retain Shopify for the functions it already handles well, and customize only where the customer or business gains meaningful value. They also treat SEO, analytics, integrations, testing and maintenance as core architecture, not finishing tasks.

With the right use case and operating model, headless Shopify can provide a flexible foundation for distinctive experiences and long-term growth. Without those foundations, it can turn a manageable store into unnecessary custom software.