Shopware API: Schnittstellen im Überblick

Was ist die Shopware API?

Die Shopware API ist die HTTP-basierte Programmierschnittstelle, über die externe Systeme mit deinem Shopware-Shop kommunizieren. Sie ermöglicht das Lesen, Erstellen, Ändern und Löschen von Produkten, Bestellungen, Kunden und nahezu allen anderen Shop-Daten, automatisiert und in Echtzeit.

Shopware 6 verfolgt konsequent einen API-First-Ansatz. Das bedeutet: Jede Funktion, die im Admin-Panel verfügbar ist, steht auch über die API zur Verfügung. Das war bei Shopware 5 anders. Dort existierte eine REST-API mit begrenztem Funktionsumfang, die nachträglich ergänzt wurde. In Shopware 6 wurde die API von Beginn an als primäre Schnittstelle konzipiert.

Wann brauchst du die API überhaupt? Vier Szenarien machen sie zur Pflicht: Erstens, wenn dein ERP Bestände und Bestellungen automatisch synchronisieren soll. Zweitens, wenn du einen Headless-Frontend-Stack einsetzt. Drittens, wenn regelmäßig mehr als 50 Produkte gleichzeitig aktualisiert werden. Und viertens, wenn du externe Services wie KI-Beratung, Chatfunktionen oder Marktplatz-Middleware anbinden willst.

Technisch basiert die Shopware 6 API auf Symfony 7 (seit Version 6.7, Juni 2025) mit PHP 8.2+. Die API folgt der OpenAPI-Spezifikation, was automatische Client-Generierung in TypeScript, Python, PHP oder Go ermöglicht. Laut Shopware verarbeitet Version 6.7 mehr als doppelt so viele Bestellungen pro Sekunde wie die Vorgängerversion. Das spiegelt sich direkt in der API-Performance wider.

Laut EHI Retail Institute nutzen 115 der umsatzstärksten 1.000 B2C-Onlineshops in Deutschland Shopware, Marktführer zum vierten Mal in Folge (Stand 2025). Wer mit Shopware arbeitet, kommt an der API nicht vorbei: ob ERP-Anbindung, Marktplatz-Integration oder Shopware Hosting mit automatisierten Deployments.

Die drei Shopware APIs im Vergleich

Shopware 6 bietet drei spezialisierte APIs: die Admin API für Backend-Verwaltung aller Shop-Daten, die Store API für kundenorientierte Frontend-Interaktionen und die Sync API für performante Massenoperationen. Welche du brauchst, hängt vom Anwendungsfall ab.

Die Admin API ist das mächtigste Werkzeug. Sie gibt dir CRUD-Zugriff auf jede Entity im System: Produkte, Bestellungen, Kunden, Medien, Regeln, Flows. Authentifizierung läuft über OAuth 2.0 mit Client Credentials. Ein Shopware Entwickler nutzt sie typischerweise für Backend-Integrationen, Custom-Dashboards oder Datenmigrationen.

Die Store API dagegen ist öffentlich zugänglich, geschützt nur durch einen sw-access-key. Sie bedient den Sales Channel: Produktsuche, Warenkörbe, Checkout, Kundenkonto. Wenn du eine Shopware Headless-Lösung baust oder eine Mobile App anbinden willst, ist die Store API dein Einstiegspunkt. Shopware Frontends nutzt sie als primäre Datenschicht.

Die Sync API ist ein Add-on zur Admin API. Sie existiert für einen einzigen Zweck: Massenoperationen. Statt 500 einzelne POST-Requests zu senden, packst du alles in einen einzigen Sync-Request an `/api/_action/sync`. Im Unterschied zur Admin API arbeitet die Sync API transaktional. Wenn ein Entity im Batch fehlschlägt, wird der gesamte Batch zurückgerollt. Bei Shopware Cloud gelten zusätzliche Rate Limits.

Authentifizierung und Setup

