API-Referenz Kategorien - WEBSALE Dokumentation

Über den Endpunkt categories/ steht Ihnen eine Schnittstelle zur Verfügung, mit der Sie Kategoriedaten in unserem Shop-System verwalten können. Über diese Schnittstelle können Sie Kategorien abrufen, erstellen, aktualisieren, verschieben und löschen, Produkten Kategorien zuweisen und abfragen, in welchen Kategorien ein Produkt liegt. Die folgenden Abschnitte beschreiben zunächst die Datenfelder einer Kategorie, dann die Methoden für Kategorien und schließlich die Methoden für die Produktzuweisung.

Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	PUT	POST	DELETE
Kategorien	categories/
Produktzuweisung	`categories/\{categoryId\}/products/` `categories/products/unassigned` `products/\{productId\}/categories`

Datenfelder einer Kategorie (Category Resource)

Die Datenfelder einer Kategorie werden in der Konfiguration verwaltet und als JSON-Objekt intern gespeichert.
Es wird zwischen den folgenden Feldtypen unterschieden:

Standardfelder: Vom System vorgegeben und immer vorhanden (beispielsweise id, name, descr, hidden)
Benutzerdefinierte Felder: Können flexibel angelegt werden und befinden sich im Abschnitt custom des Objekts
Technische Felder zur Strukturabbildung: Dienen der Darstellung der Kategoriestruktur im Shop
Dazu gehören:
- _parent: ID der übergeordneten Kategorie
- _children: Liste der untergeordneten Kategorien
- sortValue: technischer Sortierwert zur Bestimmung der tatsächlichen Reihenfolge im Shop

Name	Typ	Bedeutung
id	String	Eindeutige ID der Kategorie
name	String	Anzeigename der Kategorie
descr	String	Beschreibungstext (beispielsweise zur Anzeige im Frontend)
active	String	Aktivitätsstatus (`"always"`, `"never"`, `"test"` (aktiv nur im Testmodus))
productAssignmentType	String	Art der Produktzuweisung (`"manual", "ruleBased", "handUp"`)
productRules	String	Als JSON serialisierte Regeln für die regelbasierte Produktzuweisung
hidden	Boolean	Gibt an, ob die Kategorie im Frontend ausgeblendet werden soll
timestampCreatedAt	String	Zeitpunkt, zu dem die Kategorie erstellt wurde (ISO 8601-Format, UTC).
timestampUpdatedAt	String	Zeitpunkt der letzten Änderung (ISO 8601-Format, UTC).
custom	Objekt	Objekt für benutzerdefinierte Felder
custom.<technischer Feldname>	Benutzerdefiniert	Benutzerdefiniertes Feld, frei definierbar über die Konfiguration (beispielsweise `image`, `seoName` oder `robotsNoIndex`)

Zusätzliche Felder

Name	Typ	Bedeutung
_parent	String	ID der übergeordneten Kategorie (leer bei Hauptkategorie)
_children	Array von Strings	Liste der IDs untergeordneter Kategorien
sortValue	Int	Position der Kategorie in dem Shop

Beispiel des Datensatzes

{
    "_children": [
        "107-06636",
        "108-64674"
    ],
    "_parent": "",
    "active": "always",
    "custom": {
        "alternativeTemplate": "",
        "image": [],
        "robotsNoFollow": false,
        "robotsNoIndex": false,
        "seoName": ""
    },
    "descr": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, ...",
    "hidden": false,
    "id": "100-14213",
    "name": "Bekleidung",
    "productAssignmentType": "manual",
    "productRules": "[{\"field\":\"active\",\"mode\":\"eq\",\"value\":\"always\"},{\"field\":\"itemNumber\",\"mode\":\"contains\",\"value\":\"5\"}]",
    "sortValue": 62,
    "timestampCreatedAt": "2024-01-10T13:36:31.000Z",
    "timestampUpdatedAt": "2024-09-26T10:41:54.000Z"
}

Breaking Change in Antworten. Kategoriefelder vom Typ Price werden nicht mehr als String, sondern als Objekt mit Standardpreis und geplanten Aktionspreisen ausgeliefert. Aufbau, erlaubtes Format in Requests und Validierung sind identisch mit den Produktfeldern und im Abschnitt Zeitgesteuerte Preise (Aktionspreise) beschrieben.

Methoden für Kategorien

GET categories

Dieser Endpunkt liefert eine Liste von Kategorien aus dem Shopsystem. Die Liste lässt sich nach Feldern filtern und sortieren. Zusätzlich steht der Parameter textSearch für eine Textsuche zur Verfügung. Felder, die Ihr Shop selbst angelegt hat, sprechen Sie als custom.<technischer Feldname> an. Mit dem eigenen Parameter filter[parent] erhalten Sie gezielt die direkten Unterkategorien einer Kategorie. Dazu zählen die Unterkategorien, die selbst zu den Filtern passen oder weiter unten einen Treffer enthalten. Wird filter[parent]=root gesetzt, werden alle Hauptkategorien der obersten Ebene zurückgegeben. Durch den Parameter withExternData=yes können zusätzlich die IDs der übergeordneten Kategorie (_parent) und der untergeordneten Kategorien (_children) sowie der Sortierwert (sortValue) mitgeladen werden. Mit subshopId lassen sich die Kategorien eines bestimmten Subshops abfragen. Für die Nutzung dieses Endpunkts sind Leseberechtigungen für Kategorie-Daten erforderlich.

