API Basics

Die REST API bietet Ihnen die Möglichkeit, automatisiert mit dem Shop-System zu interagieren – etwa um Produktdaten zu verwalten, Bestellungen auszulesen oder eigene Integrationen anzubinden. Dieses Dokument beschreibt die grundlegenden Voraussetzungen und technischen Konzepte, um mit der API arbeiten zu können.

Basis-URL

Alle REST-API-Endpunkte sind unter folgendem Pfad erreichbar:

https://<ihr-shop>.de/admin/api/v1/

Diese URL ist die Basis für sämtliche Anfragen, z.B.

GET https://<ihr-shop>.de/admin/api/v1/products

POST https://<ihr-shop>.de/admin/api/v1/login

Zugang & Berechtigungen

Für den Zugriff auf die REST API ist ein Benutzerkonto erforderlich, das im Admin Interface Ihres Shops verwaltet wird. Das Admin Interface ist in sogenannte Services unterteilt (z. B. Produkte, Kategorien, Sitemaps, SEO-URLs, Datenfeeds, Statistiken etc.). Für jeden Service können im Admin-Bereich Berechtigungen vergeben werden – z. B. Lesen, Bearbeiten, Erstellen, Löschen oder Publizieren. Diese Rechte gelten auch für die REST API und bestimmen, auf welche Endpunkte Sie zugreifen und welche HTTP-Methoden (GET, POST, PUT, DELETE) Sie verwenden dürfen. Ein Benutzer mit z. B. nur Leserechten im Service „Produkte“ kann Produkte per API nur abrufen (GET), aber nicht bearbeiten (PUT/POST/DELETE). Ihre zugewiesenen Rechte können Sie im Admin Interface unter folgendem Pfad einsehen:

https://<ihr-shop>.de/admin/profile

Die Vergabe von Rechten erfolgt über den Service „Benutzer“:

https://<ihr-shop>.de/admin/administration/users

Einige Endpunkte arbeiten mit subshopspezifischen Daten. In diesen Fällen muss der betreffende Subshop explizit angegeben werden. Das betrifft unter anderem Methoden für Produkte, Kategorien, Lagerbestände, SEO-Daten und ähnliche kontextabhängige Inhalte. Der Subshop kann auf zwei gleichwertigen Wegen übergeben werden - als URL-Parameter oder als HTTP-Header:

https://<ihr-shop>.de/admin/api/v1/categories?subshopId=deutsch

X-SubshopId: deutsch

Die Auswertung erfolgt in dieser Reihenfolge:

URL-Parameter subshopId - hat Vorrang, sobald er gesetzt ist.
Header X-SubshopId - greift, wenn der URL-Parameter fehlt oder leer ist.
Fallback: der erste im Shop konfigurierte Subshop.

Der Header ist praktisch, wenn Ihr Integrationsclient durchgängig mit demselben Subshop arbeitet: Dann setzen Sie ihn einmal global, statt ihn an jede URL zu hängen.

Verlassen Sie sich nicht auf den Fallback aus Punkt 3, da Sie sonst im ersten konfigurierten Subshop arbeiten. Das ist selten der gewünschte Subshop und er kann sich ändern, wenn die Subshop-Konfiguration angepasst wird. Geben Sie deshalb den Subshop bei subshopbezogenen Endpunkten immer explizit an.

Endpunkte ohne Subshop-Bezug (z. B. Login oder Benutzerverwaltung) werten weder den Parameter noch den Header aus. Falls Ihnen der Zugriff auf bestimmte REST-Endpunkte verweigert wird, fehlen Ihnen möglicherweise die erforderlichen Rechte. In diesem Fall wenden Sie sich an den zuständigen Shop-Administrator.

Authentifizierung

Für den Zugriff auf geschützte REST-API-Endpunkte ist eine Anmeldung erforderlich. Die Authentifizierung erfolgt entweder über Benutzername/Passwort oder per API-Schlüssel. Erfolgreich authentifizierte Anfragen erhalten ein Access Token, mit dem weitere Endpunkte angesprochen werden können. Zusätzlich wird ein Refresh Token bereitgestellt. Der Login erfolgt über folgenden Endpunkt:

POST https://<ihr-shop>.de/admin/api/v1/login

Das erhaltene Access Token muss bei allen folgenden API-Aufrufen im HTTP-Header mitgesendet werden. Der Header muss dazu das Feld X-Authorization enthalten. Der Wert besteht aus dem Wort Bearer, gefolgt vom Token:

"X-Authorization": "Bearer <Access-Token>"

Details zur Authentifizierung (Request-Varianten, Token-Verwendung, Fehlercodes etc.) finden Sie in der separaten Dokumentation: API-Referenz Authentifizierung

Filter, Sortierung & Paginierung