Die Shopware 6 Admin API nutzt OAuth 2.0 mit Client Credentials Grant. Du erstellst eine Integration im Backend, erhältst Client-ID und Secret, und tauschst diese gegen ein Bearer-Token. Die Store API verwendet stattdessen einen sw-access-key, der im Sales Channel generiert wird.

Admin API: OAuth 2.0 einrichten

Gehe im Shopware-Admin zu Einstellungen > System > Integrationen und erstelle eine neue Integration. Du erhältst eine Client-ID und ein Client-Secret. Damit holst du dir ein Access Token:

curl -X POST "https://dein-shop.de/api/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "DEINE_CLIENT_ID",
    "client_secret": "DEIN_CLIENT_SECRET"
  }'

Die Response enthält ein `access_token` mit einer Gültigkeit von 600 Sekunden (10 Minuten). Nach Ablauf musst du ein neues Token anfordern. Bei der Resource Owner Password Grant-Variante erhältst du zusätzlich ein Refresh Token. Für Integrationen ohne Benutzerkontext ist der Client Credentials Grant der empfohlene Weg, laut offizieller Shopware API-Dokumentation.

Store API: Access Key und Context Token

Die Store API braucht keinen OAuth-Flow. Du sendest den `sw-access-key` als Header mit jedem Request. Für kundenspezifische Aktionen (Warenkorb, Bestellungen) benötigst du zusätzlich ein Context Token, das du über `/store-api/context` erhältst.

curl -X GET "https://dein-shop.de/store-api/product" \
  -H "sw-access-key: DEIN_ACCESS_KEY" \
  -H "Content-Type: application/json"

Der Unterschied zum Admin API OAuth-Flow: Der sw-access-key ist kein Geheimnis. Er identifiziert den Sales Channel, nicht den Benutzer. Kundenspezifische Daten werden über das Context Token geschützt. Diese Architektur orientiert sich an der OpenAPI-Spezifikation und erlaubt Shopware Hosting-Setups mit getrennt skalierbaren API-Layern. Ob du dich für Shopware Managed Hosting oder Shopware Cloud Hosting entscheidest, beeinflusst, wie du API-Zugriffe absicherst und skalierst.

Erste Schritte mit der Shopware API

Der schnellste Einstieg: Erstelle eine Integration im Shopware-Admin unter Einstellungen > System > Integrationen, kopiere Client-ID und Secret, und sende deinen ersten GET-Request an /api/product. In unter 5 Minuten hast du deine erste API-Antwort.

Erster API-Call mit cURL

Nach der Authentifizierung (siehe oben) kannst du sofort Produktdaten abfragen. Der folgende Request holt die ersten 25 Produkte:

curl -X GET "https://dein-shop.de/api/product?limit=25" \
  -H "Authorization: Bearer DEIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Die Standard-Pagination liefert 25 Entities pro Seite, maximal konfigurierbar auf 500. Für größere Datenmengen nutze den `page`-Parameter oder die Search API mit Filtern. Wer das lieber grafisch testet: Die Postman-Collection für Shopware 6 auf Postman enthält vorkonfigurierte Requests für alle Endpoints.

Wir empfehlen, die lokale Entwicklungsumgebung zuerst per Shopware Docker aufzusetzen. So kannst du API-Calls testen, ohne den Produktivshop zu belasten. Eine frische Shopware Installation mit Demo-Daten reicht für den Einstieg.

Includes und Associations

Shopware lädt standardmäßig nicht alle verknüpften Daten. Wenn du bei einem Produktaufruf auch Hersteller und Medien brauchst, nutze den `associations`-Parameter:

{
  "associations": {
    "manufacturer": {},
    "media": {}
  },
  "includes": {
    "product": ["id", "name", "productNumber", "price"],
    "product_manufacturer": ["name"]
  }
}

Der `includes`-Parameter reduziert die Response auf die Felder, die du tatsächlich brauchst. Bei einem Katalog mit 10.000+ Produkten spart das erheblich Bandbreite und Verarbeitungszeit.