Beispiel

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

Beispiel mit withExternData=yes, um _parent und _children mitzuladen:

https://www.<ihr-shop>.de/admin/api/v1/categories/?withExternData=yes

Antwort

{
    "items": [
        {
            "_children": [],
            "_parent": "372-87532",
            "active": "never",
            "custom": {
                "alternativeTemplate": "",
                "image": [],
                "metaDescription": "",
                "metaDescriptionSetManually": false,
                "metaTitle": "",
                "metaTitleSetManually": false,
                "regger": "",
                "robotsNoFollow": false,
                "robotsNoIndex": false,
                "seoName": ""
            },
            "descr": "test",
            "hidden": false,
            "id": "245-10358",
            "name": "Neue Kategorie",
            "productAssignmentType": "manual",
            "productRules": "",
            "sortValue": 42,
            "timestampCreatedAt": "2024-09-17T07:44:56.000Z",
            "timestampUpdatedAt": "2024-12-16T14:14:42.000Z"
        },
        ...
    ],
    "endReached": true,
    "nextPageToken": "",
    "totalCount": 7
}

Filterfelder

id, name, descr, active, hidden, productAssignmentType, productRules, timestampCreatedAt, timestampUpdatedAt sowie custom.<technischer Feldname> für selbst angelegte Felder. filter[parent] ist ein eigener Parameter und gehört nicht zu den Filterfeldern.

Sortierfelder

Alle Kategoriefelder und custom.<technischer Feldname>, ausgenommen Felder vom Typ Liste, Map, Bild und Video.

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Lesen von Kategorie-Daten.
400 Bad Request	”invalidValue”
400 Bad Request	”invalidCombination”	`pageToken` und `from` sind gleichzeitig gesetzt.
400 Bad Request	”illegalOperation”	Es wird versucht, Kategorien nach einem Feld vom Typ `Liste`, `Map`, `Bild` oder `Video` zu filtern. Eine ungültige Filteroperation wurde auf ein Enum-Feld angewendet. Nur `=` oder `≠` sind erlaubt.
400 Bad Request	”unknownDataField”	Ein Filter- oder Sortierfeld ist ungültig.
400 Bad Request	”unknownOperation”	Ein Filtertyp ist ungültig.
400 Bad Request	”invalidCharacters”	`size` ist keine Ganzzahl. Ein Filterwert ist ungültig.
400 Bad Request	”syntaxError”	`sort` enthält mehr als einen oder keinen ”:“.
404 Not Found		Die übergeordnete Kategorie wurde nicht gefunden.

GET categories/{categoryId}

Dieser Endpunkt lädt die vollständigen Daten einer einzelnen Kategorie anhand ihrer ID. Optional kann mit dem Parameter withExternData=yes zusätzlich die ID der übergeordneten Kategorie (_parent), die Liste aller direkt untergeordneten Kategorien (_children) und der Sortierwert (sortValue) mitgeliefert werden. Für die Nutzung des Endpunkts sind Leseberechtigungen für Kategorie-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/categories/942-53775

Beispiel mit withExternData=yes, um _parent und _children mitzuladen:

https://www.<ihr-shop>.de/admin/api/v1/categories/942-53775?withExternData=yes

Antwort

