Shopware 6 API: A Complete Beginner's Guide

When building headless commerce architectures, custom storefronts, or enterprise integrations, the Shopware 6 API serves as the central nervous system of your platform. Whether you are synchronizing inventory across multiple channels, pushing fulfilled orders to a third-party logistics provider, or rendering a fully custom frontend, mastering the API layer is non-negotiable. With Shopware 6.7 introducing stricter security defaults and refined endpoint routing, now is the ideal time to understand how to interact with the platform programmatically. This guide walks you through everything you need to know to start building confidently and securely.

What Is the Shopware 6 API?#

The Shopware 6 API is a unified, standards-compliant interface that exposes core platform entities such as products, customers, orders, categories, promotions, and stock levels. Unlike theme-driven development where business logic is tightly coupled with Twig templates, the API decouples data from presentation. This architectural shift enables true headless commerce, where your frontend can be built with React, Vue, Next.js, or native mobile frameworks while Shopware handles product management, checkout workflows, and order processing in the background. Shopware 6.7 continues to optimize API performance, expand GraphQL coverage, and enforce modern authentication practices without disrupting established integration patterns.

Authentication in Shopware 6.7+#

Authentication is the first hurdle for any new integration. In previous versions, developers relied on access_token endpoints that automatically generated session-based keys. Shopware 6.7 deprecates this flow for public-facing services and standardizes around permanent API tokens. Navigate to Administration > Settings > Technical Settings > API Tokens to generate a key. You must select the appropriate scope (store_api or administration_api) and assign granular permissions like read:product or write:order.

Shopware 6.7 requires HTTP Basic Authentication combined with a dedicated header. Encode your store name as the username and your generated access key as the password, then transmit them using Base64 encoding. Additionally, explicitly include the sw-access-key header in every request to improve routing accuracy, audit logging, and rate-limit tracking.

Authorization: Basic c3RvcmVuYW1lOnlvdXJfYWNjZXNzX2tleQ==
sw-access-key: your_access_key_here
Content-Type: application/json
Accept-Language: en-US

API Architecture & Endpoint Routing#

Understanding endpoint routing prevents common 404 and permission errors. Shopware 6.7 clearly separates contexts:

• Administration API: Rooted at /api/. Used by backend services, plugins, and internal tools. Requires admin-scoped tokens.
• Storefront API: Rooted at /api/store-api/. Exposes customer-facing endpoints like cart, checkout, and product browsing. Requires store_api tokens.

Never mix token types across contexts. A storefront token will be rejected on admin routes, and vice versa. Shopware 6.7 also enforces strict MIME type validation; always set Content-Type: application/json when sending payloads, and accept application/json in responses unless downloading files.

Filtering, Sorting & Pagination#

Both REST and GraphQL rely on standardized query parameters, but the syntax differs slightly between contexts. The REST filter structure is explicit and array-based. Each filter object requires a type, field, and value. Supported types include equals, contains, range, ids, prefix, and nested.

Sorting uses a parallel structure where you define the field and direction (ASC or DESC). Pagination is handled via page (1-indexed) and limit (maximum 250 per request). Always monitor the meta.pagination object in responses to implement infinite scrolling or cursor-based navigation efficiently.

Code Examples: Making Your First Request#

Below is a production-ready example using modern JavaScript to fetch active products via the Storefront API:

const storeName = "default";
const accessKey = "your_store_access_key";
const authHeader = Buffer.from(`${storeName}:${accessKey}`).toString("base64");

const response = await fetch("https://your-domain.com/api/store-api/product", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Basic ${authHeader}`,
    "sw-access-key": accessKey,
    "Accept-Language": "en-US"
  },
  body: JSON.stringify({
    filter: [
      { type: "equals", field: "active", value: true },
      { type: "range", field: "price.unitPrice", value: { gt: 10, lt: 50 } }
    ],
    sort: [{ field: "createdAt", order: "DESC" }],
    page: 1,
    limit: 20
  })
});

if (!response.ok) throw new Error(`API Error: ${response.status}`);
const data = await response.json();
console.log(`Retrieved ${data.meta.pagination.total} products.`);

For complex frontend requirements, GraphQL reduces payload bloat. Send queries to /api/graphql using identical authentication headers:

query {
  products(
    filter: { active: { equals: true }, price: { range: { gt: 10 } } }
    limit: 10
    sort: [{ field: "createdAt", order: DESC }]
  ) {
    total
    entities {
      id
      name
      translated: description
      price { currencyId isoCode }
      cover { mediaUrl }
    }
  }
}

Webhooks & Event-Driven Sync#

API polling is rarely necessary in Shopware 6.7. The platform includes a native webhook system that pushes events to registered URLs when specific actions occur. Navigate to Settings > System > Webhooks and register endpoints for events like order.placed, product.deleted, or stock_updated. Webhooks are signed with an HMAC-SHA256 hash, allowing you to verify authenticity and prevent spoofed requests. This event-driven approach reduces latency, lowers server load, and ensures real-time synchronization across distributed systems.

Best Practices for Reliable Integrations#

Never hardcode credentials. Use environment variables or a secret manager like AWS Secrets Manager or HashiCorp Vault. Always implement exponential backoff and retry logic for transient 5xx errors and 429 rate limits. Monitor response headers for cache directives, especially on product and category routes. Consider generating typed API clients using Shopware's OpenAPI spec to eliminate manual serialization bugs. Avoid client-side administration tokens; they expose write permissions and violate security best practices. Finally, test integrations in a fresh 6.7 installation with sample data before deploying to production environments.

Conclusion#

The Shopware 6 API is an enterprise-grade interface that powers everything from lightweight plugins to global headless storefronts. With version 6.7, the platform has tightened authentication, clarified endpoint routing, and expanded GraphQL support while maintaining backward compatibility for established workflows. By mastering access key management, understanding REST versus GraphQL trade-offs, leveraging webhooks for real-time sync, and adhering to pagination and filtering standards, you can build secure, scalable integrations that grow with your business. Always consult the official API documentation for entity-specific details, but use this guide as your foundational blueprint. Headless commerce with Shopware 6 has never been more accessible, predictable, or powerful.