Die Search API verdient besondere Aufmerksamkeit. Statt einfacher GET-Requests mit URL-Parametern nutzt du POST-Requests an `/api/search/{entity}` mit einem JSON-Body. Das erlaubt komplexe Filter, Sortierungen, Aggregationen und Volltextsuche. Für Produktabfragen mit mehr als 2-3 Filterbedingungen ist die Search API der performantere Weg.

Praxis: Häufige API-Operationen

Die am häufigsten genutzten API-Operationen sind Produktimport via Admin API, Bestellabruf für ERP-Synchronisation, Lagerbestandsupdate in Echtzeit und kundenspezifische Warenkorb-Operationen über die Store API. Hier die konkreten Beispiele.

Produkt erstellen (Admin API)

curl -X POST "https://dein-shop.de/api/product" \
  -H "Authorization: Bearer DEIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Rasendünger Premium 10kg",
    "productNumber": "RD-PREM-10",
    "stock": 150,
    "taxId": "STEUER_ID",
    "price": [{
      "currencyId": "WAEHRUNGS_ID",
      "gross": 29.99,
      "net": 25.20,
      "linked": true
    }]
  }'

Massenimport via Sync API

Einzelne POST-Requests funktionieren bei 10 Produkten. Bei 5.000 wird das zum Problem. Die Sync API löst das:

curl -X POST "https://dein-shop.de/api/_action/sync" \
  -H "Authorization: Bearer DEIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "single-operation: true" \
  -H "indexing-behavior: use-queue-indexing" \
  -d '[{
    "action": "upsert",
    "entity": "product",
    "payload": [
      {"productNumber": "RD-001", "name": "Produkt 1", "stock": 100, ...},
      {"productNumber": "RD-002", "name": "Produkt 2", "stock": 50, ...}
    ]
  }]'

Entscheidend ist der Header `indexing-behavior: use-queue-indexing`. Ohne ihn wartet die API auf den Abschluss aller Indexierungsprozesse. Laut Cloudflight verlängert das die Antwortzeit von 1-2 Sekunden auf 30-60 Sekunden pro Batch. Ein Shopware Programmierer mit Erfahrung in Massenimporten kennt diesen Header.

Bestellungen abrufen (Admin API)

curl -X POST "https://dein-shop.de/api/search/order" \
  -H "Authorization: Bearer DEIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": [{
      "type": "range",
      "field": "orderDateTime",
      "parameters": {
        "gte": "2026-05-01T00:00:00Z"
      }
    }],
    "associations": {
      "lineItems": {},
      "deliveries": {}
    }
  }'

Die Search API unterstützt komplexe Filter, Sortierung und Aggregationen. Für die ERP-Synchronisation holst du typischerweise nur Bestellungen seit dem letzten Sync-Zeitpunkt. Das reduziert die Datenmenge und hält die Antwortzeiten unter 500ms.

Lagerbestand in Echtzeit aktualisieren

Bestandsupdates über die API sind der zweitwichtigste Integrationsfall nach dem Produktimport. Ein PATCH-Request auf `/api/product/{id}` mit dem `stock`-Feld genügt. Für mehrere Produkte gleichzeitig: Sync API mit upsert-Action. Die Lagerbestandsänderung greift sofort im Frontend, keine Cache-Invalidierung nötig.

curl -X PATCH "https://dein-shop.de/api/product/PRODUKT_ID" \
  -H "Authorization: Bearer DEIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"stock": 42}'

Warenkorb-Operationen (Store API)

# Produkt zum Warenkorb hinzufügen
curl -X POST "https://dein-shop.de/store-api/checkout/cart/line-item" \
  -H "sw-access-key: DEIN_ACCESS_KEY" \
  -H "sw-context-token: DEIN_CONTEXT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{
      "type": "product",
      "referencedId": "PRODUKT_ID",
      "quantity": 2
    }]
  }'