{
    "_children": [],
    "_parent": "",
    "active": "always",
    "custom": {
        "alternativeTemplate": "",
        "image": [],
        "metaDescription": "",
        "metaDescriptionSetManually": false,
        "metaTitle": "",
        "metaTitleSetManually": false,
        "regger": "",
        "robotsNoFollow": false,
        "robotsNoIndex": false,
        "seoName": ""
    },
    "descr": "123",
    "hidden": false,
    "id": "942-53775",
    "name": "Neue Kategorie",
    "productAssignmentType": "manual",
    "productRules": "",
    "sortValue": 42,
    "timestampCreatedAt": "2024-09-25T15:03:15.000Z",
    "timestampUpdatedAt": "2024-12-16T14:14:43.000Z"
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Lesen von Kategorie-Daten.
400 Bad Request	”invalidValue"	"stage” ist ungültig.
404 Not Found		Es gibt keine Kategorie mit `id`=`categoryId`.

PUT categories/{categoryId}

Mit diesem Endpunkt kann eine bestehende Kategorie anhand ihrer ID aktualisiert werden. Der Request-Body muss nur die Felder enthalten, die tatsächlich geändert werden sollen. Eine vollständige Kategorie-Definition ist nicht notwendig. Wird der optionale Parameter createMissing=yes gesetzt und existiert keine Kategorie mit der angegebenen ID, wird stattdessen eine neue Kategorie mit dieser ID angelegt. Für die Nutzung dieses Endpunkts sind Schreibberechtigungen für Kategorie-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/categories/1081-68843

Request Body

{
    "custom": {
        "robotsNoFollow": true
    },
    "active": "always",
    "descr": "My new description"
}

Antwort

{
    "active": "always",
    "custom": {
        "alternativeTemplate": "",
        "image": [],
        ...
    },
    "descr": "My new description",
    "hidden": false,
    "id": "1081-68843",
    "name": "Bekleidung",
    "productAssignmentType": "manual",
    "productRules": "",
    "timestampCreatedAt": "2024-01-10T13:36:31.000Z",
    "timestampUpdatedAt": "2025-05-02T14:22:10.000Z"
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Schreiben von Kategorie-Daten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”invalidValue"	"stage” ist ungültig. Ein Feld vom Typ `Enumeration` enthält einen Wert, der nicht in der Menge von möglichen Werten enthalten ist. Ein Bild hat ein Format, das nicht unterstützt wird.
400 Bad Request	”invalidFormat”	`custom` ist kein Objekt. Ein Feld enthält den Wert `null`. Ein Wert hat den Typ, der mit dem Typ aus der Konfiguration nicht übereinstimmt. Ein Preis-Wert kann nicht geparst werden. Ein Feld vom Typ `Map` hat einen Schlüssel, der kein String ist. Ein Feld vom Typ `List` ist kein Array von Strings. Ein Zeitwert ist nicht in ISO 8601 Format. Bild-Daten von einem Bild sind kein Array von Objekten. `id` des Formats oder `path` sind keine Strings.
400 Bad Request	”unknownDataField”	Es wird versucht, ein unbekanntes Feld zu aktualisieren. Bild-Daten enthalten etwas außer `id` und `path`.
400 Bad Request	”notManualEditable”	In der Konfiguration wurde manuelles Bearbeiten verboten.
404 Not Found		Die Kategorie mit `id`=`{categoryId}` wurde nicht gefunden und der Parameter `createMissing` ist nicht auf `yes` gesetzt.
503 Service Unavailable	”internalError”	Die Aktualisierung ist fehlgeschlagen.

PUT categories/{categoryId}/assign

Mit diesem Endpunkt können einer bestehenden Kategorie anhand ihrer ID mehrere Unterkategorien zugewiesen werden. Der spezielle Wert categoryId: “root” sorgt dafür, dass die Kategorien als Hauptkategorien auf die oberste Ebene kommen. Im Request-Body muss ein Array mit Kategorie-IDs übergeben werden. Diese sollen der angegebenen Kategorie als untergeordnet (_children) zugeordnet werden. Die übergebene Liste ersetzt die bisherigen Unterkategorien in der angegebenen Reihenfolge. Kategorien, die bisher Unterkategorien waren und in der Liste fehlen, verlieren ihren Platz im Kategoriebaum. Um eine einzelne Kategorie zu verschieben, ohne die übrigen Unterkategorien neu schreiben zu müssen, verwenden Sie POST categories/{categoryId}/move. Für die Nutzung dieses Endpunkts sind Schreibberechtigungen für Kategorie-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/categories/1081-68843/assign

Request Body

{
    "categoryIds": [
        "1032-22182",
        "109-30589",
        "105-09206"
    ]
}

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Schreiben von Kategorie-Daten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”invalidValue"	"stage” ist ungültig.
404 Not Found		Die Kategorie mit `id`=`{categoryId}` wurde nicht gefunden.
400 Bad Request	”unknownDataField”	Es wurde etwas außer `categoryIds` übergeben.
400 Bad Request	”invalidFormat”	`categoryIds` ist kein Array von Strings.

POST categories/{categoryId}/move

Mit diesem Endpunkt kann eine bestehende Kategorie anhand ihrer ID innerhalb der Kategoriestruktur verschoben werden. Die Positionierung erfolgt entweder durch Einordnung als Unterkategorie (intoTarget) oder durch Sortierung auf derselben Ebene (beforeTarget oder afterTarget). Es darf nur einer dieser Zielparameter gesetzt sein. Für die Nutzung dieses Endpunkts sind Schreibberechtigungen für Kategorie-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/categories/1081-68843/move

Request Body

{
    "beforeTarget": "1080-40793"
}

Antwort

{
    "active": "never",
    "custom": {
        "alternativeTemplate": "",
        "defaultSort": "",
        "image": [],
        "metaDescription": "",
        "metaDescriptionSetManually": false,
        "metaTitle": "",
        "metaTitleSetManually": false,
        "robotsNoFollow": false,
        "robotsNoIndex": false,
        "seoName": "",
        "video": ""
    },
    "descr": "test",
    "hidden": false,
    "id": "1081-68843",
    "name": "Neue Kategorie",
    "productAssignmentType": "manual",
    "productRules": "",
    "timestampCreatedAt": "2025-05-02T13:59:38.000Z",
    "timestampUpdatedAt": "2025-05-02T13:59:38.000Z"
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Schreiben von Kategorie-Daten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”invalidValue"	"stage” ist ungültig. Die neue Position ist in einer Unterkategorie der Kategorie, die verschoben werden soll.
400 Bad Request	”missing”	Es fehlt ein Target-Parameter (`intoTarget`, `beforeTarget`, `afterTarget`).
400 Bad Request	”invalidFormat”	`intoTarget`, `beforeTarget` oder `afterTarget` sind keine Strings.
400 Bad Request	”unknownDataField”	Request body enthält etwas außer `intoTarget`, `beforeTarget`, `afterTarget`.
400 Bad Request	”invalidCombination”	Mehrere Target-Parameter (`intoTarget`, `beforeTarget`, `afterTarget`) können nicht gleichzeitig gesetzt werden.
404 Not Found		Die Kategorie mit `id`=`{categoryId}` wurde nicht gefunden. ”Target” enthält keine gültige Id.

POST categories/{categoryId}/setRule

Über diesen Endpunkt können einer bestehenden Kategorie anhand ihrer ID mehrere Produkte zugewiesen werden. Dabei wird die Kategorie auf die regelbasierte Produktzuweisung (ruleBased) umgestellt. Im Request-Body muss ein als JSON serialisiertes Array von Regeln übergeben werden. Produkte, auf die die Regeln zutreffen, werden der Kategorie zugewiesen. Die Antwort enthält den Wertcount, der die ANzahl der Produkte angibt, auf die die Regel zutrifft. rebuilt gibt an, ob die Regel sofort angewendet werden konnte. Wenn der Wert false ist, wird es später erneut versucht. Der Endpunkt muss dafür nicht erneut getriggert werden. Für die Nutzung dieses Endpunkts sind Schreibberechtigungen für Kategorie-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/categories/1081-68843/setRule

Request Body

{
    "rule": "[{\"field\":\"name\",\"mode\":\"contains\",\"value\":\"h\"},{\"field\":\"price\",\"mode\":\"lt\",\"value\":\"100\"}]"
}

Antwort

{
    "count": 167,
    "rebuilt": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Schreiben von Kategorie-Daten.
400 Bad Request		Request body konnte nicht geladen werden. Die Regel funktioniert nicht. Diese Regel trifft auf zu viele Produkte zu.
400 Bad Request	”invalidValue"	"stage” ist ungültig.
404 Not Found		Die Kategorie mit `id`=`{categoryId}` wurde nicht gefunden.
400 Bad Request	”invalidFormat”	`rule` ist kein String.
400 Bad Request	”unknownDataField”	Request body enthält etwas außer `rule`.

POST categories/rebuildRules

Dieser Endpunkt aktualisiert Produkte in Kategorien mit regelbasierter Produktzuweisung. Für die Nutzung dieses Endpunkts sind Schreibberechtigungen für Kategorie-Daten erforderlich.

Beispiel

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

Request Body

{}

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Schreiben von Kategorie-Daten.
503 Service Unavailable	”internalError”	Die interne URL des Rebuilder-Programms ist nicht gesetzt. Das Rebuilder-Programm konnte nicht gestartet werden.

POST categories

Mit diesem Endpunkt kann eine neue Kategorie im Shop-System erstellt werden.
Über die optionalen Parameter intoTarget, beforeTarget oder afterTarget lässt sich festlegen, wo die neue Kategorie in der Kategoriestruktur einsortiert werden soll:

Mit intoTarget wird sie als Unterkategorie einer bestehenden Kategorie angelegt.
Der spezielle Wert intoTarget: "root" sorgt dafür, dass die neue Kategorie als Hauptkategorie auf der obersten Ebene erstellt wird.
Mit beforeTarget oder afterTarget wird sie auf derselben Ebene vor oder nach einer vorhandenen Kategorie einsortiert.

Es darf jeweils nur ein Zielparameter gesetzt sein. Wenn die übergebene Kategorie-ID bereits vergeben ist, lehnt der Shop die Anfrage mit dem Status 409 Conflict ab. Eine vorhandene Kategorie wird dabei nicht überschrieben. Für die Nutzung dieses Endpunkts sind Erstellberechtigungen für Kategorie-Daten erforderlich.

Beispiel

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

Request Body

{
    "name": "Neue Kategorie",
    "intoTarget": "root"
}

Antwort

{
    "active": "never",
    "custom": {
        "alternativeTemplate": "",
        "image": [],
        "metaDescription": "",
        "metaDescriptionSetManually": false,
        "metaTitle": "",
        "metaTitleSetManually": false,
        ...
    },
    "descr": "",
    "hidden": false,
    "id": "1080-40793",
    "name": "Neue Kategorie",
    "productAssignmentType": "manual",
    "productRules": "",
    "timestampCreatedAt": "",
    "timestampUpdatedAt": ""
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Erstellen von Kategorie-Daten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”invalidValue"	"stage” ist ungültig. “Target” enthält keine gültige Id. Ein Feld vom Typ `Enumeration` enthält einen Wert, der nicht in der Menge von möglichen Werten enthalten ist. Ein Bild hat ein Format, das nicht unterstützt wird.
400 Bad Request	”invalidCombination”	Mehrere Target-Parameter (`intoTarget`, `beforeTarget`, `afterTarget`) können nicht gleichzeitig gesetzt werden.
400 Bad Request	”invalidFormat”	`custom` ist kein Objekt. Ein Feld enthält den Wert `null`. Ein Wert hat den Typ, der mit dem Typ aus der Konfiguration nicht übereinstimmt. Ein Preis-Wert kann nicht geparst werden. Ein Feld vom Typ `Map` hat einen Schlüssel, der kein String ist. Ein Feld vom Typ `List` ist kein Array von Strings. Ein Zeitwert ist nicht in ISO 8601 Format. Bild-Daten von einem Bild sind kein Array von Objekten. `id` des Formats oder `path` sind keine Strings.
400 Bad Request	”unknownDataField”	Es wird versucht, ein unbekanntes Feld zu aktualisieren. Bild-Daten enthalten etwas außer `id` und `path`.
400 Bad Request	”notManualEditable”	In der Konfiguration wurde manuelles Bearbeiten verboten.
409 Conflict		Eine Kategorie mit der übergebenen `id` existiert bereits.

DELETE categories/{categoryId}

Mit diesem Endpunkt kann eine bestehende Kategorie anhand ihrer ID gelöscht werden.
Dabei werden nicht nur die gewählte Kategorie selbst, sondern auch alle zugehörigen Unterkategorien aus dem System entfernt. Für die Nutzung dieses Endpunkts sind Löschberechtigungen für Kategorie-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/categories/1081-68843

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Löschen von Kategorie-Daten.
400 Bad Request	”invalidValue"	"stage” ist ungültig.
404 Not Found		Die Kategorie wurde nicht gefunden.

Methoden für Produktzuweisung

Technische Limits

Produkte können Kategorien manuell, regelbasiert oder über die Unterkategorien zugewiesen werden:

Manuelle Zuweisung bedeutet, dass bestimmte Produkte gezielt einzelnen Kategorien zugeordnet werden (beispielsweise „Produkt A gehört zu Kategorie B“).
Regelbasierte Zuweisung erlaubt es, Kategorien automatisch mit Produkten zu befüllen, die bestimmte Kriterien erfüllen (beispielsweise „alle reduzierten Produkte“ oder „alle Produkte mit Lagerbestand > 0“).
Produkte von Unterkategorien übernehmen, hiermit werden Kategorien automatisch mit allen Produkten befüllt, die den direkten Unterkategorien zugewiesen sind. Beispielsweise enthält die Kategorie “Damen” alle Produkte aus den Unterkategorien “Damenblusen” und “Damenröcke”.

Bei regelbasierten Kategorien ist die maximale Anzahl an zugewiesenen Produkten technisch auf 1.000 Ergebnisse begrenzt, unabhängig von der Anzahl der Produkte im Shop oder von der formulierten Regel. Wenn Produkte über mehrere Hierarchie-Ebenen übernommen werden sollen, müssen alle Kategorieebenen ihre Produkte ebenfalls aus den Unterkategorien übernehmen. Andernfalls werden nur die Produkte der direkten Unterkategorie übernommen, aber nicht die Produkte deren Kinder. Beispiel:

|-Kategorie A (Produkte von Unterkategorien übernehmen)
| |-Kategorie B (Manuell)
| | |-Kategorie C (Manuell)
| |-Kategorie D (Produkte von Unterkategorien übernehmen)
| | |-Kategorie E (Regelbasiert)
| | |-Kategorie F (Manuell)
| |- Kategorie G (Regelbasiert)

Kategorie A bekommt alle Produkte aus den Kategorien B, D, E, F und G zugeordnet. Die Produkte aus Kategorie C werden Kategorie A jedoch nicht zugeordnet, da die Produktzuweisung für Kategorie B “Manuell” ist und nicht “Produkte von Unterkategorien übernehmen”.

GET categories/{categoryId}/products

Über diesen Endpunkt wird eine Liste aller Produkte abgerufen, die anhand ihrer ID einer bestimmten Kategorie zugewiesen sind. Er entspricht der Anfrage GET products?inCategory={categoryId}, nimmt dieselben Parameter entgegen und liefert dieselben Einträge. Eine vollständige Beschreibung der Parameter, Filter- und Sortierfelder ist unter GET products zu finden. Mithilfe der Parameter from und size können große Ergebnismengen in Seiten aufgeteilt werden, sodass die API beispielsweise nicht 10.000 Produkte auf einmal übertragen muss. Mit from wird angegeben, wie viele Einträge am Anfang übersprungen werden sollen. size bestimmt die maximale Anzahl der zurückgegebenen Produkte und muss im Bereich von 1 bis 300 liegen. Mit dem optionalen Parameter textSearch kann zusätzlich eine Textsuche innerhalb der zugewiesenen Produkte durchgeführt werden. Für die Nutzung dieses Endpunkts sind Leseberechtigungen für Produkte erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/categories/105-09206/products?from=0&size=50

Antwort

{
    "endReached": true,
    "items": [
        {
            "active": "never",
            "custom": {
                "brand": "",
                "commission": 0,
                "commissionTaxRate": "",
                ...
            },
            "descr": "SUPER COOL PRODUCT",
            "id": "100-41232",
            "itemNumber": "999999999",
            "name": "Something",
            "price": {
                "price": "0.000000",
                "scheduledPrices": []
            },
            "taxRateId": "7",
            "timestampCreatedAt": "2024-09-11T09:01:15.000Z",
            "timestampUpdatedAt": "2024-12-16T14:20:41.000Z"
        },
        ...
    ],
    "totalCount": 8
}

Filterfelder

Alle Produktdatenfelder sowie benutzerdefinierte Felder beginnen mit dem Präfix custom.. Die Details dazu finden Sie unter GET products.

Sortierfelder

Alle Produktdatenfelder mit Ausnahme der Felder vom Typ Liste, Map, Bild und Video. Ohne den Parameter sort liefert der Endpunkt die Produkte in der im Shop gepflegten Kategoriereihenfolge.

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Lesen von Produkten.
400 Bad Request	”invalidValue"	"stage” ist ungültig. `size` ∉ [1;300] `pageToken` ist keine Zahl oder kleiner als 0. `from` ist größer als 9999. Es wird versucht, nach einem Feld vom Typ `Liste`, `Map`, `Bild` oder `Video` zu sortieren.
400 Bad Request	”syntaxError”	`sort` enthält mehr als einen oder keinen ”:“.
400 Bad Request	”unknownDataField”	Ein Filter- oder Sortierfeld ist ungültig.
400 Bad Request	”illegalOperation”	Ein Filtertyp ist ungültig.
400 Bad Request	”invalidCharacters”	Ein Filterwert ist ungültig. `size` ist keine Ganzzahl.

GET categories/products/unassigned

Mit diesem Endpunkt wird eine Liste aller Produkte abgerufen, die aktuell keiner Kategorie zugewiesen sind. Er entspricht der Anfrage GET products?notInAnyCategory=true, nimmt dieselben Parameter entgegen und liefert dieselben Einträge. Die vollständige Beschreibung der Parameter, Filter- und Sortierfelder ist unter GET products zu finden. Mithilfe der Parameter from und size können große Ergebnismengen in Seiten aufgeteilt werden, damit die API beispielsweise nicht 10.000 Produkte auf einmal übertragen muss. Mit from wird angegeben, wie viele Einträge am Anfang übersprungen werden sollen. size bestimmt die maximale Anzahl der zurückgegebenen Produkte und muss im Bereich von 1 bis 300 liegen. Mithilfe des optionalen Parameters textSearch ist eine Textsuche innerhalb der nicht zugewiesenen Produkte möglich. Für die Nutzung dieses Endpunkts sind Leseberechtigungen für Produkte erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/categories/products/unassigned?from=0&size=50

Antwort

{
    "endReached": true,
    "items": [
        {
            "active": "never",
            "custom": {
                "brand": "",
                "commission": 0,
                "commissionTaxRate": "",
                ...
            },
            "descr": "",
            "id": "124-28218",
            "itemNumber": "",
            "name": "Neues Produkt",
            "price": {
                "price": "0.000000",
                "scheduledPrices": []
            },
            "taxRateId": "",
            "timestampCreatedAt": "2024-09-26T10:50:23.000Z",
            "timestampUpdatedAt": "2024-12-16T14:14:42.000Z"
        },
        ...
    ],
    "totalCount": 15
}

Filterfelder

Alle Produktdatenfelder sowie benutzerdefinierte Felder beginnen mit dem Präfix custom.. Die Details dazu finden Sie unter GET products.

Sortierfelder

Alle Produktdatenfelder mit Ausnahme der Felder vom Typ Liste, Map, Bild und Video.

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Lesen von Produkten.
400 Bad Request	”invalidValue"	"stage” ist ungültig. `size` ∉ [1;300] `pageToken` ist keine Zahl oder kleiner als 0. `from` ist größer als 9999. Es wird versucht, nach einem Feld vom Typ `Liste`, `Map`, `Bild` oder `Video` zu sortieren.
400 Bad Request	”syntaxError”	`sort` enthält mehr als einen oder keinen ”:“.
400 Bad Request	”unknownDataField”	Ein Filter- oder Sortierfeld ist ungültig.
400 Bad Request	”illegalOperation”	Ein Filtertyp ist ungültig.
400 Bad Request	”invalidCharacters”	Ein Filterwert ist ungültig. `size` ist keine Ganzzahl.

GET products/{productId}/categories

Mit diesem Endpunkt werden alle Kategorien abgerufen, denen ein bestimmtes Produkt zugewiesen ist. Damit lässt sich die Zuweisung aus der umgekehrten Richtung prüfen: Statt der Produkte einer Kategorie erhalten Sie die Kategorien eines Produkts. Enthalten sind alle Zuweisungsarten, also manuelle und regelbasierte Zuweisungen sowie Zuweisungen über „Produkte von Unterkategorien übernehmen“. Es gilt derselbe Stand wie bei GET categories/{categoryId}/products. Auch inaktive und ausgeblendete Kategorien werden geliefert. Ob eine Kategorie im Shop sichtbar ist, erkennen Sie an den Feldern active und hidden. Die Liste wird vollständig in einer Antwort geliefert. Die Parameter from, size und textSearch sowie Filter und Sortierung werden nicht unterstützt. Die Kategorien erscheinen in der Reihenfolge, in der die Zuweisungen angelegt wurden. Diese Reihenfolge entspricht nicht der Reihenfolge in der Navigation des Shops. Kategorien werden Produkten zugewiesen, nicht einzelnen Varianten. Geben Sie deshalb die Produkt-ID an. Wie bei GET categories stehen folgende optionale Parameter zur Verfügung:

withExternData=yes liefert zu jeder Kategorie zusätzlich _parent, _children und sortValue.
subshopId fragt die Zuweisungen eines bestimmten Subshops ab.

Für die Nutzung dieses Endpunkts sind Leseberechtigungen für Kategorie-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/100-41232/categories

Antwort

Jeder Eintrag in items hat denselben Aufbau wie bei GET categories/{categoryId}.

{
    "endReached": true,
    "items": [
        {
            "active": "always",
            "custom": {
                "alternativeTemplate": "",
                "image": [],
                "robotsNoFollow": false,
                "robotsNoIndex": false,
                "seoName": ""
            },
            "descr": "",
            "hidden": false,
            "id": "100-14213",
            "name": "Bekleidung",
            "productAssignmentType": "manual",
            "productRules": "",
            "timestampCreatedAt": "2024-01-10T13:36:31.000Z",
            "timestampUpdatedAt": "2024-09-26T10:41:54.000Z"
        },
        ...
    ],
    "nextPageToken": "",
    "totalCount": 2
}

Ist das Produkt keiner Kategorie zugewiesen, ist items leer und totalCount ist 0.

Filterfelder

Nicht unterstützt.

Sortierfelder

Nicht unterstützt.

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Lesen von Kategorie-Daten.
400 Bad Request	”invalidValue"	"stage” ist ungültig.
404 Not Found	”missingProduct”	Das Produkt wurde nicht gefunden.

POST categories/{categoryId}/products/assign

Mit diesem Endpunkt können ein oder mehrere Produkte anhand ihrer Produkt-IDs einer bestimmten Kategorie anhand ihrer Kategorie-ID zugewiesen werden. Die Produkt-IDs werden im Feld prodId übergeben. Das Feld akzeptiert entweder einen String (ein einzelnes Produkt) oder ein Array von Strings (mehrere Produkte). Der Endpunkt funktioniert nur bei Kategorien mit der Produktzuweisung manual, bei anderen Kategorien lehnt der Shop die Anfrage ab. Ohne Positionsangabe werden die Produkte am Ende der Kategorie angehängt. Durch den optionalen Query-Parameter updateIndex=yes wird der Suchindex der betroffenen Produkte sofort aktualisiert, anstatt bis zum nächsten geplanten Lauf zu warten. Optional kann mit den Parametern beforeTarget oder afterTarget festgelegt werden, an welcher Position innerhalb der Kategorie die Produkte einsortiert werden sollen. Beide dürfen nicht gleichzeitig gesetzt sein. Für die Nutzung dieses Endpunkts sind Schreibberechtigungen für Kategorie-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/categories/105-09206/products/assign

Request Body

{
    "prodId": [
        "111-28077",
        "110-64564"
    ]
}

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Schreiben von Kategorie-Daten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request		Die Kategorie hat nicht die Produktzuweisung `manual`.
400 Bad Request	”invalidValue"	"stage” ist ungültig.
400 Bad Request	”invalidFormat”	`prodId` ist kein Array von Strings und kein String. `beforeTarget` oder `afterTarget` sind keine Strings.
400 Bad Request	”unknownDataField”	Ein anderes Feld außer `prodId`, `beforeTarget` oder `afterTarget` wurde übergeben.
400 Bad Request	”missing”	Keine Produkt-ID wurde übergeben.
404 Not Found	”missingCategory”	Die Kategorie wurde nicht gefunden.
404 Not Found	”missingTarget”	Die Position innerhalb der Kategorie ist ungültig.
409 Conflict	”multipleTargets”	`beforeTarget` und `afterTarget` wurden gleichzeitig gesetzt.
409 Conflict	”entityNotFound”	Man versucht, ein Produkt, das nicht existiert, zuzuweisen.

POST categories/{categoryId}/products/swap

Über diesen Endpunkt können die Positionen zweier Produkten innerhalb einer bestimmten Kategorie getauscht werden. Er funktioniert nur bei Kategorien, die mit der Produktzuweisung manual versehen sind. Die Produkt-IDs werden im Request-Body übergeben. Die Antwort gibt Auskunft darüber, ob der Tausch erfolgreich durchgeführt werden konnte. Für die Nutzung dieses Endpunkts sind Schreibrechte für Kategorie-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/categories/105-09206/products/swap

Request Body

{
    "productId1": "111-28077",
    "productId2": "110-64564"
}

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Schreiben von Kategorie-Daten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request		Die Kategorie hat nicht die Produktzuweisung `manual`.
400 Bad Request	”invalidValue"	"stage” ist ungültig.
400 Bad Request	”invalidFormat”	`productId1` oder `productId2` sind keine Strings.
400 Bad Request	”missing”	`productId1` oder `productId2` fehlen.
400 Bad Request	”unknownDataField”	Ein unbekanntes Feld wurde übergeben.
404 Not Found	”missingCategory”	Die Kategorie wurde nicht gefunden.

DELETE categories/{categoryId}/products/{productId}

Mit diesem Endpunkt wird ein Produkt anhand seiner ID aus einer bestimmten Kategorie anhand ihrer ID entfernt. Dadurch wird die Verknüpfung zwischen Produkt und Kategorie aufgelöst. Das Produkt bleibt im System bestehen, ist jedoch nicht mehr dieser Kategorie zugeordnet. Mit dem optionalen Query-Parameter updateIndex=yes wird der Suchindex des Produkts sofort aktualisiert, ohne dass es auf den nächsten geplanten Lauf warten muss. Für die Nutzung dieses Endpunkts sind Schreibberechtigungen für Kategorie-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/categories/105-09206/products/123456

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Schreiben von Kategorie-Daten.
400 Bad Request	”invalidValue"	"stage” ist ungültig.
404 Not Found	”missingCategory”	Die Kategorie wurde nicht gefunden.
404 Not Found	”missingProduct”	Das Produkt wurde nicht gefunden.

DELETE categories/{categoryId}/products/

Mit diesem Endpunkt können mehrere Produkte gleichzeitig aus einer bestimmten Kategorie anhand ihrer ID entfernt werden. Die zu entfernenden Produkt-IDs werden als Array im Feld prodId übergeben.
Dadurch wird die Zuordnung der Produkte zur angegebenen Kategorie aufgehoben. Die Produkte selbst bleiben im System erhalten. Der Endpunkt funktioniert nur bei Kategorien mit der Produktzuweisung manual. Mit dem optionalen Query-Parameter updateIndex=yes wird der Suchindex der betroffenen Produkte sofort aktualisiert, anstatt auf den nächsten geplanten Lauf zu warten. Für die Nutzung dieses Endpunkts sind Schreibberechtigungen für Kategorie-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/categories/105-09206/products/

Request Body

{
    "prodId": [
        "111-28077",
        "110-64564"
    ]
}

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Schreiben von Kategorie-Daten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request		Die Kategorie hat nicht die Produktzuweisung `manual`.
400 Bad Request	”invalidValue"	"stage” ist ungültig.
400 Bad Request	”invalidFormat”	Ein Produktindex ist kein String. `prodId` ist kein Array.
400 Bad Request	”unknownDataField”	Ein anderes Feld außer `prodId` wurde übergeben.
400 Bad Request	”missing”	`prodId` fehlt.
404 Not Found	”missingCategory”	Die Kategorie wurde nicht gefunden.

Ergänzende Referenzen

Hinweis zu Kategoriedatenfeldern

Neue Kategoriedatenfelder (zusätzliche Beschreibungen, Bilder etc.) können nicht direkt über die Kategorie-API erstellt werden. Die API dient ausschließlich dem Auslesen und Pflegen vorhandener Felder. Um neue Felder zu definieren, muss die Konfiguration im Knoten content.customCategoryField verwendet werden. → content - Katalog (Kategorien & Produkte) Dort können individuelle Felder definiert werden. Sobald ein Feld dort konfiguriert wurde, steht es anschließend automatisch in der Kategorie-API zur Verfügung, beispielsweise in GET categories oder POST categories.

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.

​Unterstützte Methoden

​Datenfelder einer Kategorie (Category Resource)

​Zusätzliche Felder

​Beispiel des Datensatzes

​Methoden für Kategorien

​GET categories

​Beispiel

​Antwort

​Filterfelder

​Sortierfelder

​Fehlercodes

​GET categories/{categoryId}

​Beispiel

​Antwort

​Fehlercodes

​PUT categories/{categoryId}

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​PUT categories/{categoryId}/assign

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​POST categories/{categoryId}/move

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​POST categories/{categoryId}/setRule

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​POST categories/rebuildRules

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​POST categories

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​DELETE categories/{categoryId}

​Beispiel

​Antwort

​Fehlercodes

​Methoden für Produktzuweisung

​Technische Limits

​GET categories/{categoryId}/products

​Beispiel

​Antwort

​Filterfelder

​Sortierfelder

​Fehlercodes

​GET categories/products/unassigned

​Beispiel

​Antwort

​Filterfelder

​Sortierfelder

​Fehlercodes

​GET products/{productId}/categories

​Beispiel

​Antwort

​Filterfelder

​Sortierfelder

​Fehlercodes

​POST categories/{categoryId}/products/assign

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​POST categories/{categoryId}/products/swap

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​DELETE categories/{categoryId}/products/{productId}

Unterstützte Methoden

Datenfelder einer Kategorie (Category Resource)

Zusätzliche Felder

Beispiel des Datensatzes

Methoden für Kategorien

GET categories

Beispiel

Antwort

Filterfelder

Sortierfelder

Fehlercodes

GET categories/{categoryId}

Beispiel

Antwort

Fehlercodes

PUT categories/{categoryId}

Beispiel

Request Body

Antwort

Fehlercodes

PUT categories/{categoryId}/assign

Beispiel

Request Body

Antwort

Fehlercodes

POST categories/{categoryId}/move

Beispiel

Request Body

Antwort

Fehlercodes

POST categories/{categoryId}/setRule

Beispiel

Request Body

Antwort

Fehlercodes

POST categories/rebuildRules

Beispiel

Request Body

Antwort

Fehlercodes

POST categories

Beispiel

Request Body

Antwort

Fehlercodes

DELETE categories/{categoryId}

Beispiel

Antwort

Fehlercodes

Methoden für Produktzuweisung

Technische Limits

GET categories/{categoryId}/products

Beispiel

Antwort

Filterfelder

Sortierfelder

Fehlercodes

GET categories/products/unassigned

Beispiel

Antwort

Filterfelder

Sortierfelder

Fehlercodes

GET products/{productId}/categories

Beispiel

Antwort

Filterfelder

Sortierfelder

Fehlercodes

POST categories/{categoryId}/products/assign

Beispiel

Request Body

Antwort

Fehlercodes

POST categories/{categoryId}/products/swap

Beispiel

Request Body

Antwort

Fehlercodes

DELETE categories/{categoryId}/products/{productId}