Viele REST-Endpunkte liefern Listen von Daten – etwa Produkte, Bestellungen oder Kategorien. Um mit diesen Daten effizient zu arbeiten, stellt die API verschiedene Parameter zur Verfügung, mit denen sich die Ergebnisse eingrenzen, sortieren und seitenweise abrufen lassen. Diese Mechanismen sind besonders bei großen Datenmengen wichtig, um performante und gezielte Abfragen zu ermöglichen. Ein API-Aufruf kann dabei verschiedene Parameter enthalten. Ein typischer GET-Request könnte wie folgt aussehen:

https://<ihr-shop>.de/admin/api/v1/<API-Referenz>?size=100&sort=field1:asc&filter_eq[field2]=value&pageToken=MTAw

Die Antwort der API ist standardisiert aufgebaut und enthält neben den angeforderten Datensätzen weitere Meta-Informationen wie den nextPageToken, den Gesamtzähler (totalCount) sowie das Flag endReached, das angibt, ob weitere Seiten zur Verfügung stehen:

{
	"endReached": true,
	"items": [...],
	"nextPageToken": "MTAx",
	"totalCount": 123
}

Unterstützte Parameter

Die folgenden URL-Parameter werden zur Steuerung von Ergebnislisten unterstützt. Die Schreibweise ist case-sensitive.

Parameter	Beschreibung
`size`	Anzahl der zurückgegebenen Einträge pro Seite (1 bis maximal 300)
`pageToken`	Optionaler Paginierungsmarker für den Abruf der nächsten Seite
`sort`	Ergebnis-Sortierung nach einem oder mehreren Feldern
`filter_...`	Filterbedingungen zur Einschränkung der Ergebnisse
`subshopId`	Einschränkung auf einen bestimmten Subshop. Bei subshopbezogenen Endpunkten (z. B. Produkte, Kategorien, Lagerbestände, SEO) erforderlich. Alternativ als Header `X-SubshopId` übergebbar – siehe Zugang & Berechtigungen.
`textSearch`	Optionaler Parameter für die Volltextsuche.

Anzahl & Paginierung

Die Anzahl der zurückgegebenen Datensätze pro API-Anfrage kann über den Parameter size gesteuert werden. Der Wert muss eine Ganzzahl zwischen 1 und 300 sein. Wird kein size-Parameter übergeben, verwendet die API standardmäßig einen Wert von 100 Einträgen pro Seite. Ist die angeforderte Datenmenge größer als der definierte size-Wert (bzw. größer als der Standardwert), liefert die API in der Antwort einen nextPageToken, mit dem weitere Seiten geladen werden können. Der Paginierungsmechanismus erlaubt es, große Datenmengen schrittweise abzurufen.

Beispiel

Beispiel für eine manuell gesetzte Seitengröße.

https://<ihr-shop>.de/admin/api/v1/<API-Referenz>?size=50

Fehlercodes

Fehlercode	Typ	Beschreibung
400	`InvalidCharacter`	Ungültige Zeichen im Parameterwert
400	`InvalidValue`	Wert kleiner als 1 oder größer als 300

Der Parameter pageToken ermöglicht den Zugriff auf die Folgeseiten von Ergebnislisten. Der Wert wird von der API automatisch als nextPageToken zurückgegeben und muss base64-url-kodiert übergeben werden. Bei einer fehlerhaften oder ungültigen Codierung erfolgt eine Fehlermeldung.

Beispiel

https://<ihr-shop>.de/admin/api/v1/<API-Referenz>?size=100&pageToken=MTAw

Fehlercodes

Fehlercode	Typ	Beschreibung
400		Token nicht dekodierbar oder negativ bzw. ungültig

Sonderfall: Produkte

Das Laden von Produkten mittels pageToken kann langsam sein, wenn mehr als 10.000 Produkte im Shop existieren. Neben dem pageToken wird bei Produkten auch ein searchAfterToken zurückgegeben. Statt pageToken kann searchAfterToken in der URL angegeben werden, um auch bei vielen Ergebnissen die Produkte effizient laden zu können.

Beispiel

https://<ihr-shop>.de/admin/api/v1/<API-Referenz>?size=300&searchAfterToken=WzAuMCwiMTAwLTQxMjMyLTk3NDFfZGV1dHNjaF8zIl0

Sortierung

Die Sortierung von Ergebnissen erfolgt über den Parameter sort. Er erwartet als Wert einen Feldnamen und eine Sortierrichtung (asc für aufsteigend, desc für absteigend), getrennt durch einen Doppelpunkt. Für die Kombination mehrerer Sortierkriterien ist es erforderlich, mehrere sort-Parameter zu übergeben. Jeder Parameter steht dabei für ein einzelnes Kriterium. Eine kommaseparierte Liste innerhalb eines Parameters wird nicht unterstützt. Falls kein Sortierparameter angegeben ist, wird standardmäßig nach der internen ID sortiert. Eine Ausnahme ist die Produktliste mit dem Filter inCategory: Dort gilt ohne eigenen sort-Parameter die im Shop gepflegte Kategoriereihenfolge – siehe Produkte – Reihenfolge bei inCategory.