Die Store API erlaubt vollständige Warenkorb-Steuerung: Artikel hinzufügen, Mengen ändern, Gutscheine einlösen, Versandart wählen. Ein KI-Mitarbeiter kann darüber den gesamten Checkout begleiten, vom Produktvorschlag bis zur Bestellung. Im Test mit beratungsintensiven Sortimenten (Gartenbedarf, Pflanzenschutz) liegt die API-Antwortzeit für Cart-Operationen bei 150-250ms.

Integrationsszenarien

Die drei wichtigsten Integrationsszenarien für die Shopware API sind ERP-Anbindung, Marktplatz-Integration und KI-gestützte Produktberatung über die Store API. Jedes Szenario nutzt eine andere Kombination der drei APIs.

ERP-Anbindung

Die ERP-Integration ist der häufigste API-Anwendungsfall. Produkte, Bestände und Bestellungen synchronisieren sich automatisch zwischen Shopware und Systemen wie SAP, Microsoft Dynamics oder WeClapp. Typischer Ablauf: Die Sync API importiert Produktdaten aus dem ERP, die Admin API holt neue Bestellungen im 5-Minuten-Takt.

Seit April 2026 bietet Shopware mit Shopware Nexus (noch Beta) eine visuelle Steuerung für solche Prozesse, ohne zusätzliche Middleware. Für komplexere Setups bleibt die direkte API-Integration aber der flexiblere Weg.

In der Praxis sehen wir drei typische Fehler bei ERP-Integrationen. Erstens: Vollständige Produktsynchronisationen statt Delta-Updates. Bei 10.000 Produkten bedeutet das 200+ Sync-API-Calls statt 5-10 für die geänderten Artikel. Zweitens: Bestellungen werden per Polling alle 60 Sekunden abgefragt, obwohl Shopware Webhooks anbietet. Drittens: Fehlende Retry-Logik. Wenn das ERP kurz nicht erreichbar ist, gehen Bestellungen verloren. Webhooks mit Dead-Letter-Queue lösen das.

Marktplatz-Anbindung

Amazon, eBay, Otto, Kaufland: Marktplätze erwarten regelmäßige Bestandsupdates und Bestellimporte. Die Admin API liefert beides. Typischer Flow: Ein Middleware-Service (z.B. ChannelEngine oder Tradebyte) ruft Bestandsänderungen über die Admin API ab und spielt Marktplatz-Bestellungen über die Sync API ein. Das funktioniert, aber die Fehlerrate steigt mit der Anzahl der Marktplätze. Ich halte eine zentrale Bestandsführung im ERP mit API-Push an Shopware für den stabileren Ansatz.

KI-Produktberatung via Store API

Die Store API eignet sich als Datenquelle für KI-gestützte Produktberatung. Der KI-Mitarbeiter greift über die Store API auf den Produktkatalog zu, filtert nach Kundenanforderungen und liefert personalisierte Empfehlungen in Echtzeit.

Ein konkretes Beispiel: Rasendoktor, Onlineshop für Rasenpflege, setzt einen KI-Mitarbeiter über die Shopware-Schnittstelle ein. Das Ergebnis: 16x Return on Investment und 100% Automatisierungsquote im Kundenservice, dokumentiert in der Rasendoktor Erfolgsgeschichte. Die Store API liefert dabei Produktdaten, Verfügbarkeiten und Preise für die KI-Produktberatung in unter 500ms.

Shopware treibt diese Entwicklung aktiv voran. Mit dem neuen Agentic Commerce Sales Channel (Stand Q2 2026) können Händler ihre Produkte über einen standardisierten JSONL-Feed auf KI-Plattformen wie ChatGPT bereitstellen. Die API wird zum direkten Vertriebskanal. Wer einen Shopware Relaunch plant, sollte dieses Szenario mitdenken.

Best Practices und Fehlerbehandlung

Die drei wichtigsten Best Practices: Nutze die Sync API statt Einzel-Requests für Massenoperationen, implementiere exponentielles Backoff bei Rate-Limiting und verwende Includes gezielt, um die Response-Größe zu minimieren.

