🛒Headless Commerce with Shopware 6 – how to cleanly connect the frontend framework and API shop⚙️

You have a Shopware 6 store and want to build your own frontend with Vue, React, Next, or Nuxt. Welcome to the headless world. Here, you separate the shop logic from the storefront, retrieve all data via the API, and design the frontend exactly as you need it. Sounds like a lot of freedom. And it is. But without a plan, things can quickly get chaotic.

In this article, I'll show you how to approach headless commerce with Shopware 6 in a structured way. You'll learn how the APIs are structured, how to cleanly connect your frontend framework to the shop, and which pitfalls to avoid. All this from the perspective of a developer who likes to laugh but doesn't compromise when it comes to architecture.

If you want to delve even deeper into the topic of headless commerce with Shopware 6, it's worth taking a look at the Official overview of Headless Commerce at ShopwareThere you'll get a good overall view of the platform's headless capabilities.

What exactly does Headless Commerce with Shopware 6 mean?

Headless Commerce means a strict separation between backend and frontend. Shopware 6 handles products, prices, customer data, shopping cart, and checkout. Your frontend framework retrieves this data via the API and presents it on your website, app, or in the store kiosk. Communication takes place via clearly defined endpoints and JSON. No templates from the core. No Twig loops in the Shopware theme.

The major advantage lies in the freedom on the frontend. You can build a landing page in Next.js, a mobile app in React Native, and an in-house ordering system with Vue. All of them communicate with the same Shopware 6 system. The backend remains your single source of truth for commerce data.

If you'd like to review the basics of headless e-commerce at your leisure, a neutral overview like this one will be helpful. Basic article on headless e-commerceThis will help you clearly understand what headless means in architecture and channels.

The architecture of Shopware 6 in a headless setup

Shopware 6 follows an API-first approach. Almost everything you do in the admin panel can also be done via an API. Two main areas are relevant for headless environments: the Store API and the Admin API. Both support HTTP and JSON, but they have different tasks and target audiences.

Store API – your source for all shop data in the frontend

The Store API provides everything your customer experience needs: category structures, product lists, product details, search results, shopping cart, customer account, and checkout. You use this API directly from your frontend framework. With it, you can build classic pages like categories, products, and search, as well as personalized homepages and dynamic widgets.

The key here is to structure your calls clearly. You need a central layer in the frontend that encapsulates all Store API calls. No random fetch calls in every component. Instead, have a separate module for product data, one for customers, and one for the cart and checkout. This way, you maintain an overview, can implement logging, and add caching later.

Admin API – the control center for master data and integrations

You primarily use the Admin API in a backend context. It manages products, prices, inventory, customer data, and orders from external systems. Typical examples include: ERP Integrations, PIM connections, or a custom backend tool for Content Management. The Admin API usually requires separate authentication with a client credential flow.

The Admin API is indirectly important for your headless frontend. It ensures that your Shopware 6 system always has up-to-date data. You should be familiar with it to understand how products and content are imported into the system and why certain fields appear the way they do.

Headless Shopware – E-News for ambitious developers – read up to speed – 🛒Headless Commerce with Shopware 6 – how to cleanly connect the frontend framework and API shop⚙️

Selecting the right frontend framework

For headless commerce with Shopware 6, many teams end up with Vue or React. There are Shopware PWA approaches, starter templates, and example projects. However, you shouldn't be guided solely by hype or your favorite framework. First, think about your team, your maintenance, and the surrounding systems.

Typical options are a classic SPA or an SSR variant with Next.js or Nuxt. For e-commerce, I prefer SSR plus hydration because you have better control over performance and SEO You get this. Your pages can be rendered server-side and are still interactive like a single-page app.

A responsive, mobile-first design is absolutely crucial. Users shop on the go. Most reach for their phone first, not their desktop. Your headless frontend should be designed for small screens from the very beginning. Navigation, filters, search, and checkout must run smoothly on smartphones. Desktop access is almost a bonus after that.

Preparation in Shopware 6: Integrations and API access

Before connecting your frontend framework to Shopware, you need to properly configure the API access in your shop. In Shopware 6, you'll find the "Integrations" section under "Settings and System" in the admin area. There, you create your own API clients, assign keys, and define permissions. This clearly separates which application is allowed to access which resources.

For a customer-facing frontend, you typically need access to sales channels, products, categories, prices, and media. An internal tool might require different permissions. It's better to create multiple integrations and grant each only what it actually needs. This keeps your system lean and reduces risks.

A good introduction to API concepts and integrations is provided by the official Shopware documentationThere you will also find instructions on setting up integrations and working with the API in everyday practice.

Your first request: from access token to product list

Getting started with a headless frontend usually involves three steps. You set up API access, test initial requests with a tool like Insomnia or Postman, and then transfer these calls to the frontend framework. Take your time with this part. If you work carefully here, you'll save yourself many hours of troubleshooting later.