Syntax

sort=<Feldname>:asc|desc

Sortierung nach Preis aufsteigend

https://<ihr-shop>.de/admin/api/v1/<API-Referenz>?sort=price:asc

Ein weiteres Beispiel für eine Sortierung nach dem Namen (aufsteigend) und anschließend nach dem Preis (absteigend):

https://<ihr-shop>.de/admin/api/v1/<API-Referenz>?sort=name:asc&sort=price:desc

Fehlercodes

Fehlercode	Typ	Beschreibung
400	`SyntaxError`	Fehlender oder mehrfach vorhandener Doppelpunkt.
400	`InvalidValue`	Ungültige Sortierrichtung (nicht `asc` oder `desc`)
400	`UnknownField`	Das angegebene Sortierfeld ist unbekannt

Filter

Filter ermöglichen eine gezielte Einschränkung von Ergebnislisten. Jeder Filter folgt dem Muster.

Syntax

filter_<Operation>[<Feldname>]=<Wert>

Mehrere Filter für unterschiedliche Felder werden logisch mit UND verknüpft. Wenn mehrere Filter für dasselbe Feld angegeben werden, interpretiert die API diese als ODER-Verknüpfung.

?filter_eq[status]=open
&filter_gte[createdAt]=2024-12-01T00:00:00Z
&filter_lte[createdAt]=2025-01-05T23:59:59Z

Unterstützte Filteroperationen

Operation	Bedeutung
`eq`	Gleichheit (`=`)
`neq`	Ungleichheit (`!=`)
`lt`	Kleiner als (`<`)
`lte`	Kleiner oder gleich (`≤`)
`gt`	Größer als (`>`)
`gte`	Größer oder gleich (`≥`)
`beginsWith`	Beginnt mit
`endsWith`	Endet mit
`contains`	Enthält
`notContains`	Enthält nicht
`within`	Liste enthält den angegebenen Wert (nur Felder vom Typ Liste)
`notWithin`	Liste enthält den angegebenen Wert nicht (nur Felder vom Typ Liste)
`empty`	Feld ist leer bzw. nicht gesetzt (nur Felder vom Typ Liste oder Map)

Die Operationen within, notWithin und empty stehen nur bei der Produktliste zur Verfügung (GET products und die davon abgeleiteten Endpunkte), weil nur dort Felder vom Typ Liste und Map vorkommen. Bei allen anderen Listen-Endpunkten führen sie zum Fehler UnknownOperation.

Erlaubte Operationen je Feldtyp

Nicht auf jedem Feld ist eine Filteroperation erlaubt. Welche Operationen gültig sind, hängt vom Datentyp des Feldes ab. Die Aussage “Alle Produktdatenfelder sind filterbar” bedeutet also nicht, dass jedes Feld mit jeder Operation kombinierbar ist. Eine unzulässige Kombination wird nicht ignoriert, sondern mit dem Statuscode 400 Bad Request und dem Typ illegalOperation abgewiesen.

Feldtyp	Erlaubte Operationen
Text (String)	`eq`, `neq`, `contains`, `notContains`, `beginsWith`, `endsWith`
Aufzählung (Enum), z. B. `active`	`eq`, `neq`
Wahrheitswert (Bool)	`eq`, `neq`
Zahl (Integer, Float), Preis, Datum/Zeit	`eq`, `neq`, `lt`, `lte`, `gt`, `gte`
Liste	`within`, `notWithin`, `empty`
Map	`empty`
Bild, Video	keine – diese Felder sind nicht filterbar

Beispiele:

# gültig: Text-Feld mit contains
?filter_contains[name]=Polo

# gültig: Enum-Feld mit eq
?filter_eq[active]=always

# ungültig -> 400 "illegalOperation": Enum-Feld mit contains
?filter_contains[active]=alw

Benutzerdefinierte Felder werden mit dem Präfix custom. adressiert:

?filter_eq[custom.brand]=Barbour

Es gibt keine Operationen like oder in. Verwenden Sie stattdessen contains (Teilstring-Suche) bzw. mehrere Filter auf dasselbe Feld, die die API als ODER verknüpft:

?filter_eq[taxRateId]=1&filter_eq[taxRateId]=7

Fehlercodes

Fehlercode	Typ	Beschreibung
400	`UnknownOperation`	Die Filteroperation ist nicht bekannt
400	`UnknownField`	Das angegebene Feld ist ungültig
400	`illegalOperation`	Die Operation ist für den Datentyp dieses Feldes nicht erlaubt (siehe Tabelle „Erlaubte Operationen je Feldtyp”)
400	`invalidCharacters`	Der Filterwert enthält ungültige Zeichen