1. Sync API für Bulk: Ab 10+ gleichartigen Operationen lohnt sich der Wechsel zur Sync API. Setze den `indexing-behavior: use-queue-indexing` Header.
2. Includes einschränken: Lade nur die Felder, die du brauchst. Ein Product-Request ohne Includes liefert ~3 KB JSON. Mit allen Associations steigt das auf 50+ KB.
3. Exponentielles Backoff: Bei einem 429-Status (Rate Limit) warte 1s, dann 2s, dann 4s. Nicht sofort retrien.
4. Fehler loggen, nicht verschlucken: Shopware liefert strukturierte Fehlermeldungen im `errors`-Array. Logge den vollständigen Error-Body, nicht nur den HTTP-Status.

Shopware empfiehlt maximal 10 parallele API-Connections pro Integration. Mehr führt auf Standard-Hosting zu Timeouts. Wer höhere Durchsätze braucht, sollte die Shopware Server Anforderungen prüfen, den passenden Anbieter im Shopware Hosting Vergleich auswählen und dedizierte Worker für die API einrichten.

Ehrlich gesagt: Die Shopware API-Dokumentation hat Lücken. Die Stoplight-Referenz listet Endpoints und Parameter, aber praxisnahe Beispiele für komplexe Szenarien fehlen oft. Wer eine Custom-Field-Struktur über die API anlegen will oder verschachtelte Associations mit Filtern kombiniert, landet schnell im Quellcode oder in Community-Foren. Das ist nicht schlimm, aber es ist eben auch nicht das Niveau der Stripe- oder Shopify-Dokumentation.

Meine Empfehlung nach dutzenden API-Integrationen: Starte mit der Admin API und Postman, nicht mit einem SDK. SDKs abstrahieren die HTTP-Schicht, und genau die musst du verstehen, wenn etwas schiefgeht. Erst wenn deine Integration stabil läuft, lohnt sich der Wechsel auf ein typisiertes SDK. Haette ich nicht erwartet, aber die meisten Debugging-Sessions enden beim HTTP-Layer, nicht im Anwendungscode.

Zur Shopware Performance Optimierung gehört auch die API-Ebene. Shopware 6.7 auf Symfony 7 mit PHP 8.2+ liefert laut Shopware mehr als doppelt so viele Bestellungen pro Sekunde wie die Vorgängerversion. Halte dein System aktuell, das betrifft nicht nur Security, sondern direkt die API-Performance. Ein regelmäßiges Shopware Update ist Pflicht. Und bei kritischen Daten: Shopware Backup vor jedem größeren Import.

Versionierung und API-Stabilität

Shopware versioniert seine API nicht über URL-Pfade wie `/api/v1/` oder `/api/v2/`. Stattdessen gilt: Die Admin API und Store API sind stabil innerhalb einer Major-Version. Breaking Changes kommen mit Major-Releases und werden im Changelog dokumentiert. Seit Shopware 6.5 hat sich die API-Struktur nicht grundlegend geändert. Das ist eine bewusste Entscheidung: weniger Versionschaos, stabilere Integrationen.

Was sich ändert, sind Features. Die Agentic Commerce API (Q1 2026), Shopware Nexus (April 2026, Beta) und neue Flow-Builder-Actions erweitern die API kontinuierlich. Deine bestehende Integration bricht dadurch nicht. Aber du verpasst Funktionen, wenn du die Shopware Release Notes nicht verfolgst.

Monitoring gehört zur API-Integration dazu. Logge mindestens: Antwortzeiten pro Endpoint, HTTP-Statuscodes (insbesondere 429 und 5xx), und die Anzahl der API-Calls pro Stunde. Bei Shopware SaaS-Hosting erhältst du keine Server-Logs, nur die API-Responses. Auf Self-Hosted kannst du Shopware-interne Logs unter `var/log/` auswerten. Wer mit mehr als 3 externen Systemen integriert, sollte ein zentrales API-Gateway mit Request-Logging einsetzen.

Häufig gestellte Fragen zur Shopware API