Shopware - for merchants, developers and customers Which Shopware plugins are essential for creating custom product configurators for online furniture stores in Heede?

In the simplest case, you first obtain an access token for your sales channel's Store API. Then you retrieve a product list for a category. In the frontend, you build an initial product overview based on this. Once that's up and running, you can add pagination, filters, and sorting options. Step by step, not all at once.

// stark vereinfachtes Beispiel für einen Fetch Call im Frontend
const response = await fetch('https://dein-shop.de/store-api/product', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'sw-access-key': 'DEIN_SALES_CHANNEL_KEY'
  },
  body: JSON.stringify({
    filter: [
      { type: 'equals', field: 'product.active', value: true }
    ],
    includes: {
      product: ['id', 'name', 'cover', 'calculatedPrice']
    }
  })
});

const data = await response.json();

You can see that you can specify filters, includes, and other parameters. This allows you to control which data you receive and how large your payload will be. This is very important for performance and clarity. You should only retrieve data that the frontend actually uses.

Cleanly structure the API layer in the frontend

If you're working with headless commerce, you should consistently encapsulate your API calls in the frontend. Create a dedicated service layer for Shopware. This layer should only contain functions like getProducts, getProductById, search, addToCart, updateCart, and placeOrder. Components should not access Fetch or Axios directly, but always through these service functions.

This allows you to centrally control authentication, error handling, logging, and caching. If endpoints change or new parameters are added, you only need to make adjustments in one place. Your components remain lean and focused on rendering and user interactions. This makes the project more robust and easier to maintain.

Optimize performance in headless setup

Headless commerce gives you a lot of design freedom. At the same time, you have greater responsibility for performance. Shopware 6 provides a well-structured API. However, how fast the pages feel depends largely on your frontend. You should pay attention to loading time, rendering path, and data volume from the very beginning.

Use caching on multiple levels: browser cache, framework cache, and an API cache. For products and categories, you can store frequently used data in the frontend and only update it when needed. Use lazy loading for images and parts of the page that won't be relevant until later. Implement skeleton states so users can see that something is happening.

A monitoring tool can also help you. Measure Time to First Byte, Largest Contentful Paint, and the most important Core Web Vitals. If you check these regularly, you'll recognize early on when a new feature is slowing down your site. Then you can make adjustments before your conversion rate suffers.

Clean error handling and debugging of your API calls

A headless architecture without good error handling quickly feels broken to users. You should give every API call a clear strategy for error messages. From a frontend perspective, there are roughly three categories: technical errors, such as network problems or timeouts; business errors, such as invalid voucher codes; and unexpected system errors in the shop.

Shopware - for merchants, developers and customers How can Shopware help personalize marketing campaigns for online clothing stores in Lutzhorn through data analysis?

You need separate responses in the UI for each category. A technical error can be explained with a short message and a retry button. Functional errors require a clear explanation of what went wrong and how the user can correct it. System errors should be logged and, if possible, reported centrally. This allows the team to react quickly.

Log both the request and response in an environment you have access to. Avoid using sensitive data such as plaintext passwords or complete credit card information. Focus on endpoints, status codes, and relevant IDs. This will allow you to specifically reproduce and resolve problems.

Typical pitfalls in headless commerce with Shopware 6

Many problems in headless projects revolve less around code and more around coordination. Some are building the frontend, others the ERP or PIM. Shopware 6 sits in the middle. Without clear API responsibilities and clean interface descriptions, things will become confusing. Therefore, ensure a shared API document and clearly defined responsibilities.

Another classic mistake is an excessive number of requests. Each product card loads details, images, and prices individually. The same applies to navigation and filters. You should always check which information you can bundle into a single request. Use includes and search points. Think about aggregations, facets, and the design of your lists early on.

One final pitfall is neglecting SEO. Just because your frontend is headless doesn't mean it should be blind to search engines. Use server-side rendering or static site generation, build well-structured headings, meta tags, and easily readable URLs. Keep content and commerce separate but coordinated. Blog, Advice and product world should be considered together.

Practical ideas: What you can implement with Headless and Shopware 6

With a headless setup based on Shopware 6, you can build far more than a classic shop front. You can develop a product consultation tool for tablets within the store, a configurator for complex products, or a community platform with direct integration to the shopping cart and checkout. Everything accesses the same Shopware data.

Things get really interesting when you combine personalized homepages, dynamic campaign sections, and cross-channel content. Users then see products on the homepage that match their behavior. At the same time, you can run tests and try out different variations in the background. This creates a continuously improving customer experience, all while being centrally managed by one system.

If you like, you can also get inspiration from a developer guide, for example through a German Shopware API Guide for DevelopersThis shows you how other teams model the interfaces and integrate them into their architecture.