Volltextsuche

Die meisten Endpunkte unterstützen eine Volltextsuche über den optionalen URL-Parameter textSearch. Damit lassen sich Ergebnisse nach einem Suchbegriff filtern, ohne explizite Filterfelder angeben zu müssen. Der Parameter kann mehrfach angegeben werden – mehrere Werte werden mit OR verknüpft. Die Suche ist schreibungsabhängig.

Syntax

textSearch=<Suchbegriff>&textSearch=<Suchbegriff>

Beispiel (einzelner Suchbegriff)

https://<ihr-shop>.de/admin/api/v1/orders?textSearch=Mustermann

Beispiel (mehrere Suchbegriffe)

https://<ihr-shop>.de/admin/api/v1/orders?textSearch=Mustermann&textSearch=Berlin

Bulk-Endpunkte

Für Massenoperationen stellt die API Bulk-Endpunkte bereit. Sie übertragen viele Datensätze in einem Request und sind deutlich effizienter als Einzelaufrufe.

Gemeinsames Limit: 1000 Einträge pro Request

Alle Bulk-Endpunkte teilen sich ein Limit von 1.000 Einträgen pro Anfrage. Es handelt sich dabei nicht um ein Limit einzelner Endpunkte, sondern um eine gemeinsame Obergrenze, die an jedem der unten aufgeführten Endpunkte identisch ist.

Wird das Limit überschritten, antwortet die API mit 400 Bad Request. In diesem Fall werden keine Einträge verarbeitet und der Request wird komplett abgewiesen. Zerlegen Sie daher größere Datenmengen client-seitig in Blöcke von maximal 1.000 Einträgen.

Endpunkt	Methode	Referenz
`bulk/products`	POST	Produkte
`bulk/products/variants`	POST	Produkte
`bulk/products/inventory`	POST	Produkte
`bulk/customerAccounts`	POST	Kundendaten
`bulk/customerAccounts/addresses`	POST	Kundendaten
`vouchers/bulk`	POST, DELETE	Gutscheine

Alle schreibenden Bulk-Endpunkte arbeiten mit POST, auch wenn sie bestehende Datensätze aktualisieren. Ein PUT auf einen Bulk-Pfad wird nicht beantwortet.

Support

Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: Zum Kundenportal Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.

Schnittstellen

Admin Interface API

Storefront API

Weitere

Basis-URL

Zugang & Berechtigungen

Authentifizierung

Filter, Sortierung & Paginierung

Unterstützte Parameter

Anzahl & Paginierung

Beispiel

Fehlercodes

Beispiel

Fehlercodes

Sonderfall: Produkte

Beispiel

Sortierung

Syntax

Sortierung nach Preis aufsteigend

Fehlercodes

Filter

Syntax

Unterstützte Filteroperationen

Erlaubte Operationen je Feldtyp

Fehlercodes

Volltextsuche

Syntax

Beispiel (einzelner Suchbegriff)

Beispiel (mehrere Suchbegriffe)

Bulk-Endpunkte

Gemeinsames Limit: 1000 Einträge pro Request

Support

​Basis-URL

​Zugang & Berechtigungen

​Authentifizierung

​Filter, Sortierung & Paginierung

​Unterstützte Parameter

​Anzahl & Paginierung

​Beispiel

​Fehlercodes

​Beispiel

​Fehlercodes

​Sonderfall: Produkte

​Beispiel

​Sortierung

​Syntax

​Sortierung nach Preis aufsteigend

​Fehlercodes

​Filter

​Syntax

​Unterstützte Filteroperationen

​Erlaubte Operationen je Feldtyp

​Fehlercodes

​Volltextsuche

​Syntax

​Beispiel (einzelner Suchbegriff)

​Beispiel (mehrere Suchbegriffe)

​Bulk-Endpunkte

​Gemeinsames Limit: 1000 Einträge pro Request

​Support

Basis-URL

Zugang & Berechtigungen

Authentifizierung

Filter, Sortierung & Paginierung

Unterstützte Parameter

Anzahl & Paginierung

Beispiel

Fehlercodes

Beispiel

Fehlercodes

Sonderfall: Produkte

Beispiel

Sortierung

Syntax

Sortierung nach Preis aufsteigend

Fehlercodes

Filter

Syntax

Unterstützte Filteroperationen

Erlaubte Operationen je Feldtyp

Fehlercodes

Volltextsuche

Syntax

Beispiel (einzelner Suchbegriff)

Beispiel (mehrere Suchbegriffe)

Bulk-Endpunkte

Gemeinsames Limit: 1000 Einträge pro Request

Support