Decoupling Shopware 6 Storefronts with the Store API: A Practical Guide

Problem: A Headless Frontend Needs a Fast, Stateless API

When you want to build a custom React or Vue app on top of a Shopware 6 backend, the first hurdle is the communication layer. The traditional storefront is tightly coupled to the core logic, but a headless architecture requires a clean, stateless interface that can be consumed by any frontend.

Thesis: Use the Store API, Context Tokens, and Criteria for Optimal Performance

The Store API is Shopware’s API‑first gateway for all customer‑facing operations. By leveraging the sw-context-token to maintain session state and the flexible Criteria object to request only the data you need, you can keep the API lean and the frontend snappy.

1. The Store API vs. the Admin API

• Store API – Public, stateless, optimized for customer actions (cart, product listing, checkout).
• Admin API – Internal, authenticated via OAuth, used for backend management.

For a headless frontend you only need the Store API. It exposes endpoints like /store-api/product and /store-api/checkout/cart.

2. The Context Token – Your Stateless Session

Each request to the Store API must include a sw-context-token header. This token holds:

• Current customer group (e.g., B2B, B2C)
• Currency and locale
• Cart reference for the user session

To obtain a token you send a handshake request with a sales‑channel API key:

curl -X POST \
  "https://yourshop.com/store-api/authenticate" \
  -H "Content-Type: application/json" \
  -H "sw-Api-Key: <sales‑channel‑api‑key>" \
  -d '{}' \
  -i

The response headers will contain sw-context-token. Store it in local storage or a cookie and send it with every subsequent request:

curl -X GET \
  "https://yourshop.com/store-api/product/123" \
  -H "sw-context-token: <token>" \
  -H "sw-Api-Key: <sales‑channel‑api‑key>"

3. Criteria – Request Only What You Need

The Store API’s Criteria object lets you filter, sort, and limit the fields and associations returned. Over‑fetching can lead to heavy DB queries and large payloads.

Example: Retrieve a product list but only its ID, name, and price, without loading all media or custom fields.

curl -X GET \
  "https://yourshop.com/store-api/product?limit=10&sortBy=price&order=asc" \
  -H "sw-context-token: <token>" \
  -H "sw-Api-Key: <sales‑channel‑api‑key>" \
  -H "Content-Type: application/json" \
  -d '{"fields": ["id", "name", "price"], "associations": {}}'

Notice the empty associations object – no media or custom fields will be fetched.

4. Cart Flow – Write Operations Must Be Cautious

Cart updates are write operations. Frequent POSTs to /store-api/checkout/cart/line-item can create a bottleneck if not cached.

curl -X POST \
  "https://yourshop.com/store-api/checkout/cart/line-item" \
  -H "sw-context-token: <token>" \
  -H "sw-Api-Key: <sales‑channel‑api‑key>" \
  -H "Content-Type: application/json" \
  -d '{"id": "p123", "quantity": 2, "type": "product"}'

After adding an item, retrieve the cart to confirm persistence:

curl -X GET \
  "https://yourshop.com/store-api/checkout/cart" \
  -H "sw-context-token: <token>" \
  -H "sw-Api-Key: <sales‑channel‑api‑key>"

Trade‑Offs and Limitations

• Read‑Heavy Design – The Store API is built for reads. Heavy write traffic (e.g., rapid cart updates) may need a dedicated caching layer or rate limiting.
• Over‑Fetching Associations – Including many associations in the Criteria can trigger complex joins and slow down queries. Keep associations minimal.
• Version Changes – API endpoints and payload shapes can change between major releases. Always review the changelog when upgrading.

Actionable Takeaways

1. Start every frontend session with the handshake to acquire a sw-context-token.
2. Use the Criteria object to limit fields and avoid unnecessary associations.
3. Implement client‑side caching for cart operations if you expect high write traffic.
4. Monitor API response times and DB query counts; adjust Criteria or add pagination as needed.
5. Keep an eye on Shopware release notes for API changes that may affect your integration.

By following these patterns, you can build a lightweight, high‑performance headless storefront on top of Shopware 6 that remains maintainable as your product catalog grows.