API-Referenz Kategorien

Erstellen, Abrufen und Zuordnen von Kategorien.Der Endpunkt categories/ stellt Ihnen eine Schnittstelle bereit mit der Sie Kategorie-Daten in unserem Shop-System verwalten können. Mit dieser Schnittstelle können Sie Kategorien abrufen, erstellen, löschen und Produkte Kategorien zuweisen.

---

Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	PUT	POST	DELETE
Kategorien	categories/
Produktzuweisung

Datenfelder eine Kategorie (Category Resource)

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

• Standardfelder: Vom System vorgegeben und immer vorhanden (z. B. 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 (z. B. zur Anzeige im Frontend)
active	String	Aktivitätsstatus ("always", "never", "test" (aktiv nur im Testmodus))
productAssignmentType	String	Art der Produktzuweisung ("manual", "ruleBased")
productRules	String	Geparstes Objekt, das Regeln für Produktzuweisung enthält
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 (z. B. image, seoName, robotsNoIndex etc.)

Zusätzliche Felder

_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"
}

Methoden für Kategorien

GET categories

Dieser Endpunkt liefert eine Liste von Kategorien aus dem Shopsystem.

Eine Sortierung, Textsuche oder komplexe Filterung ist derzeit nicht möglich. Es kann jedoch gezielt nach Unterkategorien einer bestimmten Kategorie gefiltert werden, indem der Parameter filter[parent] verwendet wird.

Wird 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) sowie der untergeordneten Kategorien (_children) 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/

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

parent

Sortierfelder

Nicht unterstützt

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder 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/

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) sowie die Liste aller direkt untergeordneten Kategorien (_children) 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

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 oder 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/

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 erforderlich.

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 oder 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 einen Format, der 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//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 von Kategorie-IDs übergeben werden, die der angegebenen Kategorie als untergeordnet (_children) zugeordnet werden sollen.

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 oder 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//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 oder 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//setRule

Mit diesem Endpunkt können einer bestehenden Kategorie anhand ihrer ID mehrere Produkte zugewiesen werden.

Im Request-Body muss ein als JSON serialisiertes Array von Regeln übergeben werden. Produkte, auf die die Regeln zutreffen, werden der Kategorie zugewiesen.

rebuilt in der Antwort 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 oder 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 oder 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.

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 oder 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 einen Format, der 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.

DELETE categories/

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 oder 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 entweder manuell oder regelbasiert zugewiesen werden:

• Manuelle Zuweisung bedeutet, dass bestimmte Produkte gezielt einzelnen Kategorien zugeordnet werden (z. B. „Produkt A gehört zu Kategorie B“).
• Regelbasierte Zuweisung erlaubt es, Kategorien automatisch mit Produkten zu befüllen, die bestimmte Kriterien erfüllen (z. B. „alle reduzierten Produkte“ oder „alle Produkte mit Lagerbestand > 0“).

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.

GET categories//products

Mit diesem Endpunkt wird eine Liste aller Produkte abgerufen, die einer bestimmten Kategorie anhand ihrer ID zugewiesen sind.

Die Parameter from und size dienen der Aufteilung großer Ergebnismengen in Seiten – damit die API nicht z. B. 10.000 Produkte auf einmal übertragen muss. from gibt an, wie viele Einträge am Anfang übersprungen werden, size bestimmt die maximale Anzahl der zurückgegebenen Produkte.

Zusätzlich kann mit dem optionalen Parameter textSearch eine Textsuche innerhalb der zugewiesenen Produkte durchgeführt werden.

Für die Nutzung dieses Endpunkts sind Leseberechtigungen für Kategorie-Daten 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": "0.000000",
            "taxRateId": "7",
            "timestampCreatedAt": "2024-09-11T09:01:15.000Z",
            "timestampUpdatedAt": "2024-12-16T14:20:41.000Z"
        },
        ...
    ],
    "totalCount": 8
}

Filterfelder

nicht unterstützt

Sortierfelder

productId (muss nicht explizit angegeben werden. sort:asc bzw. sort:desc reicht aus)

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Kategorie-Daten.
400 Bad Request	”invalidValue”
400 Bad Request	”syntaxError”	sort enthält mehr als einen oder keinen ”:”.

GET categories/products/unassigned

Mit diesem Endpunkt wird eine Liste aller Produkte abgerufen, die aktuell keiner Kategorie zugewiesen sind.

Die Parameter from und size dienen der Aufteilung großer Ergebnismengen in Seiten – damit die API nicht z. B. 10.000 Produkte auf einmal übertragen muss. from gibt an, wie viele Einträge am Anfang übersprungen werden, size bestimmt die maximale Anzahl der zurückgegebenen Produkte.

Der optionale Parameter textSearchermöglicht eine Textsuche innerhalb der nicht zugewiesenen Produkte.

Für die Nutzung dieses Endpunkts sind Leseberechtigungen für Kategorie-Daten 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": "0.000000",
            "taxRateId": "",
            "timestampCreatedAt": "2024-09-26T10:50:23.000Z",
            "timestampUpdatedAt": "2024-12-16T14:14:42.000Z"
        },
        ...
    ],
    "totalCount": 15
}

Filterfelder

nicht unterstützt

Sortierfelder

productId (muss nicht explizit angegeben werden.sort:ascbzw.sort:desc reicht aus)

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Kategorie-Daten.
400 Bad Request	”invalidValue”
400 Bad Request	”syntaxError”	sort enthält mehr als einen oder keinen ”:”.

POST categories//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 – entweder als String (ein einzelnes Produkt) oder als Array von Strings (mehrere Produkte).

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 oder 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.
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//products/swap

Dieser Endpunkt ermöglicht es, die Position von zwei Produkten innerhalb einer bestimmten Kategorie zu tauschen. Die Produkt-IDs werden im Request-Body übergeben. Die Antwort gibt zurück, 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 oder 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.
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//products/

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 aufgehoben – das Produkt bleibt im System bestehen, ist jedoch nicht mehr dieser Kategorie zugeordnet.

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 oder 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//products/

Mit diesem Endpunkt können mehrere Produkte gleichzeitig aus einer bestimmten Kategorie anhand ihrer ID entfernt werden.

Die zu entfernenden Produkt-IDs werden im Feld prodId als Array übergeben.
Dadurch wird die Zuordnung der Produkte zur angegebenen Kategorie aufgehoben – die Produkte selbst bleiben im System erhalten.

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 oder 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.
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

• API-Referenz Produkte
• API-Referenz Konfiguration
• content - Katalog (Kategorien & Produkte)

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 lassen sich individuelle Felder. Sobald ein Feld dort konfiguriert wurde, steht es anschließend automatisch in der Produkt-API zur Verfügung (z. B. 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.