API-Referenz Produkte - WEBSALE Dokumentation

Über den Endpunkt /products können Sie eine Schnittstelle nutzen, um Produktdaten und Lagerbestände in unserem Shop-System zu verwalten. Sie können damit Produkte erstellen, bearbeiten, filtern, abrufen und löschen sowie Lagerbestandsinformationen zu Produkten abrufen, aktualisieren und löschen. Hinzu kommen Variantenattribute, Produktvarianten und Set-Produkte. Für größere Datenmengen stehen Bulk-Endpunkte bereit. Die folgende Übersicht zeigt, welche Endpunkte welche Methoden unterstützen. Im Anschluss beschreibt die Seite die Datenfelder und die zeitgesteuerten Preise. Anschließend werden die einzelnen Endpunkte geordnet nach Produkten, Variantenattributen, Produktvarianten, Lagerbeständen und Set-Produkten beschrieben.

Unterstützte Methoden

Befehl/Info	Endpunkte	GET	POST	PUT	DELETE
Allgemeines Produkt	products/
Allgemeines Produkt (Bulk)	bulk/products
Kategorien eines Produkts	products/{productId}/categories
Produkt-URL	products/{productId}/url
Regeltest	products/testRule
Variantenattribute	products/variants
Reihenfolge der Optionen	products/variants/{attributeId}/positions
Varianten	products/{productId}/variants
Variantenattribute eines Produkts	products/{productId}/variantAttributes
Variantenattribute verschieben	products/{productId}/variantAttributes/move
Varianten (Bulk)	bulk/products/variants
Lagerbestand Allgemein	products/inventory
Lagerbestand für Produkte	products/{productId}/inventory
Lagerbestand für Varianten	products/{productId}/variants/{variantId}/inventory
Lagerbestand (Bulk)	bulk/products/inventory
Lagereinstellungen (Bulk)	bulk/products/inventoryConfig
Set-Produkte	products/{parentProductId}/setproducts
Set-Produkte aktualisieren	products/{parentProductId}/setproducts/update/{childProductId}
Set-Preisvorschau	products/setproducts/preview

Datenfelder

Felder werden in der Konfiguration verwaltet und als ein JSON-Objekt in der Tabelle gespeichert. Es wird unterschieden zwischen Standardproduktdatenfeldern und benutzerdefinierten Produktdatenfeldern. Benutzerdefinierte Produktdatenfelder können beliebig angelegt werden, während Standardproduktdatenfelder vom Shop vorgegeben werden und immer definiert sind. Alle benutzerdefinierte Produktdatenfelder sind im Abschnitt custom zu finden. Alle anderen Einträge stellen Standardproduktdatenfelder dar.

Name	Typ	Bedeutung
active	String	Aktivitätsstatus des Produkts (beispielsweise „always“, „never“)
custom	Objekt	Benutzerdefinierte Felder
custom.liste	Array	Beispielhafte Liste
custom.map	Objekt	Beispielhafte Schlüssel-Wert-Zuordnungen
custom.validInsertCodes	Array	Liste der für dieses Produkt gültigen Werbemittelkennzeichen. Jeder Eintrag maximal 16 Zeichen. Nur wirksam, wenn das Feld in `content.usedFields.products.validInsertCodes` zugeordnet und die Werbemittelkennzeichnung aktiv ist.
custom.robotsNoFollow	Boolean	True = Link zu diesem Produkt sollte von Suchmaschinen nicht gefolgt werden
custom.robotsNoIndex	Boolean	True = Produktseite sollte nicht in Suchmaschinen indiziert werden
custom.weight	Float	Gewicht des Produkts in Kilogramm (zur Priorisierung oder Sortierung)
descr	String	Produktbeschreibung
hasVariants	Boolean	Gibt an, ob das Produkt Varianten besitzt (beispielsweise Größe, Farbe)
id	String	Technische ID des Produkts
itemNumber	String	Artikelnummer (kann identisch mit `id` sein)
name	String	Klartext-Name des Produkts
price	Objekt	Standardpreis des Produkts und dessen geplante Aktionspreise. Den Aufbau beschreibt der Abschnitt Zeitgesteuerte Preise (Aktionspreise).
ratingApprovalConfig.maximumRating	Float	Maximal zulässige Bewertung (beispielsweise 5)
ratingApprovalConfig.minimumRating	Float	Minimal zulässige Bewertung (beispielsweise 0)
statistics.averageRating	Float	Durchschnittliche Bewertung des Produkts
statistics.ratingCount	Integer	Anzahl der abgegebenen Bewertungen
statisticsPerPoint	Array	Bewertungshistogramm als Liste von Paaren `[Wert, Anzahl]`: für jeden möglichen Wert die Anzahl der Bewertungen
taxRateId	String	ID des angewendeten Steuersatzes
timestampCreatedAt	String	Zeitpunkt der Erstellung (ISO 8601-Format, UTC)
timestampUpdatedAt	String	Zeitpunkt der letzten Produktänderung (ISO 8601-Format, UTC)

Die Felder statistics, statisticsPerPoint und ratingApprovalConfig liefert nur GET products/{productId}. Die Listenabfrage GET products enthält sie nicht.

Beispielhafter Datensatz

{
    "active": "always",
    "custom": {
        "liste": [
            "123",
            "234",
            "456"
        ],
        "map": {
            "a": "b",
            "c": "d",
            "e": "f"
        },
        "robotsNoFollow": false,
        "robotsNoIndex": false,
        "weight": 0.33
    },
    "descr": "Lässiges Barbour-Shirt aus Baumwoll-Piqué mit Langarm.<span class='passform'> Gearbeitet in gerader, normaler Passform (Regular Fit)</span> mit Kontrastbesatz im 'Barbour-Tartan' an der Knopfleiste und im Kragen. Mit klassischem Polokragen, Ärmelbündchen und gesticktem Barbour-Logo. Ein Mode-Klassiker für die Freizeit, in dem sich jeder Mann wohlfühlt.<span class='mass'> Länge ca. 75 cm.</span><span class='katalogfarbe'>Farbe: Navy.</span><span class='herkunft'> Original Barbour. </span>  <span class='groessen'> Größen: M (48), L (50), XL (52/54), XXL (56/58), XXXL (58/60) </span>  <span class='material'> Reine Baumwolle.</span>",
    "hasVariants": true,
    "id": "11-1701",
    "itemNumber": "11-1701",
    "name": "Tartan-Langarm-Polo in Navy",
    "price": {
        "price": "89.900000",
        "scheduledPrices": []
    },
    "ratingApprovalConfig": {
        "maximumRating": 5,
        "minimumRating": 0
    },
    "statistics": {
        "averageRating": 0,
        "ratingCount": 0
    },
    "taxRateId": "1",
    "statisticsPerPoint": [
        [
            0,
            0
        ],
        [
            1,
            0
        ],
        [
            2,
            0
        ],
        [
            3,
            0
        ],
        [
            4,
            0
        ],
        [
            5,
            0
        ]
    ],
    "timestampCreatedAt": "2024-11-14T10:41:25.000Z",
    "timestampUpdatedAt": "2025-01-24T09:28:06.000Z"
}

Zeitgesteuerte Preise (Aktionspreise)

Produkte können Preise mit einem Gültigkeitszeitraum tragen. Damit lassen sich Aktionspreise im Voraus pflegen, ohne dass zum Aktionsstart ein Import oder eine manuelle Änderung nötig ist. Dieser Abschnitt beschreibt zuerst das Format der Preisfelder in Antworten, danach das erlaubte Format in Requests, anschließend die Wirkung im Shop und zuletzt die Validierung. Wer nur wissen will, was an bestehenden Anbindungen anzupassen ist, findet die kurze Antwort im folgenden Hinweis.

Breaking Change in Antworten. Jedes Feld vom Typ Price wird in Produkt-Antworten nicht mehr als String, sondern als Objekt ausgeliefert. Betroffen sind das Basisfeld price und alle benutzerdefinierten Preisfelder. Anbindungen, die den Preis direkt als String weiterverarbeiten, müssen angepasst werden. Die Änderung betrifft alle Endpunkte, die Produktdaten ausliefern, also die Abfrage einzelner Produkte, Listenabfragen, die Antworten von Erstellen und Aktualisieren sowie die Bulk-Endpunkte.

Preisfelder in Antworten

Ein Preisfeld enthält den Standardpreis und die Liste der geplanten Aktionspreise. Die Liste scheduledPrices ist immer vorhanden. Sind keine Aktionspreise gepflegt, wird sie als leeres Array ausgeliefert.

Antwort (Auszug)

{
    "price": {
        "price": "19.990000",
        "scheduledPrices": [
            {
                "price": "14.990000",
                "startDate": "2026-08-01T00:00:00.000Z",
                "endDate": "2026-08-31T23:59:59.000Z",
                "promotionInfo": "Sommeraktion",
                "validForDiscount": true
            }
        ]
    }
}

Vor dieser Änderung stand an derselben Stelle ein reiner String:

{
    "price": "19.990000"
}

Parameterübersicht

Parameter	Typ	Beschreibung
`price`	`string`	Standardpreis des Feldes. Er gilt immer dann, wenn kein Aktionspreis aktiv ist.
`scheduledPrices`	`array` (object)	Liste der geplanten Aktionspreise. Leeres Array, wenn keine gepflegt sind.
`scheduledPrices[].price`	`string`	Aktionspreis für diesen Zeitraum. Pflichtangabe und größer als `0`.
`scheduledPrices[].startDate`	`string`	Beginn des Zeitraums im Format ISO 8601 (UTC). Ein leerer String bedeutet offener Beginn, der Eintrag gilt also von Anfang an.
`scheduledPrices[].endDate`	`string`	Ende des Zeitraums im Format ISO 8601 (UTC). Ein leerer String bedeutet offenes Ende, der Eintrag gilt also unbefristet.
`scheduledPrices[].promotionInfo`	`string`	Freier Text zur Aktion, beispielsweise für eine Kennzeichnung im Shop. Das Feld fehlt in der Antwort, wenn kein Text gesetzt ist.
`scheduledPrices[].validForDiscount`	`bool`	Gibt an, ob während des Aktionszeitraums weitere Rabatte auf den Preis gewährt werden. Standardwert `true`.

Der Zeitraum ist an beiden Enden einschließend. Ein Eintrag mit endDate auf 2026-08-31T23:59:59.000Z ist zu genau dieser Sekunde noch aktiv.

Bei Produktvarianten kann ein Preisfeld auch null sein. Der Typ eines Preisfelds ist für Anbindungen deshalb object | null. Wann dieser Fall auftritt, beschreibt der Abschnitt Methoden für Produktvarianten.

Preisfelder in Requests

Eingehend bleibt die Schnittstelle abwärtskompatibel. Ein Preisfeld darf weiterhin als reiner String übergeben werden. Bestehende Schreibzugriffe funktionieren damit unverändert weiter. Angepasst werden muss nur, wer Aktionspreise über die Schnittstelle pflegen will. Alternativ nimmt die Schnittstelle das Objekt in derselben Struktur an, in der sie es ausliefert. Wird das Feld scheduledPrices nicht mitgeschickt, bleiben bestehende Einträge erhalten. Ein leer übergebenes Array löscht alle Einträge.

Request Body (Auszug)

{
    "price": {
        "price": "19.99",
        "scheduledPrices": [
            {
                "price": "14.99",
                "startDate": "2026-08-01T00:00:00.000Z",
                "endDate": "2026-08-31T23:59:59.000Z",
                "promotionInfo": "Sommeraktion",
                "validForDiscount": true
            }
        ]
    }
}

Wirkung im Shop

Zu jedem Zeitpunkt wird genau ein Preis aufgelöst. Die Auflösung geschieht bei jeder Anfrage neu, es wird also kein Preis vorberechnet und gespeichert. Welcher Preis gilt, entscheiden drei Regeln. Erstens greift ein Aktionspreis nur dann, wenn er den Standardpreis nicht überschreitet. Einträge über dem Standardpreis werden bei der Auflösung übersprungen. In diesem Fall bleibt der Standardpreis gültig. Zweitens wird bei mehreren gleichzeitig aktiven Einträgen der niedrigste Preis verwendet. Bei gleichem Preis gewinnt der Eintrag mit dem späteren startDate, ein offener Beginn verliert also. Sind auch die Startzeitpunkte gleich, entscheidet die Reihenfolge im Array. Drittens ersetzt ein eigenes Preisfeld an einer Variante den Standardpreis und den Zeitplan des Basisprodukts gemeinsam. Mehr dazu im Abschnitt Methoden für Produktvarianten.

Die Validierung prüft einen Aktionspreis nicht gegen den Standardpreis. Ein Eintrag über dem Standardpreis wird gespeichert und in der Antwort wieder ausgeliefert, er greift aber nie. Das wirkt auch nachträglich. Wird der Standardpreis später unter einen bestehenden Aktionspreis gesenkt, verliert dieser Eintrag stillschweigend seine Wirkung.

Für den Suchindex gilt eine Einschränkung. Preisfelder werden ausschließlich mit ihrem Standardpreis indexiert. Geplante Aktionspreise stehen im Index nicht zur Verfügung und können deshalb nicht gefiltert oder sortiert werden.

Validierung und Fehlerschlüssel

Jeder Eintrag wird einzeln geprüft. Fehlerhafte Angaben führen zu 400 Bad Request. Der Fehlerschlüssel enthält den Index des betroffenen Eintrags im Array.

Fehlerschlüssel	Typ	Grund
`<feld>.scheduledPrices[<i>]`	”invalidFormat”	Der Eintrag ist kein Objekt.
`<feld>.scheduledPrices[<i>].price`	”missing”	`price` fehlt oder ist leer.
`<feld>.scheduledPrices[<i>].price`	”invalidFormat”	`price` kann nicht als Preis geparst werden.
`<feld>.scheduledPrices[<i>].price`	”invalidValue”	`price` ist kleiner oder gleich `0`.
`<feld>.scheduledPrices[<i>].startDate`	”invalidFormat”	`startDate` ist nicht im Format ISO 8601.
`<feld>.scheduledPrices[<i>].endDate`	”invalidFormat”	`endDate` ist nicht im Format ISO 8601.
`<feld>.scheduledPrices[<i>].endDate`	”invalidValue”	`startDate` liegt nach `endDate`.

Geprüft wird ausschließlich der Eintrag selbst. Ein Vergleich mit dem Standardpreis oder mit anderen Einträgen findet nicht statt. Überlappende Zeiträume und Preise über dem Standardpreis führen deshalb nicht zu einem Fehler, sondern wirken sich erst bei der Auflösung aus. Welcher Eintrag dann greift, beschreibt der Abschnitt Wirkung im Shop.

Hinweis zum internen Speicherformat

Für Werkzeuge, die direkt auf dem gespeicherten Datenblob eines Produkts oder einer Kategorie arbeiten, gilt eine Besonderheit. Dort tragen die beiden Wrapper eine andere Bezeichnung als im REST-Vertrag. Die inneren Schlüssel eines Eintrags sind identisch.

Bedeutung	REST-Vertrag	Gespeicherter `data`-Blob
Standardpreis	`price`	`standard`
Zeitplan	`scheduledPrices`	`schedule`

Beide Lesepfade akzeptieren zusätzlich das alte Format als reinen String. Bestandsdaten müssen dafür nicht migriert werden.

Methoden für Produkte

Die hier dokumentierten Endpunkte ermöglichen den Lese-, Schreib-, Änderungs- und Löschzugriff auf Produktdaten im Shopsystem. Sie können zur Verwaltung des Produktkatalogs genutzt werden, sowohl zur Initialbefüllung als auch zur laufenden Aktualisierung von Inhalten. Zusätzlich stehen Endpunkte zur Verfügung, um Produktsuchen auf Basis definierter Regeln durchzuführen. Da jeder Subshop eine eigene Produktmenge hat, sollen URLs den Parameter subshopId enthalten. Ist der angegebene Subshop im Shop nicht vorhanden, wird die Anfrage mit dem Statuscode 400 Bad Request und dem Fehlercode "invalidValue" für das Feld subshopId abgelehnt. Für alle Endpunkte ist eine gültige Authentifizierung erforderlich. Die jeweiligen Berechtigungen zum Lesen, Schreiben, Erstellen oder Löschen von Produkten müssen vorhanden sein.

GET products

Mit diesem Endpunkt können Sie eine Liste aller Produkte im System abrufen. Optional kann die Ergebnismenge mithilfe von Filterparametern eingeschränkt werden, beispielsweise auf Produkte, die einer bestimmten Kategorie zugeordnet sind (inCategory) oder aus einer bestimmten Kategorie ausgeschlossen werden sollen (notInCategory). Beide Parameter dürfen nicht gleichzeitig verwendet werden. Damit der Endpunkt verwendet werden kann, müssen die entsprechenden Berechtigungen zum Lesen von Produkten vorhanden sein.

Reihenfolge bei `inCategory`

Wird inCategory verwendet und kein eigener sort-Parameter angegeben, liefert der Endpunkt die Produkte genau in der im Shop gepflegten Kategoriereihenfolge. GET products?inCategory={categoryId} und GET categories/{categoryId}/products sind dabei gleichwertig: Der Kategorie-Endpunkt setzt intern nichts anderes als inCategory und wertet denselben Code aus. Es gibt also keinen Grund, für die Kategoriereihenfolge auf den anderen Endpunkt zu wechseln.

Sobald Sie selbst einen sort-Parameter setzen, gilt die Kategoriereihenfolge für keinen der beiden Endpunkte mehr. Ihre Sortierung ersetzt sie vollständig. Wenn Sie die ursprüngliche Reihenfolge benötigen, lassen Sie sort einfach weg.

Beispiel

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

Antwort

{
    "endReached": false,
    "items": [
        {
            "active": "always",
            "custom": {
                ...
            },
            "descr": "Lässiges Barbour-Shirt aus Baumwoll-Piqué mit Langarm.<span class='passform'> Gearbeitet in gerader, normaler Passform (Regular Fit)</span> mit Kontrastbesatz im 'Barbour-Tartan' an der Knopfleiste und im Kragen. Mit klassischem Polokragen, Ärmelbündchen und gesticktem Barbour-Logo. Ein Mode-Klassiker für die Freizeit, in dem sich jeder Mann wohlfühlt.<span class='mass'> Länge ca. 75 cm.</span><span class='katalogfarbe'>Farbe: Navy.</span><span class='herkunft'> Original Barbour. </span>  <span class='groessen'> Größen: M (48), L (50), XL (52/54), XXL (56/58), XXXL (58/60) </span>  <span class='material'> Reine Baumwolle.</span>",
            "hasVariants": false,
            "id": "11-1701",
            "itemNumber": "11-1701",
            "name": "Tartan-Langarm-Polo in Navy",
            "price": {
                "price": "89.900000",
                "scheduledPrices": []
            },
            "taxRateId": "1",
            "timestampCreatedAt": "2024-11-14T10:41:25.000Z",
            "timestampUpdatedAt": "2025-01-24T09:28:06.000Z"
        }
    ],
    "nextPageToken": "MTAw",
    "searchAfterToken": "WzAuMCwiMTEtMjgxNV9kZXV0c2NoXzMiXQ",
    "totalCount": 1296
}

Filterfelder

Alle Produktdatenfelder lassen sich filtern. Benutzerdefinierte Felder tragen das Präfix custom., beispielsweise filter_eq[custom.brand]=Barbour.

Filterbar bedeutet nicht „mit jeder Operation kombinierbar”: Welche Filteroperationen erlaubt sind, hängt vom Datentyp des Feldes ab. Auf einem Enum-Feld wie active sind beispielsweise nur eq und neq zulässig, contains führt zu 400 Bad Request mit dem Typ illegalOperation. Die vollständige Matrix steht ist in den API Basics: Erlaubte Operationen je Feldtyp zu finden.

Zusätzlich zu den Produktdatenfeldern stehen folgende Filter als einfache Query-Parameter zur Verfügung (ohne filter_-Präfix und ohne Klammern):

Parameter	Beschreibung
`inCategory={categoryId}`	Nur Produkte, die dieser Kategorie zugewiesen sind.
`notInCategory={categoryId}`	Nur Produkte, die dieser Kategorie nicht zugewiesen sind.
`notInAnyCategory=true`	Nur Produkte, die keiner Kategorie zugewiesen sind.
`inSetProduct={productId}`	Nur Produkte, die Bestandteil dieses Set-Produkts sind.
`notInSetProduct={productId}`	Nur Produkte, die nicht Bestandteil dieses Set-Produkts sind.

Die Attribute inCategory und notInCategory bzw. inSetProduct und notInSetProduct dürfen nicht gleichzeitig gesetzt werden (Fehler invalidCombination). Das Gleiche gilt für notInAnyCategory=true in Verbindung mit inCategory oder notInCategory.

Sortierfelder

Alle Produktdatenfelder außer den Typen Liste, Map, Bild und Video. Eine Sortierung nach diesen Typen führt zu einer Fehlermeldung 400 Bad Request mit dem Typ invalidValue. Syntax: sort=<Feldname>:asc bzw. sort=<Feldname>:desc. Der Feldname ist Pflicht. Eine Kurzform wie sort=asc ist ein Syntaxfehler. Mehrere Sortierkriterien werden über mehrere sort-Parameter übergeben. Weitere Informationen finden Sie in den API Basics: Sortierung.

Sonstige Parameter

Zusätzlich stehen folgende Query-Parameter zur Verfügung:

Parameter	Beschreibung
`size`	Anzahl der Produkte pro Antwort.
`from`	Anzahl der Treffer, die übersprungen werden (numerischer Offset).
`pageToken`	Token der nächsten Seite. Übergeben Sie den Wert aus `nextPageToken` der vorherigen Antwort unverändert.
`searchAfterToken`	Token aus dem Feld `searchAfterToken` der vorherigen Antwort. Damit lässt sich Seite für Seite auch bei sehr großen Ergebnismengen blättern.
`textSearch`	Freitext, auf den die Produkte durchsucht werden.
`includeVariants`	Ist der Parameter auf `yes` gesetzt, wird für jedes Produkt in der Antwort unter dem Schlüssel `variants` zusätzlich eine Liste aller für dieses Produkt definierten Varianten ausgegeben. Die Varianten eines einzelnen Produkts können Sie auch über `GET products/{productId}/variants` abrufen.

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		Request body konnte nicht geladen werden.
400 Bad Request	”invalidValue"	"stage” ist ungültig `size` liegt nicht zwischen 1 und 300. Es wird versucht, Produkte nach einem Feld vom Typ `Liste`, `Map`, `Bild` oder `Video` zu sortieren.
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.
400 Bad Request	”invalidCombination”	Die Filter `inCategory` und `notInCategory` oder `inSetProduct` und `notInSetProduct` sind gleichzeitig gesetzt. `notInAnyCategory=true` ist zusammen mit `inCategory` oder `notInCategory` gesetzt.
503 Service Unavailable	”serviceUnavailable”	Das Lesen von Daten ist fehlgeschlagen.

GET products/{productId}

Mit diesem Endpunkt können Sie die vollständigen Daten eines einzelnen Produkts abrufen. Geben Sie dazu die Produkt-ID als Pfadparameter an. Neben den Basisdaten werden auch benutzerdefinierte Felder zurückgegeben. Damit der Endpunkt verwendet werden kann, müssen die entsprechenden Berechtigungen zum Lesen von Produkten vorhanden sein.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/11-1701?subshopId=deutsch

Antwort

{
    "active": "always",
    "custom": {
        "liste": [
            "123",
            "234",
            "456"
        ],
        "map": {
            "a": "b",
            "c": "d",
            "e": "f"
        },
        "robotsNoFollow": false,
        "robotsNoIndex": false,
        "weight": 0.33
    },
    "descr": "Lässiges Barbour-Shirt aus Baumwoll-Piqué mit Langarm.<span class='passform'> Gearbeitet in gerader, normaler Passform (Regular Fit)</span> mit Kontrastbesatz im 'Barbour-Tartan' an der Knopfleiste und im Kragen. Mit klassischem Polokragen, Ärmelbündchen und gesticktem Barbour-Logo. Ein Mode-Klassiker für die Freizeit, in dem sich jeder Mann wohlfühlt.<span class='mass'> Länge ca. 75 cm.</span><span class='katalogfarbe'>Farbe: Navy.</span><span class='herkunft'> Original Barbour. </span>  <span class='groessen'> Größen: M (48), L (50), XL (52/54), XXL (56/58), XXXL (58/60) </span>  <span class='material'> Reine Baumwolle.</span>",
    "hasVariants": false,
    "id": "11-1701",
    "itemNumber": "11-1701",
    "name": "Tartan-Langarm-Polo in Navy",
    "price": {
        "price": "89.900000",
        "scheduledPrices": [
            {
                "price": "79.900000",
                "startDate": "2026-08-01T00:00:00.000Z",
                "endDate": "2026-08-31T23:59:59.000Z",
                "promotionInfo": "Sommeraktion",
                "validForDiscount": true
            }
        ]
    },
    "ratingApprovalConfig": {
        "maximumRating": 5.0,
        "minimumRating": 1.0
    },
    "statistics": {
        "averageRating": 4.5,
        "ratingCount": 12
    },
    "statisticsPerPoint": [
        [1, 0],
        [2, 1],
        [3, 2],
        [4, 3],
        [5, 6]
    ],
    "taxRateId": "1",
    "timestampCreatedAt": "2024-11-14T10:41:25.000Z",
    "timestampUpdatedAt": "2025-01-24T09:28:06.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 Produkten.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben.
404 Not Found		Produkt mit `id`=`{id}` wurde nicht gefunden.

GET products/{productId}/url

Mit diesem Endpunkt können Sie die vollständige URL eines Produkts abrufen. Für die Nutzung dieses Endpunkts sind Leseberechtigungen für Produkt-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/143-68071/url?subshopId=deutsch

Antwort

https://www.<ihr-shop>.de/SEOURL/

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”	Es wurde eine ungültige Stage angegeben.

GET products/{productId}/categories

Über diesen Endpunkt können Sie die Kategorien (Warengruppen) abrufen, denen ein Produkt zugeordnet ist. Die Kategorien werden in der Reihenfolge angezeigt, in der die Zuordnungen angelegt wurden. Die Liste wird nicht seitenweise ausgeliefert, sondern enthält immer alle Kategorien des Produkts. Jeder Eintrag hat den Aufbau einer Kategorie aus der API-Referenz Kategorien. Mit dem Parameter withExternData=yes liefert jeder Eintrag zusätzlich _parent und _children. Um den Endpunkt verwenden zu können, müssen die entsprechenden Berechtigungen zum Lesen von Kategorien vorhanden sein.

Beispiel

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

Antwort

{
    "endReached": true,
    "items": [
        {
            "active": "always",
            "custom": {},
            "descr": "",
            "hidden": false,
            "id": "942-53775",
            "name": "Poloshirts",
            "productAssignmentType": "manual",
            "productRules": "",
            "timestampCreatedAt": "2024-09-25T15:03:15.000Z",
            "timestampUpdatedAt": "2024-12-16T14:14:43.000Z"
        }
    ],
    "nextPageToken": "",
    "totalCount": 1
}

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 Kategorien.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben.
404 Not Found		Es gibt kein Produkt mit der angegebenen `productId`.

GET products/testRule

Mit diesem Endpunkt können Sie gezielt Produkte abrufen, die einer oder mehreren angegebenen Regeln entsprechen. Die Regeln werden als JSON-formatiertes Array in der Query-URL übergeben und ermöglichen eine flexible Filterung nach Produktfeldern wie beispielsweise Aktivitätsstatus, Artikelnummern oder Preisangaben. Die Regeln dürfen nur gültige Felder und zulässige Operatoren enthalten. Damit dieser Endpunkt verwendet werden kann, müssen die entsprechenden Berechtigungen zum Lesen von Produktdaten vorhanden sein. Der Parameter size ist Pflicht und muss einen Wert zwischen 1 und 1000 enthalten. Der value einer Regel muss immer ein String sein, auch bei Zahlenwerten.

Beispiel

Die Regeln werden in der URL als JSON-Array kodiert und über den Parameter rules übergeben. Um korrekt interpretiert zu werden, muss dieser Parameter URL-dekodiert werden.

https://www.<ihr-shop>.de/admin/api/v1/products/testRule?size=100&rules=%5B%7B%22field%22%3A%22active%22%2C%22mode%22%3A%22eq%22%2C%22value%22%3A%22always%22%7D%2C%7B%22field%22%3A%22itemNumber%22%2C%22mode%22%3A%22contains%22%2C%22value%22%3A%225%22%7D%5D

Die URL ruft Produkte ab, die zwei Bedingungen erfüllen:

Das Feld active muss den Wert always haben.
Es werden nur dauerhaft aktive Produkte berücksichtigt.
Die Artikelnummer (itemNumber) muss die Ziffer „5“ enthalten.
Es werden nur Produkte ausgewählt, deren Artikelnummer irgendwo die „5“ enthält (beispielsweise 11-2518).

Filter und Sortierungen auf Preisfeldern greifen auf den Standardpreis zu. Geplante Aktionspreise werden dabei nicht berücksichtigt.

Antwort

{
    "items": [
        {
            "active": "always",
            "custom": {
                "brand": "",
                "commission": 0,
                "commissionTaxRate": "",
                "crossSelling": [],
                "customNumber": "",
                "ean": "",
                "filterField": "",
                "image": [],
                "isbn": "",
                "mainCategory": "",
                "metaDescription": "",
                "metaDescriptionSetManually": false,
                "metaTitle": "",
                "metaTitleSetManually": false,
                "multiProducts": "",
                "oneTimeFee": 0,
                "oneTimeFeeTaxRate": "",
                "productDiscount": 0,
                "productDiscountAbsolute": false,
                "productType": "",
                "robotsNoFollow": false,
                "robotsNoIndex": false,
                "validForDiscount": false,
                "video": "",
                "voucherProductActive": false,
                "voucherProductHtmlTemplate": "",
                "voucherProductPrice": false,
                "voucherProductTemplate": "",
                "weight": 0
            },
            "descr": "Dieses weiße Poloshirt ist alles andere als gewöhnlich, sondern ...",
            "hasVariants": true,
            "id": "11-2451",
            "itemNumber": "11-2451",
            "name": "Samtweiches Polo aus Luxusjersey",
            "price": {
                "price": "89.900000",
                "scheduledPrices": []
            },
            "taxRateId": "1",
            "timestampCreatedAt": "2025-02-14T10:50:38.000Z",
            "timestampUpdatedAt": "2025-04-28T10:24:24.000Z"
        },
        {
            "active": "always",
            "custom": {
                "brand": "",
                "commission": 0,
                "commissionTaxRate": "",
                "crossSelling": [],
                "customNumber": "",
                "ean": "",
                "filterField": "",
                "image": [],
                "isbn": "",
                "mainCategory": "",
                "metaDescription": "",
                "metaDescriptionSetManually": false,
                "metaTitle": "",
                "metaTitleSetManually": false,
                "multiProducts": "",
                "oneTimeFee": 0,
                "oneTimeFeeTaxRate": "",
                "productDiscount": 0,
                "productDiscountAbsolute": false,
                "productType": "",
                "robotsNoFollow": false,
                "robotsNoIndex": false,
                "validForDiscount": false,
                "video": "",
                "voucherProductActive": false,
                "voucherProductHtmlTemplate": "",
                "voucherProductPrice": false,
                "voucherProductTemplate": "",
                "weight": 0
            },
            "descr": "Einmal angezogen, wollen Sie aus diesem kuschelig weichen Flane...",
            "hasVariants": true,
            "id": "11-2518",
            "itemNumber": "11-2518",
            "name": "Lieblingshemd aus Fischgrat-Gewebe",
            "price": {
                "price": "79.900000",
                "scheduledPrices": []
            },
            "taxRateId": "1",
            "timestampCreatedAt": "2025-02-14T10:50:45.000Z",
            "timestampUpdatedAt": "2025-04-28T10:24:24.000Z"
        },
        ...
    ],
    "nextPageToken": "WzAuMCwiMTQzLTY4MDcxX2RldXRzY2hfMyJd",
    "totalCount": 64,
    "warnings": {
        "invalidValue": [],
        "unknownFilters": [],
        "wrongOperators": []
    }
}

Mögliche Werte für `mode`

gt (größer), gte (größer oder gleich), lt (kleiner), lte (kleiner oder gleich), eq (gleich), neq (ungleich), contains (enthält), notcontains (nicht enthält), begins (beginnt mit), ends (endet mit), within (Listenwert enthalten), notwithin (Listenwert nicht enthalten)

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 Produkt-Daten.
400 Bad Request		Regeln konnten nicht geparst werden. Der Parameter `rules` ist kein gültiges JSON-Array, ein Eintrag enthält kein `mode`, `field` oder `value`, `value` ist kein String oder `mode` hat einen unbekannten Wert.
400 Bad Request	”syntaxError”	`sort` enthält mehr als einen oder keinen ”:“.
400 Bad Request	”unknownDataField”	Ein Sortierfeld ist ungültig.
400 Bad Request	”invalidValue”	`size` fehlt oder liegt nicht zwischen 1 und 1000.

POST products

Mit dem Endpunkt /products können neue Produkte im Shop-System angelegt werden. Alle für die Erstellung erforderlichen Produktinformationen müssen im Request Body übergeben werden. Die Antwort enthält die vollständigen Produktdaten des neu erstellten Produkts im JSON-Format. Wenn die übergebene Produkt-ID bereits vergeben ist, lehnt der Shop die Anfrage mit dem Status 409 Conflict ab. Ein vorhandenes Produkt wird dabei nicht überschrieben. Zum Erstellen eines Produkts sind entsprechende Berechtigungen erforderlich. Mit dem optionalen Parameter updateIndex=yes wird der Suchindex für das Produkt sofort aktualisiert. Ohne diesen Parameter übernimmt der nächste geplante Lauf die Aktualisierung.

Beispiel

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

Request Body

{
    "custom": {
        "liste": [],
        "map": {}
    },
    "active": "always",
    "descr": "This is a new Produkt",
    "itemNumber": "new",
    "name": "NewProdukt",
    "price": "1",
    "taxRateId": "19"
}

Der Preis darf wie im Beispiel als String übergeben werden. Sollen zugleich Aktionspreise gepflegt werden, ist die Objektform zu verwenden, die der Abschnitt Preisfelder in Requests beschreibt.

Antwort

{
    "active": "always",
    "custom": {
        "brand": "",
        "commission": {
            "source": "0.0",
            "parsedValue": 0
        },
        "commissionTaxRate": "",
        "crossSelling": [],
        "customNumber": "",
        "ean": "",
        "filterField": "",
        "image": [],
        "isbn": "",
        "liste": [],
        "map": {},
        ...
        "weight": {
            "source": "0.0",
            "parsedValue": 0
        }
    },
    "descr": "This is a new Produkt",
    "hasVariants": false,
    "id": "144-46864",
    "itemNumber": "new",
    "name": "NewProdukt",
    "price": {
        "price": "1.000000",
        "scheduledPrices": []
    },
    "taxRateId": "19",
    "timestampCreatedAt": "2025-05-09T14:57:36.000Z",
    "timestampUpdatedAt": "2025-05-09T14:57:36.000Z"
}

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 Produkten.
400 Bad Request		Der Request-Body konnte nicht geladen werden.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage oder ein ungültiger Subshop angegeben. 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	”invalidFormat”	`custom` ist kein Objekt.
400 Bad Request	”unknownDataField”	Ein nicht existierendes Produktdatenfeld wurde im Request-Body angegeben.
400 Bad Request	”notManualEditable”	Ein nicht bearbeitbares Produktdatenfeld wurde im Request-Body angegeben.
409 Conflict		Ein Produkt mit der übergebenen `id` existiert bereits.

Fehler in geplanten Aktionspreisen werden je Eintrag gemeldet. Die Schlüssel beschreibt der Abschnitt Validierung und Fehlerschlüssel. Verweist ein Eintrag im Feld set auf ein nicht existierendes Produkt, lehnt der Shop die Anfrage mit dem Statuscode 400 Bad Request und dem Typ “notFound” ab. Der Fehlerschlüssel lautet set[<i>].id, wobei <i> der Index des Eintrags im Array ist.

PUT products/{productId}

Mit dem Endpunkt products/{productId} können Produktdaten aktualisiert werden. Wird ein Produkt mit der angegebenen ID nicht gefunden, kann bei gesetztem Parameter createMissing=yes automatisch ein neues Produkt angelegt werden. Im Request-Body müssen nur die Felder angegeben werden, die geändert werden sollen. Felder, die nicht übermittelt werden, behalten ihren Wert. Mit dem Feld set werden die Mitglieder eines Set-Produkts als Ganzes ersetzt. Mit dem optionalen Parameter updateIndex=yes wird der Suchindex für das Produkt sofort aktualisiert. Das optionale Feld set kann benutzt werden, um andere Produkte zusammen mit dem Aktuellen einem Set zuzuweisen. Alternativ können die Endpunkte für Set-Produkte genutzt werden. Zum Bearbeiten oder Anlegen eines Produkts sind entsprechende Berechtigungen erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/11-1966

Request-Body

{
    "custom": {
        "brand": "",
        "commission": 0,
        "commissionTaxRate": "",
        "crossSelling": [],
        "customNumber": "",
        "ean": "",
        "filterField": "",
        "image": [],
        "isbn": "",
        "mainCategory": "",
        "metaDescription": "",
        "metaDescriptionSetManually": false,
        "metaTitle": "",
        "metaTitleSetManually": false,
        "multiProducts": "",
        "oneTimeFee": 0,
        "oneTimeFeeTaxRate": "",
        "productDiscount": 0,
        "productDiscountAbsolute": false,
        "productType": "",
        "robotsNoFollow": false,
        "robotsNoIndex": false,
        "validForDiscount": false,
        "video": "",
        "voucherProductActive": false,
        "voucherProductHtmlTemplate": "",
        "voucherProductPrice": false,
        "voucherProductTemplate": "",
        "weight": 0
    },
    "active": "always",
    "descr": "Jedes Stück, das von dem Strickunternehmen Kero Design kommt, ist ein echtes Unikat! Genau wie dieser Cardigan: Hier mischen sich zarte und kräftige Blautöne und ergeben ein effektvolles Strickkunstwerk. Diese handgestrickte Optik mit ihren schönen Farbverläufen erhält der Cardigan vor allem durch seine aufwendig von Hand gefärbten Garne. Reine Baumwolle macht die Strickjacke schön leicht und weich. Ein echter Blickfang und sehr besonders! Mit langen Ärmeln, Rundhals und Perlmutt-Knöpfen.<br /><span class='passform'> Gerade Form (Regular Fit).</span><span class='mass'> Länge ca. 60 cm.</span><span class='katalogfarbe'>Farbe: Multicolor Blue.</span><span class='herkunft'> Original Kero Design.</span>  <span class='material'>65 % Baumwolle (Bio-Baumwolle), 35 % Baumwolle.</span>",
    "itemNumber": "12-2144",
    "name": "Cardigan 'Amelia'",
    "price": {
        "price": "139.00",
        "scheduledPrices": [
            {
                "price": "119.00",
                "startDate": "2026-08-01T00:00:00.000Z",
                "endDate": "2026-08-31T23:59:59.000Z",
                "promotionInfo": "Sommeraktion",
                "validForDiscount": true
            }
        ]
    },
    "taxRateId": "1",
    "set": [
        {
            "id": "11-2497",
            "quantityFactor": 1,
            "usePrice": true,
            "fixQuantity": false,
            "hidden": false
        },
        {
            "id": "11-2492",
            "quantityFactor": 1,
            "usePrice": true,
            "fixQuantity": false,
            "hidden": false
        }
    ]
}

Antwort

{
    "active": "always",
    "custom": {
        "brand": "",
        "commission": 0,
        "commissionTaxRate": "",
        "crossSelling": [],
        "customNumber": "",
        "ean": "",
        "filterField": "",
        "image": [],
        "isbn": "",
        "mainCategory": "",
        "metaDescription": "",
        "metaDescriptionSetManually": false,
        "metaTitle": "",
        "metaTitleSetManually": false,
        "multiProducts": "",
        "oneTimeFee": 0,
        "oneTimeFeeTaxRate": "",
        "productDiscount": 0,
        "productDiscountAbsolute": false,
        "productType": "",
        "robotsNoFollow": false,
        "robotsNoIndex": false,
        "validForDiscount": false,
        "video": "",
        "voucherProductActive": false,
        "voucherProductHtmlTemplate": "",
        "voucherProductPrice": false,
        "voucherProductTemplate": "",
        "weight": 0
    },
    "descr": "Jedes Stück, das von dem Strickunternehmen Kero Design kommt, ist ein echtes Unikat! Genau wie dieser Cardigan: Hier mischen sich zarte und kräftige Blautöne und ergeben ein effektvolles Strickkunstwerk. Diese handgestrickte Optik mit ihren schönen Farbverläufen erhält der Cardigan vor allem durch seine aufwendig von Hand gefärbten Garne. Reine Baumwolle macht die Strickjacke schön leicht und weich. Ein echter Blickfang und sehr besonders! Mit langen Ärmeln, Rundhals und Perlmutt-Knöpfen.<br /><span class='passform'> Gerade Form (Regular Fit).</span><span class='mass'> Länge ca. 60 cm.</span><span class='katalogfarbe'>Farbe: Multicolor Blue.</span><span class='herkunft'> Original Kero Design.</span>  <span class='material'>65 % Baumwolle (Bio-Baumwolle), 35 % Baumwolle.</span>",
    "hasVariants": true,
    "id": "12-2144",
    "itemNumber": "12-2144",
    "name": "Cardigan 'Amelia'",
    "price": {
        "price": "139.000000",
        "scheduledPrices": [
            {
                "price": "119.000000",
                "startDate": "2026-08-01T00:00:00.000Z",
                "endDate": "2026-08-31T23:59:59.000Z",
                "promotionInfo": "Sommeraktion",
                "validForDiscount": true
            }
        ]
    },
    "taxRateId": "1",
    "timestampCreatedAt": "2025-02-14T10:54:45.000Z",
    "timestampUpdatedAt": "2025-05-10T16:19:36.000Z"
}

Die Antwort enthält keinen Set-Preis. Er wird nicht gespeichert, sondern bei Bedarf berechnet. Wie Sie ihn abrufen, beschreibt der Abschnitt POST products/setproducts/preview.

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 Produkten.
400 Bad Request		Der Request-Body konnte nicht geladen werden.
400 Bad Request	”invalidValue”	Die `productId` im Pfad ist ungültig. Es wurde eine ungültige Stage oder ein ungültiger Subshop angegeben. 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	”invalidFormat”	`custom` ist kein Objekt.
400 Bad Request	”unknownDataField”	Ein nicht existierendes Produktdatenfeld wurde im Request-Body angegeben.
400 Bad Request	”notManualEditable”	Ein nicht bearbeitbares Produktdatenfeld wurde im Request-Body angegeben.
400 Bad Request	”notFound”	Ein Eintrag im Feld `set` verweist auf ein Produkt, das nicht existiert. Der Fehlerschlüssel lautet `set[<i>].id`.
400 Bad Request	”protectedFieldWriteError”	Ein geschütztes Produktdatenfeld wurde im Request-Body angegeben und der Benutzer hat keine Berechtigung, dieses Feld zu ändern.
503 Service Unavailable	”internalError”	Das Produkt konnte nach mehreren Versuchen aufgrund von Versionskonflikten nicht gespeichert werden.
404 Not Found		Das Produkt mit `id={id}` wurde nicht gefunden und der Parameter `createMissing` ist nicht auf `yes` gesetzt.

DELETE products/{productId}

Mit dem Endpunkt products/{productId} kann ein Produkt mit der angegebenen ID dauerhaft gelöscht werden. Dieser Vorgang entfernt das Produkt vollständig mitsamt seiner Varianten vollständig aus dem System. Bestellungen, die das Produkt enthalten, behalten ihre Daten. Mit dem optionalen Parameter updateIndex=yes wird der Suchindex sofort aktualisiert. Zum Löschen eines Produkts sind entsprechende Berechtigungen erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/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 Löschen von Produkten.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben.
404 Not Found		Das Produkt mit `id={id}` existiert nicht.

Bulk-Methoden für Produkte

In diesem Abschnitt werden die Bulk-Endpunkte beschrieben, mit denen mehrere Datensätze in einem einzigen Request abgefragt oder verarbeitet werden können.

POST bulk/products

Ermöglicht das massenhafte Erstellen und Aktualisieren von Produktdaten in einem einzigen Request. Der Request-Body ist ein JSON-Array, in dem jedes Element ein Produkt mit ID beschreibt. Erstell- und Schreibrechte für Produkte sind erforderlich. Standardmäßig werden nur Produkte aktualisiert. Wenn der Parameter createMissing=yes gesetzt wird, werden Produkte, die noch nicht existieren, aus der Anfrage automatisch neu angelegt. In einem Request können maximal 1000 Einträge verarbeitet werden. Dieses Limit gilt für alle Bulk-Endpunkte der API gemeinsam. Weitere Informationen finden Sie in den API Basics: Bulk-Endpunkte. Fehler auf Zeilenebene brechen den Request nicht ab. Ungültige oder übersprungene Einträge erscheinen in der Antwort unter skippedLines mit lineNumber (ab 0 gezählt), productId, errorType (beispielsweise notFound oder invalidParameters) und fieldErrors. Unter items stehen die IDs der geschriebenen Produkte.

Beispiel

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

Request Body

[
    {
        "custom": {
            "liste": [],
            "map": {}
        },
        "id": "144-46864",
        "active": "always",
        "descr": "This is a new Produkt",
        "itemNumber": "new",
        "name": "NewProdukt",
        "price": "1",
        "taxRateId": "19"
    },
    {
        "custom": {
            "liste": [],
            "map": {}
        },
        "id": "145-26318",
        "active": "always",
        "descr": "This is an existing Produkt",
        "itemNumber": "existing",
        "name": "existingProduct",
        "price": "1",
        "taxRateId": "19"
    }
]

Antwort

{
    "items": ["145-26318"],
    "skippedLines": [{
        "lineNumber": 0,
        "productId": "144-46864",
        "errorType": "notFound",
        "fieldErrors": {}
    }]
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Erstellen oder aktualisieren von Produkten.
400 Bad Request		Der Request-Body konnte nicht geladen werden. Es wurden mehr als 1000 Einträge angegeben.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage oder ein ungültiger Subshop angegeben. 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	”invalidFormat”	`custom` ist kein Objekt.
400 Bad Request	”unknownDataField”	Ein nicht existierendes Produktdatenfeld wurde im Request-Body angegeben.
400 Bad Request	”notManualEditable”	Ein nicht bearbeitbares Produktdatenfeld wurde im Request-Body angegeben.

Methoden für Variantenattribute

Über die Endpunkte im Bereich products/variants/ können Sie die Variantenattribute und die dazugehörigen Optionen verwalten, die zur Bildung von Produktvarianten in Ihrem Shop verwendet werden. Sie können neue Attribut-Optionen hinzufügen, bestehende anpassen oder Attribute löschen. Ebenso können Sie die Reihenfolge der Optionen in der Anzeige ändern (siehe PUT products/variants/{attributeId}/positions) oder gezielt einzelne Optionen abfragen. Für alle hier dokumentierten Endpunkte ist eine gültige Authentifizierung erforderlich. Darüber hinaus benötigen Sie die Berechtigungen zum Lesen, Erstellen, Bearbeiten oder Löschen von Produktvarianten.

GET products/variants

Mit diesem Endpunkt kann eine Liste aller im Shop-System definierten Varianten-Attribute und deren verfügbaren Optionen abgerufen werden. Die Antwort gibt Aufschluss darüber, welche Attributnamen (beispielsweise „Größe“, „Farbe“) verwendet werden und welche Ausprägungen pro Attribut zur Verfügung stehen. Dies ist besonders hilfreich für das Anlegen oder Bearbeiten von Produktvarianten. Für diesen Endpunkt ist eine gültige Authentifizierung erforderlich. Sie müssen über die Berechtigung zum Lesen von Produktvarianten verfügen. Mit dem Parameter textSearch können Sie die Liste auf Attribute einschränken, deren Name oder Optionen den angegebenen Text enthalten.

Beispiel

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

Antwort

[
    {
        "name": "Größe",
        "options": [
            {
                "id": 1,
                "option": "L"
            },
            {
                "id": 2,
                "option": "XL"
            }
        ]
    },
    {
        "name": "Farbe",
        "options": [
            {
                "id": 4,
                "option": "Rot"
            },
            {
                "id": 3,
                "option": "Grün"
            }
        ]
    }
]

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 Produktvarianten.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben.

GET products/variants/{id}

Mit diesem Endpunkt kann entweder ein Varianten-Attribut mit seinen zugehörigen Optionen oder eine einzelne Variante-Option abgerufen werden. Wird in der URL ein Attributname (beispielsweise „Farbe“) übergeben, liefert die Antwort alle Optionen zu diesem Attribut. Wird hingegen eine Options-ID übergeben, muss zusätzlich der Parameter singleOption=yes gesetzt werden, um die Daten zu einer konkreten Variante-Option abzurufen. Die Suche nach dem Attributnamen erfolgt unabhängig von der Groß-/Kleinschreibung. Um diesen Endpunkt nutzen zu können, ist eine gültige Authentifizierung erforderlich. Sie benötigen außerdem die Berechtigung, Produktvarianten lesen zu dürfen.

Beispiel (Attribut)

https://www.<ihr-shop>.de/admin/api/v1/products/variants/Farbe

Antwort (Attribut)

{
    "name": "Farbe",
    "options": [
        {
            "id": 4,
            "option": "Rot"
        },
        {
            "id": 3,
            "option": "Grün"
        }
    ]
}

Beispiel (Option)

https://www.<ihr-shop>.de/admin/api/v1/products/variants/4?singleOption=yes

Antwort (Option)

{
    "id": 4,
    "attribute": "Farbe",
    "option": "Rot"
}

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 Produktvarianten.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben. Die übergebene `id` ist keine positive Ganzzahl (bei `singleOption=yes`).
404 Not Found		Die Option oder das Attribute wurde nicht gefunden.

POST products/variants

Mit diesem Endpunkt wird ein neues Varianten-Attribut mit beliebigen Optionswerten erstellt. Sollte das Attribut bereits existieren (Groß-/Kleinschreibung wird nicht berücksichtigt), wird es um die neuen, bislang nicht vorhandenen Optionen ergänzt. Ist eine der angegebenen Optionen für das Attribut bereits vorhanden, wird der Vorgang mit einem Konfliktfehler (409) abgebrochen. Um diesen Endpunkt nutzen zu können, ist eine gültige Authentifizierung erforderlich. Sie benötigen außerdem die Berechtigung zum Erstellen von Produktvarianten.

Beispiel

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

Request-Body

{
    "attribute": "color",
    "options": [
        "red",
        "blue",
        "white"
    ]
}

Antwort

{
    "attribute": "color",
    "options": [
        {
            "id": 23,
            "option": "red"
        },
        {
            "id": 24,
            "option": "blue"
        },
        {
            "id": 25,
            "option": "white"
        }
    ]
}

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 Produktvarianten.
400 Bad Request		Der Request-Body konnte nicht geladen werden.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben. `attribute` oder `options` sind leer. Die Länge von `attribute` oder von einzelnen Optionen ist gleich 0 oder größer als 128 Zeichen.
400 Bad Request	”missing”	Parameter `attribute` oder `options` fehlen.
400 Bad Request	”invalidFormat”	`attribute` ist kein String. `options` ist kein Array.
400 Bad Request	”unknownDataField”	Ein unbekanntes Feld wurde im Request-Body angegeben.
409 Conflict	”variantAlreadyExists”	Ein Attribut mit der angegebenen Option existiert bereits.

PUT products/variants/{attributeId}

Mit diesem Endpunkt wird ein bestehendes Varianten-Attribut aktualisiert. Die Suche nach dem Attributnamen erfolgt unabhängig von der Groß-/Kleinschreibung. Es können neue Optionen hinzugefügt und bestehende bearbeitet werden. Eine Option mit id wird umbenannt, eine Option ohne id wird neu angelegt und hinter den vorhandenen Optionen eingeordnet. Die Umbenennung wird auf alle Produkte übertragen, die die Option verwenden. Das Umbenennen des Attributs ist über das optionale Feld newAttributeName im Request-Body möglich. Bereits existierende Optionen, die im Request-Body nicht enthalten sind, bleiben unverändert bestehen und behalten ihre Position. Mit dem Query-Parameter complete=true geben Sie an, dass options die vollständige Liste aller Optionen des Attributs ist. Dann gilt zusätzlich:

Optionen, die im Request fehlen, werden entfernt.
Alle Optionen werden in der Reihenfolge des Requests eingeordnet.
Wird eine zu entfernende Option noch von einem Produkt verwendet, lehnt der Shop den gesamten Request ab, ohne etwas zu ändern. Die Antwort nennt die betroffenen Produkte.

Um nur die Reihenfolge zu ändern, verwenden Sie PUT products/variants/{attributeId}/positions. Für die Nutzung dieses Endpunkts ist eine gültige Authentifizierung erforderlich. Sie benötigen außerdem die Berechtigung zum Schreiben von Produktvarianten. Mit complete=true ist zusätzlich die Berechtigung zum Löschen von Produktvarianten nötig, weil dabei Optionen entfernt werden können.

Query-Parameter

Parameter	Beschreibung
`complete`	`true`, wenn `options` alle Optionen des Attributs enthält. Fehlende Optionen werden dann entfernt und alle Optionen in der Reihenfolge des Requests eingeordnet. Default: `false`

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/variants/color

Request-Body

{
    "options": [
        {
            "option": "blueUpd",
            "id": 24
        },
        {
            "id": 23,
            "option": "red"
        },
        {
            "id": 25,
            "option": "white"
        },
        {
            "option": "newColor"
        }
    ],
    "newAttributeName": "colorUpd"
}

Antwort

{
    "attribute": "colorUpd"
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Bearbeiten von Produktvarianten. Mit `complete=true` fehlt zusätzlich die Berechtigung zum Löschen von Produktvarianten.
400 Bad Request		Der Request-Body konnte nicht geladen werden.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben. `options` ist kein Array. Die Länge von `newAttributeName` oder von einzelnen Optionen ist gleich 0 oder größer als 128 Zeichen. Eine `id` in `options` gehört nicht zu diesem Attribut. `complete=true` ist gesetzt, und `options` ist leer.
400 Bad Request	”duplicateEntry”	Dieselbe `id` steht mehrfach in `options`.
400 Bad Request	”missing”	`attributeId` fehlt.
404 Not Found		Das Attribut wurde nicht gefunden.
409 Conflict	”variantInUse”	Mit `complete=true`: Eine Option, die entfernt würde, wird noch von einem Produkt verwendet. Die Antwort nennt die betroffenen Produkte. Es wurde nichts geändert.
503 Internal Error	”internalError”	Das Aktualisieren ist fehlgeschlagen.

PUT products/variants/{attributeId}/positions

Mit diesem Endpunkt legen Sie die Reihenfolge fest, in der die Optionen eines Varianten-Attributs angeboten werden. Die Optionen werden in der Reihenfolge des Requests eingeordnet. Optionen, die im Request fehlen, folgen danach in ihrer bisherigen Reihenfolge. Namen und Optionen selbst ändern sich nicht. Die Suche nach dem Attributnamen erfolgt unabhängig von der Groß-/Kleinschreibung. Jede Option geben Sie über ihre id oder ihren Namen in option an. Ist beides angegeben, gilt die id. Für die Nutzung dieses Endpunkts ist eine gültige Authentifizierung erforderlich. Sie benötigen außerdem die Berechtigung zum Schreiben von Produktvarianten.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/variants/Farbe/positions

Request-Body

{
    "options": [
        {
            "id": 3
        },
        {
            "option": "Rot"
        }
    ]
}

Antwort

Die Antwort enthält das Attribut mit allen Optionen in der neuen Reihenfolge.

{
    "name": "Farbe",
    "options": [
        {
            "id": 3,
            "option": "Grün"
        },
        {
            "id": 4,
            "option": "Rot"
        }
    ]
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Bearbeiten von Produktvarianten.
400 Bad Request		Der Request-Body konnte nicht geladen werden.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben. `options` fehlt oder ist leer. Ein Eintrag in `options` ist kein Objekt oder nennt keine Option dieses Attributs.
400 Bad Request	”missing”	`attributeId` fehlt.
404 Not Found		Das Attribut wurde nicht gefunden.
503 Internal Error	”internalError”	Das Speichern der Reihenfolge ist fehlgeschlagen. Die bisherige Reihenfolge bleibt dann vollständig erhalten.

DELETE products/variants/{id}

Mit diesem Endpunkt können Sie entweder ein Varianten-Attribut samt aller zugehörigen Optionen oder eine einzelne Option löschen. Wird das Attribut derzeit noch von einem Produkt verwendet, wird der Vorgang mit einem Konfliktfehler abgebrochen. Um diesen Endpunkt nutzen zu können, ist eine gültige Authentifizierung erforderlich. Sie benötigen außerdem die Berechtigung, Produktvarianten zu löschen. Wird in der URL ein Attributname übergeben, werden das Attribut und alle zugehörigen Optionen gelöscht. Die Suche nach dem Attributnamen erfolgt unabhängig von der Groß-/Kleinschreibung. Wird hingegen eine Options-ID übergeben, muss zusätzlich der Parameter singleOption=yes gesetzt werden, um nur diese einzelne Option zu löschen.

Beispiel (Attribut)

https://www.<ihr-shop>.de/admin/api/v1/products/variants/color

Antwort (Attribut)

{
    "success": true
}

Beispiel (Option)

https://www.<ihr-shop>.de/admin/api/v1/products/variants/4?singleOption=yes

Antwort (Option)

{
    "id": 4,
    "attribute": "Farbe",
    "option": "Rot"
}

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 Produktvarianten.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben. Die übergebene `id` ist keine positive Ganzzahl (bei `singleOption=yes`).
404 Not Found		Die Option oder das Attribut wurden nicht gefunden.
409 Conflict	”variantInUse”	Dieses Varianten-Attribut wird von einer Produktvariante verwendet.

Methoden für Produktvarianten

Mithilfe der folgenden Endpunkte können Produktvarianten innerhalb eines bestehenden Produkts verwaltet werden. Varianten stellen spezifische Ausprägungen eines Produkts dar, beispielsweise Größen oder Farben, und basieren auf den zuvor definierten Variantenattributen. Über die API können Varianten einzeln abgerufen, erstellt, aktualisiert oder gelöscht werden. Zusätzlich lassen sich die Variantenattribute eines Produkts abrufen, festlegen und in ihrer Reihenfolge verschieben. Die meisten Endpunkte in diesem Abschnitt prüfen die Lese-, Erstellungs- oder Schreibberechtigungen für Produktvarianten. Drei Endpunkte benötigen dagegen Berechtigungen für Produkte. Das Löschen einer Variante erfordert die Löschberechtigung für Produkte, das Abrufen der Variantenattribute die Leseberechtigung und das Verschieben eines Variantenattributs die Schreibberechtigung. Auch Varianten tragen ihren Preis als Objekt. Setzt eine Variante ein eigenes Preisfeld, ersetzt dieses den Standardpreis und den Zeitplan des Basisprodukts gemeinsam. Eine Variante mit eigenem Preis und ohne Aktionspreise erbt die Aktion des Basisprodukts also nicht. Setzt eine Variante kein eigenes Preisfeld, liefert die Antwort für dieses Feld null und nicht den Wert des Basisprodukts. Anbindungen müssen diesen Fall abfangen, der Typ ist object | null.

GET products/{productId}/variants

Mit diesem Endpunkt kann eine Liste aller Varianten für das angegebene Produkt geladen werden. Varianten sind Produktversionen, die sich durch unterschiedliche Attributkombinationen (beispielsweise Größe oder Farbe) vom Hauptprodukt unterscheiden. Die Antwort enthält grundlegende Produktdaten sowie die zugehörigen Attributwerte unter selection. Um diesen Endpunkt nutzen zu können, sind entsprechende Berechtigungen zum Lesen von Produktvarianten erforderlich. Die Antwort ist seitenweise aufgebaut. Mit size legen Sie fest, wie viele Varianten eine Seite enthält (Standardwert 10). Die nächste Seite rufen Sie mit dem unverändert übernommenen Parameter pageToken aus nextPageToken der vorherigen Antwort auf. Mit dem Parameter textSearch können Sie die Liste auf Varianten einschränken, deren Name, Beschreibung oder Attributwerte den angegebenen Text enthalten.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/11-1701/variants

Antwort

{
    "endReached": true,
    "items": [
        {
            "active": "always",
            "custom": {
                "weight": 0.33
            },
            "descr": null,
            "id": "8310",
            "itemNumber": "11-1701-M",
            "name": null,
            "price": {
                "price": "89.900000",
                "scheduledPrices": []
            },
            "selection": {
                "Größe": "M"
            },
            "taxRateId": null
        },
        ...
    ],
    "nextPageToken": "MTAw",
    "totalCount": 6
}

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 Produktvarianten.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben.
404 Not Found		Das Produkt mit `id={productId}` wurde nicht gefunden.

GET products/{productId}/variants/{variantId}

Mit diesem Endpunkt kann eine bestimmte Produktvariante anhand ihrer ID innerhalb eines Produkts geladen werden. Die Produkt-ID wird als Teil der URL übergeben, ebenso die Varianten-ID. Die Antwort enthält die zugehörigen Variantendaten inklusive Preis, Artikelnummer, Auswahlattribute (selection) und weiterer Detailinformationen. Für die Nutzung dieses Endpunkts sind entsprechende Berechtigungen zum Lesen von Produktvarianten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/11-1701/variants/8310

Antwort

{
    "active": "always",
    "custom": {
        "weight": 0.33
    },
    "descr": null,
    "id": "8310",
    "itemNumber": "11-1701-M",
    "name": null,
    "price": {
        "price": "89.900000",
        "scheduledPrices": []
    },
    "selection": {
        "Größe": "M"
    },
    "taxRateId": null
}

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 Produktvarianten.
400 Bad Request	”invalidValue”	`id` ist ungültig. Es wurde eine ungültige Stage angegeben.
404 Not Found		Produkt mit `id`=`{productId}` wurde nicht gefunden. Produktvariante mit `id={variantId}` wurde nicht gefunden.

PUT products/{productId}/variants/{variantId}

Über diesen Endpunkt können die Daten einer bestimmten Produktvariante mithilfe ihrer Produkt-ID und Varianten-ID aktualisiert werden. Die Variante wird über die angegebenen IDs identifiziert. Felder, die nicht im Request-Body angegeben sind, behalten ihren Wert. Die Attributkombination (selection) darf nicht im Request-Body stehen und lässt sich nicht ändern. Für die Nutzung dieses Endpunkts sind Schreibrechte für Produktvarianten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/11-1701/variants/8310

Request-Body

{
    "active": "always",
    "custom": {
        "weight": 0.33
    },
    "descr": null,
    "id": "8310",
    "itemNumber": "11-1701-M",
    "name": null,
    "price": "89.900000",
    "set": [],
    "taxRateId": null
}

Antwort

{
    "active": "always",
    "custom": {
        "weight": 0.33
    },
    "descr": null,
    "id": "8310",
    "itemNumber": "11-1701-M",
    "name": null,
    "price": {
        "price": "89.900000",
        "scheduledPrices": []
    },
    "selection": {
        "Größe": "M"
    },
    "taxRateId": null
}

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 Produktvarianten.
400 Bad Request		Der Request-Body konnte nicht geladen werden
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben oder ein ungültiger Subshop angegeben. `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”	Ein nicht existierendes Produktdatenfeld wurde im Request-Body angegeben, beispielsweise `selection`.
400 Bad Request	”notFound”	Ein Eintrag im Feld `set` verweist auf ein Produkt, das nicht existiert. Der Fehlerschlüssel lautet `set[<i>].id`.
404 Not Found		Produkt mit `id`=`{productId}` wurde nicht gefunden Produktvariante mit `id={variantId}` wurde nicht gefunden.
400 Bad Request	”invalidFormat”	`custom` ist kein Objekt.
503 Service Unavailable	”internalError”	Das Produkt konnte nach mehreren Versuchen aufgrund von Versionskonflikten nicht gespeichert werden.

GET products/{productId}/variantAttributes

Über diesen Endpunkt können die Variantenattribute eines Produkts in der Reihenfolge abgerufen werden, in der sie angeboten werden. Jeder Eintrag enthält den Namen des Attributs (name) und seine Position (position, ab 0 gezählt). Die Antwort ist nicht seitenweise aufgebaut und endReached ist immer true. Für die Nutzung dieses Endpunkts sind Leseberechtigungen für Produkte erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/11-1701/variantAttributes

Antwort

{
    "endReached": true,
    "items": [
        {
            "name": "größe",
            "position": 0
        },
        {
            "name": "farbe",
            "position": 1
        }
    ],
    "nextPageToken": "",
    "searchAfterToken": "",
    "totalCount": 2
}

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”	Es wurde eine ungültige Stage angegeben.
404 Not Found		Das Produkt mit `id`=`{productId}` wurde nicht gefunden.

POST products/{productId}/variantAttributes

Über diesen Endpunkt wird die Liste der Variantenattribute eines Produkts festgelegt, anhand derer sich dessen Varianten unterscheiden. Jedes übergebene Attribut muss im Shop mit mindestens einer Option existieren (siehe POST products/variants). Der Endpunkt erzeugt selbst keine Varianten. Konkrete Varianten werden über den Endpunkt POST products/{productId}/variants/manage angelegt. Wenn das Produkt bereits Variantenattribute hat und Attribute ergänzt oder entfernt werden, bricht der Vorgang standardmäßig mit einem 400-Fehler vom Typ conflict ab. Der Grund dafür ist, dass dabei alle bestehenden Varianten wegfallen würden. Um diesen Abbruch zu umgehen, kann der optionale Parameter force=yes verwendet werden. In diesem Fall werden alle bisherigen Varianten des Produkts gelöscht und die Optionen der Attribute am Produkt zurückgesetzt. Wenn das Produkt noch keine Variantenattribute hatte, werden die Attribute ohne Konflikt gesetzt. Für die Nutzung dieses Endpunkts sind Erstellberechtigungen für Produktvarianten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/11-1701/variantAttributes

Request-Body

{
    "attributes": [ "größe", "farbe" ]
}

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 Erstellen von Produktvarianten.
400 Bad Request		Der Request-Body konnte nicht geladen werden.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben. Ein angegebenes Attribut existiert nicht.
400 Bad Request	”missing”	`attributes` fehlt im Request-Body.
400 Bad Request	”invalidFormat”	`attributes` ist kein Array. Ein Element in `attributes` ist kein String.
400 Bad Request	”unknownDataField”	Ein unbekanntes Feld wurde im Request-Body angegeben.
400 Bad Request	”conflict”	Die Variantenattribute des Produkts haben sich geändert. Bestehende Varianten würden gelöscht. Verwenden Sie `force=yes`, um den Vorgang trotzdem durchzuführen.
404 Not Found		Das Produkt mit `id`=`{productId}` wurde nicht gefunden.
503 Service Unavailable	”internalError”	Das Produkt konnte nicht aktualisiert werden.

POST products/{productId}/variantAttributes/move

Mithilfe dieses Endpunkts kann ein Variantenattribut eines Produkts an eine neue Position verschoben werden. Die Position legt die Reihenfolge fest, in der die Attribute angeboten werden. Das Produkt muss mindestens zwei Variantenattribute besitzen. Für die Nutzung dieses Endpunkts sind Schreibberechtigungen für Produkte erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/11-1701/variantAttributes/move

Request-Body

{
    "attribute": "farbe",
    "position": 0
}

position wird ab 0 gezählt und muss kleiner sein als die Anzahl der Variantenattribute des Produkts.

Antwort

{}

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 Produkten.
400 Bad Request		Das Produkt hat weniger als zwei Variantenattribute. Der Request-Body konnte nicht geladen werden.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben. `attribute` ist am Produkt nicht vorhanden. `position` ist nicht kleiner als die Anzahl der Variantenattribute.
400 Bad Request	”missing”	`attribute` oder `position` fehlt im Request-Body.
400 Bad Request	”invalidFormat”	`attribute` ist kein String. `position` ist keine nicht negative Ganzzahl.
400 Bad Request	”unknownDataField”	Ein unbekanntes Feld wurde im Request-Body angegeben.
404 Not Found		Das Produkt mit `id`=`{productId}` wurde nicht gefunden.
503 Service Unavailable	”internalError”	Das Attribut konnte nicht verschoben oder das Produkt nicht gespeichert werden.

POST products/{productId}/variants/manage

Dieser Endpunkt ermöglicht es, gezielt bestimmte Varianten-Kombinationen für ein bestehendes Produkt anzulegen. Die Variantenattribute des Produkts müssen zuvor über die API unter POST products/{productId}/variantAttributes festgelegt werden. Es werden nur die explizit übermittelten Kombinationen erzeugt. Bereits existierende Kombinationen werden übersprungen und erscheinen nicht in der Antwort. Optional kann je Eintrag eine id für die neue Variante übergeben werden. Fehlt diese, vergibt der Shop eine ID. Der Endpunkt eignet sich besonders, wenn nicht alle theoretisch möglichen Kombinationen eines Produkts benötigt werden, sondern nur eine gezielte Auswahl. Für die Nutzung sind Erstellberechtigungen für Produktvarianten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/11-1701/variants/manage

Request-Body

{
    "selections": [
        {
            "größe": "M",
            "farbe": "rot"
        },
        {
            "id": "443",
            "größe": "L",
            "farbe": "blau"
        },
        ...
    ]
}

Antwort

{
    "items": [
        {
            "id": "42",
            "selection": {
                "größe": "M",
                "farbe": "rot"
            }
        },
        {
            "id": "443",
            "selection": {
                "größe": "L",
                "farbe": "blau"
            }
        },
        ...
    ]
}

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 Produktvarianten.
400 Bad Request		Der Request-Body konnte nicht geladen werden
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben. `selections` beinhaltet ungültige Attribut oder Attributwerte.
400 Bad Request	”duplicateEntry”	Die Variante konnte nicht angelegt werden, beispielsweise weil die übergebene `id` bei diesem Produkt bereits vergeben ist. Der Fehlerschlüssel lautet `selection`.
400 Bad Request	”missing”	`selections` fehlt im Request-Body.
400 Bad Request	”invalidFormat”	`selections` ist kein Array. Ein Element in `selections` ist kein JSON-Objekt. Ein Attributwert ist kein String.
400 Bad Request	”unknownDataField”	Ein unbekanntes Feld wurde im Request-Body angegeben.
404 Not Found		Produkt mit `id`=`{productId}` wurde nicht gefunden
409 Conflict	”versionConflict”	Das Produkt wurde während des Generierens der Varianten verändert.

DELETE products/{productId}/variants/{variantId}

Mit diesem Endpunkt kann eine bestehende Produktvariante anhand von Produkt-ID und Varianten-ID gelöscht werden. Dies ist etwa dann sinnvoll, wenn bestimmte Kombinationen von Varianten (beispielsweise Größe und Farbe) nicht mehr angeboten werden sollen. Sowohl das übergeordnete Produkt als auch die Variante müssen existieren. Andernfalls wird ein entsprechender Fehler zurückgegeben. Für die Nutzung sind Löschberechtigungen für Produkte erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/11-1701/variants/1

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 Produkten.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben.
404 Not Found		Produkt mit `id`=`{productId}` wurde nicht gefunden Produktvariante mit `id={variantId}` wurde nicht gefunden

Bulk-Methoden für Varianten

In diesem Abschnitt werden die Bulk-Endpunkte beschrieben, mit denen mehrere Datensätze in einem einzigen Request abgefragt oder verarbeitet werden können.

POST bulk/products/variants

Ermöglicht das massenhafte Erstellen und Aktualisieren von Produktvarianten in einem einzigen Request. Der Request-Body ist ein JSON-Array, in dem jedes Element eine Produktvariante beschreibt. Erstell- und Schreibrechte für Produktvarianten sind erforderlich. Für jeden Eintrag wird die jeweilige Produktvariante über die Felder productId, variantId und selection identifiziert. Zum Aktualisieren einer Variante genügt productId in Kombination mit selection oder variantId. Beim Anlegen einer neuen Variante ist selection verpflichtend. Wird zusätzlich variantId mitgegeben, wird die neue Variante mit dieser ID erstellt. Standardmäßig werden nur Produktvarianten aktualisiert. Wenn der Parameter createMissing=yes gesetzt wird, werden Produktvarianten, die noch nicht existieren, aus der Anfrage automatisch neu angelegt. Mit dem Parameter updateIndex=yes wird der Suchindex sofort aktualisiert. In einem Request können maximal 1000 Einträge verarbeitet werden. Dieses Limit gilt gemeinsam für alle Bulk-Endpunkte der API. Details stehen in den API Basics: Bulk-Endpunkte.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/bulk/products/variants

Request Body

[
    {
        "custom": {
            "liste": [],
            "map": {}
        },
        "productId": "144-46864",
        "selection": {
            "größe": "M",
            "farbe": "rot"
        },
        "active": "always",
        "descr": "This is a new Variant",
        "name": "NewVariant"
    },
    {
        "custom": {
            "liste": [],
            "map": {}
        },
        "productId": "144-46864",
        "selection": {
            "größe": "L",
            "farbe": "blau"
        },
        "active": "always",
        "descr": "This is an existing Variant",
        "name": "existingVariant"
    }
]

Antwort

{
    "items": [{"lineNumber": 1, "productId": "144-46864", "variantId": "43"}],
    "skippedLines": [{
        "lineNumber": 0,
        "productId": "144-46864",
        "errorType": "notFound",
        "fieldErrors": {}
    }]
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Erstellen oder aktualisieren von Produkten.
400 Bad Request		Der Request-Body konnte nicht geladen werden. Es wurden mehr als 1000 Einträge angegeben.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage oder ein ungültiger Subshop angegeben. 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	”invalidCombination”	Es wurden `variantId` und `selection` angegeben, jedoch passt die `variantId` nicht zur über `selection` identifizierten Variante.
400 Bad Request	”invalidFormat”	`custom` ist kein Objekt.
400 Bad Request	”unknownDataField”	Ein nicht existierendes Produktdatenfeld wurde im Request-Body angegeben.
400 Bad Request	”notManualEditable”	Ein nicht bearbeitbares Produktdatenfeld wurde im Request-Body angegeben.

Methoden für Lagerbestand Allgemein

Die folgenden Endpunkte ermöglichen das Abrufen, Erstellen, Aktualisieren und Löschen von Lagerbeständen im System. Jeder Lagerbestand wird durch eine eindeutige inventoryId identifiziert. Abhängig vom Endpunkt können Lagerbestände direkt gesetzt oder relativ verändert werden, beispielsweise beim Buchen von Zu- oder Abgängen. Für alle hier dokumentierten Endpunkte ist eine entsprechende Berechtigung für den Zugriff auf Lagerbestände erforderlich. Alle Endpunkte in diesem Abschnitt unterstützen den optionalen URL-Parameter storageId, mit dem die Lager-ID explizit angegeben werden kann. Wird dieser Parameter nicht gesetzt, wird automatisch die Lager-ID des aktiven Subshops verwendet.

Woher kommt die `inventoryId`?

Die inventoryId ist der Schlüssel des Lagerbestands-Eintrags. Beim Anlegen eines Produkts bzw. einer Variante legt das System automatisch einen Bestands-Eintrag mit einem Standardschlüssel an:

Objekt	Standard-`inventoryId`	Beispiel
Produkt ohne Varianten	die Produkt-ID	`11-1701`
Produktvariante	`{productId}.{variantId}`, also Produkt-ID und Varianten-ID, getrennt durch einen Punkt	`11-1701.M`

Sie müssen die inventoryId also nicht separat abfragen, sondern können sie für den Standardfall aus Produkt- und Varianten-ID zusammensetzen.

Der Standardschlüssel ist lediglich der Ausgangswert und stellt keine Garantie dar. Die inventoryId eines Produkts kann überschrieben werden. Genau dafür ist sie da: Mehrere Produkte oder Varianten können sich denselben Lagerbestand teilen, indem sie auf dieselbe inventoryId verweisen. Welche inventoryId einem Produkt tatsächlich zugeordnet ist, lesen Sie über die Methode GET products/{productId}/inventory im Feld storeId. Verlassen Sie sich bei Integrationen, die auf gepflegten Shops arbeiten, nicht blind auf das Standardschema.

Aus demselben Grund weichen die Beispiele in diesem Abschnitt (beispielsweise 11-1701 M) vom Standardschema ab. Sie zeigen einen Shop, in dem eigene Bestandsschlüssel gepflegt wurden.

GET products/inventory/{inventoryId}

Mit diesem Endpunkt kann der Lagerbestand eines Produkts oder einer Produktvariante anhand der Lagerbestands-ID (inventoryId) abgerufen werden. Die Antwort enthält Informationen über den aktuellen Bestand, offene Bestellungen sowie den Zeitpunkt der letzten Aktualisierung. Damit der Endpunkt genutzt werden kann, müssen die entsprechenden Berechtigungen zum Lesen von Lagerbeständen vorhanden sein.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/inventory/11-1701%20M

Antwort

{
    "amount": 10.0,
    "id": "100-21456",
    "openOrder": 0.0,
    "setAt": "2024-08-19T08:03:26.000Z",
    "updatedAt": "2024-08-19T08:03:26.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 Lagerbeständen.
404 Not Found		Es wurde kein Lagerbestand mit `id={inventoryId}` im aktuellen Subshop gefunden.

POST products/inventory

Mit diesem Endpunkt wird ein neuer Lagerbestand für ein Produkt oder eine Produktvariante angelegt. Dabei wird eine eindeutige Lagerbestands-ID (id) sowie die verfügbaren und offenen Mengen angegeben. Damit dieser Endpunkt verwendet werden kann, müssen die entsprechenden Berechtigungen zum Erstellen von Lagerbeständen vorhanden sein.

Beispiel

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

Request-Body

{
    "id": "11-1701 M",
    "amount": 10.0,
    "openOrder": 0.0
}

Antwort

{
    "amount": 10.0,
    "id": "11-1701 M",
    "openOrder": 0.0,
    "setAt": "2025-05-01T10:12:00.000Z",
    "updatedAt": "2025-05-01T10:12:00.000Z"
}

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 Lagerbeständen.
400 Bad Request		Der Request-Body konnte nicht geladen werden
400 Bad Request	”missing”	Das Pflichtfeld `id` fehlt im Request-Body
400 Bad Request	”invalidValue”	Das Feld `id` darf nicht leer sein
400 Bad Request	”invalidFormat”	Ein Feldwert hat einen falschen Datentyp, beispielsweise Number statt String für `id`
400 Bad Request	”unknownDataField”	Der Request-Body enthält ein unbekanntes Feld
400 Bad Request	”duplicateEntry”	Ein Lagerbestand mit der angegebenen `id` existiert bereits

PUT products/inventory/{inventoryId}

Mit diesem Endpunkt aktualisieren Sie den Lagerbestand eines bestimmten Produkts anhand der übergebenen Parameter. Dabei können Sie sowohl den Bestand (amount) als auch die Anzahl der offenen Bestellungen (openOrder) anpassen, entweder absolut oder relativ:

Ist amountType auf relative gesetzt, wird der aktuelle Lagerbestand um den angegebenen amount erhöht. Bei einem negativen Wert wird er verringert. Andernfalls wird der Lagerbestand auf den Wert von amount gesetzt.
Entsprechend funktioniert openOrderType. Ist dieser auf relative gesetzt, wird die Anzahl der offenen Bestellungen um openOrder erhöht oder bei negativem Wert verringert. Ohne relative wird openOrder direkt gesetzt.

Existiert noch kein Lagerbestand für die angegebene {inventoryId}, kann über den optionalen URL-Parameter createMissing=yes automatisch ein neuer Eintrag angelegt werden. Um diesen Endpunkt verwenden zu können, benötigen Sie die Berechtigung zum Schreiben von Lagerbeständen.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/inventory/11-1701%20M

Request-Body

{
    "amount": 10.0,
    "amountType": "absolute",
    "openOrder": -1.0,
    "openOrderType": "relative"
}

Antwort

{
    "amount": 10.0,
    "id": "11-1701 M",
    "openOrder": 4.0,
    "setAt": "2025-05-01T14:22:30.000Z",
    "updatedAt": "2025-05-01T14:22:30.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 Lagerbeständen.
400 Bad Request		Der Request-Body konnte nicht geladen werden
400 Bad Request	”invalidFormat”	`amount` oder `openOrder` ist kein gültiger Number-Typ
404 Not Found		Es wurde kein Lagerbestand mit `id={inventoryId}` im aktuellen Subshop gefunden und `createMissing` ist nicht `yes`

DELETE products/inventory/{inventoryId}

Mit diesem Endpunkt löschen Sie den Lagerbestand eines Produkts für die angegebene {inventoryId} im aktuellen Subshop. Wenn kein entsprechender Eintrag existiert, wird ein Fehler zurückgegeben. Um diesen Endpunkt verwenden zu können, benötigen Sie die Berechtigung zum Löschen von Lagerbeständen.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/inventory/1

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 Lagerbeständen.
404 Not Found		Es wurde kein Lagerbestand mit `id={inventoryId}` im aktuellen Subshop gefunden

POST bulk/products/inventory

Mit diesem Endpunkt legen Sie mehrere Lagerbestände in einem Request an oder aktualisieren sie (Upsert). Jeder Eintrag im Request-Body wird über seine id (Lagerbestands-ID, siehe Woher kommt die inventoryId?) adressiert. Für jeden Eintrag können Sie den Bestand (amount) und die Anzahl der offenen Bestellungen (openOrder) absolut oder relativ anpassen:

Ist amountType auf relative gesetzt, wird der aktuelle Lagerbestand um den angegebenen amount erhöht. Bei einem negativen Wert wird er verringert. Andernfalls wird der Lagerbestand auf den Wert von amount gesetzt.
Entsprechend funktioniert openOrderType. Ist dieser auf relative gesetzt, wird die Anzahl der offenen Bestellungen um openOrder erhöht oder bei negativem Wert verringert. Ohne relative wird openOrder direkt gesetzt.
Existiert für eine id noch kein Lagerbestand, wird er standardmäßig angelegt, sofern ein Produkt oder eine Variante des Subshops auf diese inventoryId verweist. Mit createMissing=no werden nur bestehende Einträge aktualisiert.

Um diesen Endpunkt verwenden zu können, benötigen Sie die Berechtigung zum Schreiben von Lagerbeständen.

Der Endpunkt erwartet POST, auch wenn bestehende Bestände aktualisiert werden. Das gilt für alle Bulk-Endpunkte. Ein PUT auf bulk/products/inventory wird nicht beantwortet. Der Request läuft ins Leere, ohne dass sich die Bestände ändern.

Geändertes Standardverhalten. Bisher wurden fehlende Lagerbestände nur mit createMissing=yes angelegt. Jetzt ist das Anlegen der Standard. Anbindungen, die ohne createMissing aufrufen und sich darauf verlassen, dass unbekannte IDs nicht angelegt werden, müssen createMissing=no mitsenden.

In einem Request können maximal 1000 Einträge verarbeitet werden. Dieses Limit gilt gemeinsam für alle Bulk-Endpunkte der API. Weitere Informationen finden Sie in den API Basics: Bulk-Endpunkte. Bei mehr Einträgen wird der gesamte Request abgelehnt und nichts geschrieben.

URL-Parameter

Parameter	Werte	Standard	Beschreibung
`subshopId`	Subshop-ID	Header `X-SubshopId`, sonst erster Subshop	Bestimmt den Subshop und damit das Standard-Lager.
`storageId`	Lager-ID	Lager des Subshops	Schreibt in ein anderes Lager als das Standard-Lager des Subshops.
`stage`	`work`, `active`	`work`	Content-Stage. Wird für die Referenzprüfung und die Back-in-Stock-Benachrichtigungen verwendet.
`createMissing`	`yes`, `no`	`yes`	Mit `no` werden nur bestehende Einträge aktualisiert. Unbekannte IDs werden mit `notFound` übersprungen.
`requireReference`	`yes`, `no`	`yes`	Schutz vor Tippfehlern: Ein fehlender Eintrag wird nur angelegt, wenn ein Produkt oder eine Variante des Subshops auf diese `inventoryId` verweist. Mit `no` wird die Prüfung abgeschaltet. Wirkt nur, wenn `createMissing` nicht `no` ist.

Bestehende Einträge werden immer aktualisiert, auch wenn kein Produkt auf sie verweist. requireReference greift nur beim Anlegen. Soll der Bestand bewusst angelegt werden, bevor das zugehörige Produkt existiert, senden Sie requireReference=no.

Felder pro Eintrag

Feld	Typ	Pflicht	Beschreibung
`id`	String	ja	Lagerbestands-ID (`inventoryId`)
`amount`	Number	`amount` oder `openOrder`	Bestand
`amountType`	String	nein	`relative`: `amount` wird zum bestehenden Wert addiert. Jeder andere Wert oder fehlend: Wert wird absolut gesetzt.
`openOrder`	Number	`amount` oder `openOrder`	Anzahl offener Bestellungen
`openOrderType`	String	nein	Wie `amountType`, bezogen auf `openOrder`

Mindestens amount oder openOrder muss angegeben sein. Ein nicht angegebenes Feld bleibt unverändert. Wird ein Eintrag neu angelegt, zählt eine relative Änderung ab 0: Aus {"id": "4800", "amount": 5, "amountType": "relative"} wird ein Eintrag mit amount = 5. Ein nicht angegebenes Feld wird mit 0 angelegt. Alle Felder eines Eintrags werden vor dem Schreiben geprüft. Ein ungültiger Eintrag wird vollständig übersprungen, auch wenn einzelne Felder gültig sind.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/bulk/products/inventory

Request-Body

Der Request-Body ist ein JSON-Array. Aus Kompatibilitätsgründen wird auch ein Objekt mit dem Array im Feld data akzeptiert ({"data": [ ... ]}).

[
    {
        "id": "11-1701 M",
        "amount": 10.0,
        "amountType": "absolute",
        "openOrder": -1.0,
        "openOrderType": "relative"
    },
    {
        "id": "11-1702 L",
        "amount": 5.0
    },
    {
        "id": "11-1702 L",
        "amount": 1.0
    },
    {
        "id": "11-1703 XL",
        "amount": "zehn"
    }
]

Antwort

Fehler auf Zeilenebene brechen den Request nicht ab. Gültige Einträge werden geschrieben, ungültige werden in skippedLines aufgeführt. Die Antwort hat in beiden Fällen den Status 200.

{
    "items": ["11-1701 M", "11-1702 L"],
    "skippedLines": [
        {
            "lineNumber": 2,
            "inventoryId": "11-1702 L",
            "errorType": "duplicateIdInRequest",
            "fieldErrors": {}
        },
        {
            "lineNumber": 3,
            "inventoryId": "11-1703 XL",
            "errorType": "invalidParameters",
            "fieldErrors": {
                "amount": { "type": "invalidValue" }
            }
        }
    ]
}

Feld	Beschreibung
`items`	IDs aller angelegten oder aktualisierten Lagerbestände
`skippedLines[].lineNumber`	Position des Eintrags im Request-Array (ab `0` gezählt). `skippedLines` ist nach diesem Wert sortiert.
`skippedLines[].inventoryId`	ID des Eintrags. Leer, wenn keine ID ermittelt werden konnte.
`skippedLines[].errorType`	Grund für das Überspringen, siehe folgende Tabelle
`skippedLines[].fieldErrors`	Fehler je Feld, beispielsweise `{"amount": {"type": "invalidValue"}}`

Werte für `errorType`

`errorType`	Grund
`invalidParameters`	Der Eintrag ist kein JSON-Objekt. `amount` oder `openOrder` ist keine Zahl (`type: invalidValue`). `amount` und `openOrder` fehlen beide (`type: missing` für beide Felder).
`missingId`	`id` fehlt oder ist leer.
`duplicateIdInRequest`	Die `id` kam bereits weiter oben im selben Request vor. Nur das erste Vorkommen wird geschrieben.
`notFound`	Der Lagerbestand existiert nicht und `createMissing=no` ist gesetzt.
`unreferencedId`	Der Lagerbestand existiert nicht und kein Produkt bzw. keine Variante verweist auf die `id`. Tritt nicht auf, wenn `requireReference=no` gesetzt ist.

Back-in-Stock

Nach jeder erfolgreichen Änderung werden Back-in-Stock-Benachrichtigungen für alle Produkte und Varianten erzeugt, die auf die geänderte inventoryId verweisen. Ist Back-in-Stock im Shop deaktiviert, entfällt dieser Schritt.

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 Lagerbeständen.
400 Bad Request		Der Request-Body ist leer oder kein gültiges JSON. Der Request-Body ist weder ein Array noch ein Objekt mit einem Array im Feld `data`. Es wurden mehr als 1000 Einträge angegeben.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben (`errorContext.stageId`).

Methoden für Produkte Lagerbestand

Über die folgenden Endpunkte lassen sich lagerbezogene Einstellungen für einzelne Produkte verwalten. Dazu zählen sowohl die Zuordnung zu einem Lagerbestandseintrag als auch die Konfiguration der Darstellung im Shop, beispielsweise farbliche Ampellogik, individuelle Lagermeldungen und Reservierungszeiten. Die Einstellungen greifen dabei direkt auf die allgemeinen Lagerbestände zu, die über die Endpunkte im Abschnitt Methoden für Lagerbestand Allgemein gepflegt werden. Für den Zugriff auf diese Endpunkte sind Lese- oder Schreibrechte für Produktdaten erforderlich, je nach gewählter Operation.

GET products/{productId}/inventory

Mit diesem Endpunkt können Sie die Lagerbestandskonfiguration eines bestimmten Produkts abrufen. Diese Konfiguration umfasst unter anderem Schwellwerte für Ampelfarben, individuelle Lagermeldungen und die Reservierungsdauer. Die Angabe storeId verweist auf einen allgemeinen Lagerbestandseintrag, wie er über die Lagerbestands-Endpunkte verwaltet wird. Für die Verwendung dieses Endpunkts sind Lese-Berechtigungen für Produktdaten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/11-703/inventory

Antwort

{
    "active": true,
    "greenYellowBorder": 0,
    "messageLimit": 5,
    "messageMail": "m.mustermann@websale.de",
    "messageMode": "inactive",
    "redOrder": true,
    "reservationTime": 10,
    "state": "dynamic",
    "storeId": "11-1701%20M",
    "textGreen": "auf Lager",
    "textRed": "Wieder vorrätig in 1 Woche(n)",
    "textYellow": "Geringe Stückzahl",
    "useGlobalBorders": false,
    "useGlobalReservationTime": true,
    "useGlobalTexts": true,
    "yellowRedBorder": 0
}

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 Produktdaten.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben.
404 Not Found		Das Produkt mit `id={productId}` wurde nicht gefunden Kein Lagerbestand ist dem Produkt mit `id`=`{productId}` zugewiesen

PUT products/{productId}/inventory

Dieser Endpunkt dient dazu, die Lagerbestandseinstellungen eines Produkts zu aktualisieren. Dabei lassen sich beispielsweise die Darstellung im Shop (Ampel-Logik), Lagermeldungen oder die Reservierungszeit anpassen. Die Einstellung storeId bleibt hierbei unverändert und muss nicht übergeben werden. Für die Verwendung dieses Endpunkts sind Schreib-Berechtigungen für Produktdaten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/11-703/inventory

Request-Body

{
    "active": true,
    "greenYellowBorder": 0,
    "messageLimit": 5,
    "messageMail": "m.mustermann@websale.de",
    "messageMode": "inactive",
    "redOrder": true,
    "reservationTime": 10,
    "state": "dynamic",
    "textGreen": "auf Lager",
    "textRed": "Wieder vorrätig in 1 Woche(n)",
    "textYellow": "Geringe Stückzahl",
    "useGlobalBorders": false,
    "useGlobalReservationTime": true,
    "useGlobalTexts": true,
    "yellowRedBorder": 0
}

Antwort

{
    "active": true,
    "greenYellowBorder": 0,
    "messageLimit": 5,
    "messageMail": "m.mustermann@websale.de",
    "messageMode": "inactive",
    "redOrder": true,
    "reservationTime": 10,
    "state": "dynamic",
    "storeId": "11-1701%20M",
    "textGreen": "auf Lager",
    "textRed": "Wieder vorrätig in 1 Woche(n)",
    "textYellow": "Geringe Stückzahl",
    "useGlobalBorders": false,
    "useGlobalReservationTime": true,
    "useGlobalTexts": true,
    "yellowRedBorder": 0
}

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 Produktdaten.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben `state` ∉ `{“dynamic”, “green”, “yellow”, “redhard”, “redsoft”}` `messageMode` ∉ `{“inactive”, “active”, “global”}`
400 Bad Request	”invalidFormat”	Ein Feldwert hat einen falschen Datentyp, beispielsweise String statt Boolean oder Number
400 Bad Request		Der Request-Body konnte nicht geladen werden
404 Not Found		Das Produkt mit `id={productId}` wurde nicht gefunden Kein Lagerbestand ist dem Produkt mit `id`=`{productId}` zugewiesen
503 Service Unavailable		Versionskonflikte: Die Aktualisierung konnte nach mehreren Versuchen nicht durchgeführt werden.

Methoden für Varianten Lagerbestand

Dieses Kapitel beschreibt die Endpunkte zur Verwaltung von lagerbezogenen Einstellungen einzelner Produktvarianten. Wie bei Produkten lassen sich auch für Varianten spezifische Lagerbestandsanzeigen, Ampelgrenzen, individuelle Texte und Reservierungszeiten festlegen. Die Zuordnung erfolgt ebenfalls über einen storeId, der auf einen zentral gepflegten Lagerbestand verweist. Für den Zugriff sind entsprechende Lese- oder Schreibrechte auf Produktvarianten erforderlich.

GET products/{productId}/variants/{variantId}/inventory

Ruft die Lagerbestandseinstellungen der Produktvariante mit der angegebenen variantId ab. Die Einstellungen beinhalten unter anderem Ampelgrenzen, Verfügbarkeitsanzeige, E-Mail-Benachrichtigungen sowie den Verweis (storeId) auf den zugehörigen zentralen Lagerbestand. Für diese Abfrage werden Lese-Rechte auf Produktvarianten benötigt.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/11-703/variants/1/inventory

Antwort

{
    "active": true,
    "greenYellowBorder": 0,
    "messageLimit": 5,
    "messageMail": "m.mustermann@websale.de",
    "messageMode": "inactive",
    "redOrder": true,
    "reservationTime": 10,
    "state": "dynamic",
    "storeId": "GUT",
    "textGreen": "auf Lager",
    "textRed": "Wieder vorrätig in 1 Woche(n)",
    "textYellow": "Geringe Stückzahl",
    "useGlobalBorders": false,
    "useGlobalReservationTime": true,
    "useGlobalTexts": true,
    "yellowRedBorder": 0
}

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 Produktvarianten.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben.
404 Not Found		Das Produkt mit `id={productId}` wurde nicht gefunden Die Produktvariante mit `id={variantId}` wurde nicht gefunden Kein Lagerbestand ist dem Produkt mit `id`=`{productId}` zugewiesen

PUT products/{productId}/variants/{variantId}/inventory

Aktualisiert die Lagerbestandseinstellungen der Produktvariante mit der angegebenen variantId. Die Konfigurationen wirken sich direkt auf die Darstellung im Shop aus und steuern beispielsweise die Verfügbarkeitsanzeige. Die Verknüpfung zum zentralen Lager erfolgt über das Feld storeId. Für diese Operation werden Schreibrechte auf Produktvarianten benötigt.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/11-703/variants/1/inventory

Request-Body

{
    "active": true,
    "greenYellowBorder": 0,
    "messageLimit": 5,
    "messageMail": "m.mustermann@websale.de",
    "messageMode": "inactive",
    "redOrder": true,
    "reservationTime": 10,
    "state": "dynamic",
    "textGreen": "auf Lager",
    "textRed": "Wieder bestellbar in 1 Woche(n)",
    "textYellow": "Geringe Menge",
    "useGlobalBorders": false,
    "useGlobalReservationTime": true,
    "useGlobalTexts": true,
    "yellowRedBorder": 0
}

Antwort

{
    "active": true,
    "greenYellowBorder": 0,
    "messageLimit": 5,
    "messageMail": "m.mustermann@websale.de",
    "messageMode": "inactive",
    "redOrder": true,
    "reservationTime": 10,
    "state": "dynamic",
    "textGreen": "auf Lager",
    "textRed": "Wieder bestellbar in 1 Woche(n)",
    "textYellow": "Geringe Menge",
    "useGlobalBorders": false,
    "useGlobalReservationTime": true,
    "useGlobalTexts": true,
    "yellowRedBorder": 0
}

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 Produktvarianten.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben `state` ∉ `{“dynamic”, “green”, “yellow”, “redhard”, “redsoft”}` `messageMode` ∉ `{“inactive”, “active”, “global”}`
400 Bad Request	”invalidFormat”	Ein Feldwert hat einen falschen Datentyp, beispielsweise String statt Boolean oder Number
400 Bad Request		Der Request-Body konnte nicht geladen werden
404 Not Found		Das Produkt mit `id={productId}` wurde nicht gefunden Die Produktvariante mit `id={variantId}` wurde nicht gefunden Kein Lagerbestand ist dem Produkt mit `id`=`{productId}` zugewiesen
503 Service Unavailable		Versionskonflikte: Die Aktualisierung konnte nach mehreren Versuchen nicht durchgeführt werden.

Bulk-Methoden für Lagereinstellungen

Mit dem folgenden Endpunkt pflegen Sie die Lagereinstellungen mehrerer Produkte und Varianten in einem einzigen Request. Er ist das Bulk-Gegenstück zu PUT products/{productId}/inventory und PUT products/{productId}/variants/{variantId}/inventory.

POST bulk/products/inventoryConfig

Mit diesem Endpunkt legen Sie die Lagereinstellungen mehrerer Produkte und/oder Varianten an oder aktualisieren sie (Upsert). Dazu zählen Ampelgrenzen, Texte, Lagermeldungen, Reservierungszeiten und die Verknüpfung mit einem Lagerbestand über storeId. Ein Request darf Produkte und Varianten gemischt enthalten. Da ein Request Produkte und Varianten enthalten kann, benötigen Sie immer die Schreibrechte für Produktdaten und für Produktvarianten. Die Berechtigung wird einmal für den gesamten Request geprüft. In einem Request können maximal 1000 Einträge verarbeitet werden. Dieses Limit gilt gemeinsam für alle Bulk-Endpunkte der API. Weitere Informationen finden Sie in den API Basics: Bulk-Endpunkte. Bei mehr Einträgen wird der gesamte Request abgelehnt und nichts geschrieben.

URL-Parameter

Parameter	Werte	Standard	Beschreibung
`subshopId`	Subshop-ID	Header `X-SubshopId`, sonst erster Subshop	Subshop
`stage`	`work`, `active`	`work`	Content-Stage

Adressierung

Feld	Typ	Pflicht	Beschreibung
`productId`	String	ja	ID des Produkts
`variantId`	String	nein	Ist das Feld gesetzt, werden die Einstellungen der Variante geschrieben, sonst die des Produkts.

Ein Produkt und seine Varianten dürfen im selben Request vorkommen. Dieselbe Kombination aus productId und variantId darf dagegen nur einmal enthalten sein.

Einstellungsfelder

Alle Einstellungsfelder sind optional. Nicht angegebene Felder behalten ihren gespeicherten Wert. Es gelten dieselben Felder und Prüfungen wie bei den Einzel-Endpunkten.

Feld	Typ	Beschreibung
`active`	Boolean	Lagerführung aktiv
`storeId`	String	Verknüpft das Produkt bzw. die Variante mit einer abweichenden `inventoryId`. Ein leerer String (`""`) entfernt die Verknüpfung. Dann gilt wieder der Standardschlüssel, siehe Woher kommt die `inventoryId`?.
`state`	String	`dynamic`, `green`, `yellow`, `redhard`, `redsoft`
`useGlobalBorders`	Boolean	Globale Ampelgrenzen verwenden
`greenYellowBorder`	Number	Grenze von Grün zu Gelb
`yellowRedBorder`	Number	Grenze von Gelb zu Rot
`useGlobalTexts`	Boolean	Globale Ampeltexte verwenden
`textGreen`	String	Text für Grün
`textYellow`	String	Text für Gelb
`textRed`	String	Text für Rot
`redOrder`	Boolean	Bei Rot bestellbar
`useGlobalReservationTime`	Boolean	Globale Reservierungszeit verwenden
`reservationTime`	Number	Reservierungszeit
`messageMode`	String	`inactive`, `active`, `global`
`messageLimit`	Number	Schwellwert für die Lagermeldung
`messageMail`	String	Empfänger der Lagermeldung

Das Produkt bzw. die Variante muss bereits existieren. Existieren für sie noch keine Lagereinstellungen, werden sie mit Standardwerten angelegt und mit den Werten aus dem Request ergänzt. Der Suchindex wird, wie bei den Einzel-Endpunkten, nicht aktualisiert.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/bulk/products/inventoryConfig

Request-Body

Der Request-Body muss ein JSON-Array sein. Ein Objekt mit dem Feld data wird hier nicht akzeptiert.

[
    {
        "productId": "11-703",
        "active": true,
        "state": "dynamic",
        "useGlobalBorders": false,
        "greenYellowBorder": 10,
        "yellowRedBorder": 2
    },
    {
        "productId": "11-703",
        "variantId": "1",
        "storeId": "EAN-4006381333931"
    },
    {
        "productId": "11-999",
        "active": true
    },
    {
        "productId": "11-703",
        "variantId": "2",
        "state": "orange"
    }
]

Antwort

Fehler auf Zeilenebene brechen den Request nicht ab. Gültige Einträge werden geschrieben, ungültige werden in skippedLines aufgeführt. Die Antwort hat in beiden Fällen den Status 200.

{
    "items": [
        { "lineNumber": 0, "productId": "11-703" },
        { "lineNumber": 1, "productId": "11-703", "variantId": "1" }
    ],
    "skippedLines": [
        {
            "lineNumber": 2,
            "productId": "11-999",
            "errorType": "productNotFound",
            "fieldErrors": {}
        },
        {
            "lineNumber": 3,
            "productId": "11-703",
            "variantId": "2",
            "errorType": "invalidParameters",
            "fieldErrors": {
                "state": { "type": "invalidValue" }
            }
        }
    ]
}

Feld	Beschreibung
`items[]`	Erfolgreich geschriebene Einträge mit `lineNumber`, `productId` und bei Varianten `variantId`
`skippedLines[].lineNumber`	Position des Eintrags im Request-Array (ab `0` gezählt). `skippedLines` ist nach diesem Wert sortiert.
`skippedLines[].productId`	ID des Produkts. Leer, wenn keine ID ermittelt werden konnte.
`skippedLines[].variantId`	Nur vorhanden, wenn der Eintrag eine Variante adressiert
`skippedLines[].errorType`	Grund für das Überspringen, siehe folgende Tabelle
`skippedLines[].fieldErrors`	Fehler je Feld, beispielsweise `{"greenYellowBorder": {"type": "invalidFormat", "expectedType": "number"}}`

Werte für `errorType`

`errorType`	Grund
`invalidParameters`	Der Eintrag ist kein JSON-Objekt. Ein Feldwert hat einen falschen Datentyp (`type: invalidFormat` mit `expectedType`). `state` oder `messageMode` enthält einen unbekannten Wert (`type: invalidValue`).
`missingProductId`	`productId` fehlt oder ist leer.
`duplicateEntryInRequest`	Dieselbe Kombination aus `productId` und `variantId` kam bereits weiter oben im selben Request vor.
`productNotFound`	Das Produkt existiert im Subshop bzw. in der Stage nicht.
`variantNotFound`	Das Produkt existiert, die Variante aber nicht.
`versionConflict`	Der Eintrag konnte wegen paralleler Änderungen auch nach mehreren Versuchen nicht geschrieben werden. Anders als bei den Einzel-Endpunkten (`503`) wird nur dieser Eintrag übersprungen.

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 Produktdaten und Produktvarianten.
400 Bad Request		Der Request-Body ist leer, kein gültiges JSON oder kein Array. Es wurden mehr als 1000 Einträge angegeben.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage oder ein ungültiger Subshop angegeben.

Mehrere Varianten teilen sich einen Lagerbestand

Über storeId verknüpfen Sie mehrere Varianten mit demselben Lagerbestand, beispielsweise über die EAN:

[
    { "productId": "11-703", "variantId": "1", "storeId": "EAN-4006381333931" },
    { "productId": "11-703", "variantId": "2", "storeId": "EAN-4006381333931" }
]

Anschließend genügt ein einziger Eintrag in POST bulk/products/inventory, um den Bestand beider Varianten zu setzen:

[
    { "id": "EAN-4006381333931", "amount": 40 }
]

Ist Back-in-Stock im Shop aktiv, werden die Benachrichtigungen für beide Varianten erzeugt. Um die Verknüpfung einer Variante wieder aufzuheben, senden Sie "storeId": "".

Typischer Ablauf beim Import

Produkte importieren

POST bulk/products legt die Produkte an oder aktualisiert sie.

Lagereinstellungen setzen

POST bulk/products/inventoryConfig setzt die Lagereinstellungen. Bei Bedarf verknüpfen Sie über storeId eine abweichende inventoryId.

Bestände schreiben

POST bulk/products/inventory schreibt die Bestände. Da requireReference standardmäßig aktiv ist, werden nur inventoryIds angelegt, auf die ein Produkt oder eine Variante aus den vorherigen Schritten verweist.

Werden die Bestände vor den Produkten geliefert, rufen Sie POST bulk/products/inventory mit requireReference=no auf.

Methoden für Set-Produkte

Dieses Kapitel beschreibt die Endpunkte zur Verwaltung von Set-Produkten (Produktbündeln). Für den Zugriff sind entsprechende Lese-, Schreib- oder Löschrechte auf Produktdaten erforderlich. Der Preis eines Sets ist kein gespeicherter Wert. Er wird aus dem Preis des Hauptprodukts und den Preisen der Unterprodukte berechnet, und zwar jedes Mal neu. Wer ihn anzeigen will, ruft ihn über den Endpunkt POST products/setproducts/preview ab. Was das für bestehende Anbindungen bedeutet, steht am Ende dieses Kapitels im Abschnitt Set-Preis wird nicht mehr gespeichert.

GET products/{parentProductId}/setproducts

Gibt eine Liste mit Unterprodukten zurück, wenn das Produkt mit id=parentProductId einen Set besitzt. Optional kann setParentProductList IDs der Produkte enthalten, zu deren Sets das aktuelle Produkt gehört. Für diese Abfrage werden Lese-Rechte auf Produktdaten benötigt. Mit size legen Sie fest, wie viele Unterprodukte items enthält. Mit from legen Sie den Startpunkt fest (ab 0 gezählt). Ohne size bleibt items leer. totalCount und setData enthalten dennoch alle Mitglieder des Sets.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/12-2325/setproducts?subshopId=deutsch&from=0&size=100

Antwort (Hauptprodukt)

{
    "endReached": true,
    "isChildProduct": false,
    "items": [
        {
            "active": "always",
            "custom": {
                "brand": "",
                "commission": 0,
                "commissionTaxRate": "",
                "crossSelling": [],
                "customNumber": "",
                "ean": "",
                "filterField": "",
                "image": [],
                "isbn": "",
                "mainCategory": "",
                "metaDescription": "",
                "metaDescriptionSetManually": false,
                "metaTitle": "",
                "metaTitleSetManually": false,
                "multiProducts": "",
                "oneTimeFee": 0,
                "oneTimeFeeTaxRate": "",
                "productDiscount": 0,
                "productDiscountAbsolute": false,
                "productType": "",
                "robotsNoFollow": false,
                "robotsNoIndex": false,
                "validForDiscount": false,
                "video": "",
                "voucherProductActive": false,
                "voucherProductHtmlTemplate": "",
                "voucherProductPrice": false,
                "voucherProductTemplate": "",
                "weight": 0
            },
            "descr": "Beautiful! Mit unserer neuen, weißen Bluse mit femininen Volants an Kragen und Knopfleiste kreieren Sie im Nu lässig verspielte Looks. Das sportliche Feinoxford-Gewebe trägt sich sehr komfortabel und schmeichelt der Haut. Ein absolutes Must-have und Lieblingsteil für die neue Saison. Geschneidert <span class='passform'>in leicht taillierter Form (Regular Fit)</span> mit verdeckter Knopfleiste und gerundeter Saumlinie. <span class='mass'>Länge ca. 68 cm.</span><span class='katalogfarbe'>Farbe: Weiß.</span><span class='herkunft'>Original Herringbone.</span>  <span class='material'>Reine Baumwolle.</span>",
            "hasVariants": true,
            "id": "11-2492",
            "itemNumber": "11-2492",
            "name": "Rüschenbluse 'Florence'",
            "price": {
                "price": "69.900000",
                "scheduledPrices": []
            },
            "taxRateId": "1",
            "timestampCreatedAt": "2025-02-14T10:50:41.000Z",
            "timestampUpdatedAt": "2025-04-28T10:24:24.000Z"
        },
        {
            "active": "always",
            "custom": {
                "brand": "",
                "commission": 0,
                "commissionTaxRate": "",
                "crossSelling": [],
                "customNumber": "",
                "ean": "",
                "filterField": "",
                "image": [],
                "isbn": "",
                "mainCategory": "",
                "metaDescription": "",
                "metaDescriptionSetManually": false,
                "metaTitle": "",
                "metaTitleSetManually": false,
                "multiProducts": "",
                "oneTimeFee": 0,
                "oneTimeFeeTaxRate": "",
                "productDiscount": 0,
                "productDiscountAbsolute": false,
                "productType": "",
                "robotsNoFollow": false,
                "robotsNoIndex": false,
                "validForDiscount": false,
                "video": "",
                "voucherProductActive": false,
                "voucherProductHtmlTemplate": "",
                "voucherProductPrice": false,
                "voucherProductTemplate": "",
                "weight": 0
            },
            "descr": "Schlichter Unterziehrolli? Von wegen! Dieses Basicteil werden Sie lieben, sobald Sie es das erste Mal getragen haben. Es ist aus besonders edlem Swiss Cotton Jersey gefertigt, einem sehr feinen, samtweichen und luxuriösen Jersey mit zartem Glanz. Auf der Haut fühlt er sich wahnsinnig gut an und durch seine Elastizität ist er unendlich bequem. Der etwas weiter geschnittene Rollkragen, wird locker drapiert und engt daher überhaupt nicht ein. Tragen Sie dieses Rollkragenshirt unter Blazern, Westen, Hemdjacken oder Blusen und Sie werden nicht nur top aussehen, sondern sich auch so fühlen! <span class='passform'>Normale Form (Regular Fit).</span><span class='mass'>Länge ca. 66 cm.</span><span class='katalogfarbe'>Farbe: Ecru.</span><span class='herkunft'>Original Herringbone.</span>  <span class='material'>Reine Baumwolle.</span>",
            "hasVariants": true,
            "id": "11-2497",
            "itemNumber": "11-2497",
            "name": "Edles Rollkragenshirt",
            "price": {
                "price": "89.900000",
                "scheduledPrices": []
            },
            "taxRateId": "1",
            "timestampCreatedAt": "2025-02-14T10:50:43.000Z",
            "timestampUpdatedAt": "2025-04-28T10:24:24.000Z"
        }
    ],
    "setData": {
        "items": [
            {
                "fixQuantity": false,
                "hidden": false,
                "id": "11-2497",
                "quantityFactor": 1,
                "usePrice": true
            },
            {
                "fixQuantity": false,
                "hidden": false,
                "id": "11-2492",
                "quantityFactor": 1,
                "usePrice": true
            }
        ]
    },
    "setParentProductList": [],
    "totalCount": 2
}

Antwort (Set-Unterprodukt)

{
    "endReached": true,
    "isChildProduct": true,
    "items": [],
    "setData": {},
    "setParentProductList": [
        "12-2325"
    ],
    "totalCount": 0
}

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 Produktdaten.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben.

POST products/{parentProductId}/setproducts/assign

Die Produkte aus dem Request-Body werden dem Set des Produkts mit der ID id=parentProductId zugewiesen. Das Feld prodId kann entweder einen einzelnen String oder ein Array von Strings enthalten. Es können nur vorhandene Produkte zugewiesen werden. Ist eines der Produkte unbekannt, lehnt der Shop den gesamten Request ab und weist keines der Produkte zu. Für diese Abfrage werden Schreib-Rechte auf Produktdaten benötigt.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/11-2803/setproducts/assign?subshopId=deutsch

Request Body

{
	"prodId": [
		"105-59442"
	]
}

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 Produktdaten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben.
400 Bad Request	”missing”	`prodId` fehlt oder ist leer.
400 Bad Request	”notFound”	Ein Produkt aus `prodId` existiert nicht. Die Fehlermeldung nennt das betroffene Feld, bei mehreren Produkten mit Index, beispielsweise `prodId.[1]`.
400 Bad Request	”invalidFormat”	`prodId` ist kein Array von Strings.
400 Bad Request	”unknownDataField”	Der Request Body enthält unbekannte Felder.
404 Not Found		`parentProductId` fehlt.

POST products/{parentProductId}/setproducts/update/{childProductId}

Daten vom Produkt mit id=childProductId im Set vom Produkt mit id=parentProductId werden aktualisiert. Für diese Abfrage werden Schreibrechte auf Produktdaten benötigt. Im Objekt setData müssen alle fünf Felder id, quantityFactor, usePrice, fixQuantity und hidden angegeben werden. Wenn die id ein anderes Produkt als childProductId nennt, wird das Mitglied durch dieses Produkt ersetzt.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/12-2325/setproducts/update/11-2492?subshopId=deutsch

Request Body

{
    "setData": {
        "id": "11-2492",
        "quantityFactor": 1,
        "usePrice": true,
        "fixQuantity": false,
        "hidden": false
    }
}

Antwort

{
    "parentProductId": "12-2325",
    "childProductId": "11-2492",
    "setData": {
        "id": "11-2492",
        "quantityFactor": 1,
        "usePrice": true,
        "fixQuantity": false,
        "hidden": false
    }
}

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 Produktdaten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben.
400 Bad Request	”missing”	`setData` fehlt im Request Body. Ein Feld in `setData` fehlt.
400 Bad Request	”invalidFormat”	`setData` ist kein Objekt. Ein Feld in `setData` hat den falschen Typ.
400 Bad Request	”invalidValue”	`quantityFactor` ist keine gültige Mengenangabe.
400 Bad Request	”unknownDataField”	Der Request Body enthält unbekannte Felder.
404 Not Found		`parentProductId` oder `childProductId` fehlen.

POST products/setproducts/preview

Dieser Endpunkt berechnet den Preis eines Set-Produkts aus den übergebenen Werten und gibt das Ergebnis zurück. Er speichert nichts. Damit lässt sich der Set-Preis bereits während der Bearbeitung anzeigen, also noch bevor das Produkt gespeichert wird. Berechnet werden zwei Werte. setPrice ist die Summe aus dem Preis des Hauptprodukts und den Preisen aller Unterprodukte mit usePrice. setOrgPrice ist die Summe aus dem Preis des Hauptprodukts und den Preisen aller Unterprodukte und dient als Referenzpreis. Die Preise werden zum aktuellen Zeitpunkt aufgelöst, aktive Aktionspreise fließen also in beide Werte ein. Für diese Abfrage werden Schreib-Rechte auf Produktdaten benötigt.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/setproducts/preview

Request Body

{
    "parentPrice": 19.99,
    "setProducts": [
        {
            "id": "P1",
            "usePrice": true,
            "quantityFactor": 2
        },
        {
            "id": "P2",
            "usePrice": false,
            "quantityFactor": 1
        }
    ],
    "scheduledPrices": [
        {
            "price": "14.99",
            "startDate": "2026-08-01T00:00:00.000Z",
            "endDate": "2026-08-31T23:59:59.000Z",
            "promotionInfo": "Sommeraktion",
            "validForDiscount": true
        }
    ],
    "fixQuantity": false,
    "hidden": false
}

Parameter	Typ	Beschreibung
`parentPrice`	`number`	Standardpreis des Hauptprodukts. Pflichtangabe.
`setProducts`	`array` (object)	Liste der Unterprodukte. Pflichtangabe.
`setProducts[].id`	`string`	ID des Unterprodukts.
`setProducts[].usePrice`	`bool`	Gibt an, ob der Preis dieses Unterprodukts in `setPrice` einfließt.
`setProducts[].quantityFactor`	`number`	Menge, mit der das Unterprodukt in das Set eingeht.
`scheduledPrices`	`array` (object)	Geplante Aktionspreise des Hauptprodukts. Optional. Aufbau wie im Abschnitt Zeitgesteuerte Preise (Aktionspreise) beschrieben.
`fixQuantity`	`bool`	Optional. Gilt für alle Unterprodukte gemeinsam, nicht je Unterprodukt.
`hidden`	`bool`	Optional. Gilt für alle Unterprodukte gemeinsam, nicht je Unterprodukt.

Unbekannte IDs in setProducts werden übersprungen, ohne einen Fehler auszulösen. Ein Tippfehler in setProducts[].id führt deshalb nicht zu 404, sondern zu einer Antwort mit einem zu niedrigen Preis. Prüfen Sie die IDs vor dem Aufruf.

Antwort

{
    "setPrice": "29.97",
    "setOrgPrice": "39.96"
}

Beide Werte sind Strings. Die Antwort im Beispiel ergibt sich aus einem Preis von 4,99 für P1 und 9,99 für P2. setPrice enthält das Hauptprodukt und das zweifache P1, also 19,99 plus 9,98. In setOrgPrice kommt zusätzlich P2 hinzu, weil dort alle Unterprodukte einfließen. Tragen alle Unterprodukte usePrice, sind beide Werte gleich.

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 Produktdaten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”missing”	`parentPrice` oder `setProducts` fehlt.
400 Bad Request	”invalidFormat”	Ein Feld hat einen unpassenden Typ, beispielsweise `setProducts` als Objekt statt als Array.
400 Bad Request	”invalidValue”	Ein Eintrag in `scheduledPrices` ist ungültig. Die Fehlerschlüssel beschreibt der Abschnitt Validierung und Fehlerschlüssel.

Entfallener Endpunkt. Der bisherige Endpunkt PUT products/{childProductId}/setproducts/recalculate steht nicht mehr zur Verfügung. Er hat den Set-Preis berechnet und gespeichert. An seine Stelle tritt POST products/setproducts/preview, der ausschließlich berechnet.

DELETE products/{parentProductId}/setproducts/{childProductId}

Das Produkt mit id=childProductId wird aus dem Set vom Produkt mit id=parentProductId entfernt. Gilt childProductId=all, werden alle Produkte aus dem Set entfernt. Gilt parentProductId=all, wird das Produkt mit id=childProductId aus allen Sets entfernt, in denen es enthalten ist. Für diese Abfrage werden Löschberechtigungen für Produktdaten benötigt.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/products/11-2527/setproducts/11-703

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 Produktdaten.
400 Bad Request	”invalidValue”	Es wurde eine ungültige Stage angegeben.
404 Not Found		`parentProductId` oder `childProductId` fehlen.

Set-Preis wird nicht mehr gespeichert

Der Set-Preis ist kein gespeicherter Wert mehr, sondern wird bei Bedarf berechnet. Die impliziten Neuberechnungen beim Anlegen, Aktualisieren und Löschen von Produkten, bei den Bulk-Endpunkten und im Produktimport sind entfallen. Für Clients bedeutet das zwei Dinge. Erstens liefert kein Endpunkt mehr einen gespeicherten Set-Preis aus. Zweitens muss ein Client, der den Set-Preis anzeigen will, ihn über den Endpunkt POST products/setproducts/preview berechnen lassen.

Im Shop wird der Set-Preis weiterhin bei jedem Seitenaufruf berechnet. Die Felder am Template-Objekt haben sich dabei geändert, setPrice und die zugehörigen Felder stehen nur noch an Set-Produkten. Was das für bestehende Templates bedeutet, beschreibt der Abschnitt Änderungen an bestehenden Templates.

Entfernte Felder

Feld	Ort	Auswirkung
`setPrice`	Basisfeld eines Produkts	Erscheint nicht mehr in Produkt-Antworten und wird in Requests nicht mehr gelesen. Auch das Standard-Produktfeld in der Konfiguration ist entfallen.
`setOrgPrice`	Slot in `content.usedFields.products`	Der Slot ist aus dem Konfigurationsschema entfernt.
`double_setPrice`	Elasticsearch-Mapping	Das Indexfeld ist entfernt.

Die Entfernung von double_setPrice betrifft alle Abfragen, Filter und Sortierungen, die dieses Indexfeld verwenden. Bestehende Anbindungen müssen vor dem Update geprüft und angepasst werden.

Ergänzende Referenzen

Hinweis zu Produktdatenfeldern

Neue Produktdatenfelder (zusätzliche Eigenschaften, Attribute oder technische Felder) können nicht direkt über die Produkt-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.customProductField verwendet werden. → content - Katalog (Kategorien & Produkte) Dort lassen sich individuelle Felder mit Typ, Suchrelevanz, Pflichtstatus und Varianteneigenschaften anlegen. Sobald ein Feld dort konfiguriert wurde, steht es anschließend automatisch in der Produkt-API zur Verfügung, beispielsweise in GET products oder POST products.

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

​Beispielhafter Datensatz

​Zeitgesteuerte Preise (Aktionspreise)

​Preisfelder in Antworten

​Antwort (Auszug)

​Parameterübersicht

​Preisfelder in Requests

​Request Body (Auszug)

​Wirkung im Shop

​Validierung und Fehlerschlüssel

​Hinweis zum internen Speicherformat

​Methoden für Produkte

​GET products

​Reihenfolge bei inCategory

​Beispiel

​Antwort

​Filterfelder

​Sortierfelder

​Sonstige Parameter

​Fehlercodes

​GET products/{productId}

​Beispiel

​Antwort

​Fehlercodes

​GET products/{productId}/url

​Beispiel

​Antwort

​Fehlercodes

​GET products/{productId}/categories

​Beispiel

​Antwort

​Fehlercodes

​GET products/testRule

​Beispiel

​Antwort

​Mögliche Werte für mode

​Fehlercodes

​POST products

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​PUT products/{productId}

​Beispiel

​Request-Body

​Antwort

​Fehlercodes

​DELETE products/{productId}

​Beispiel

​Antwort

​Fehlercodes

​Bulk-Methoden für Produkte

​POST bulk/products

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​Methoden für Variantenattribute

​GET products/variants

​Beispiel

​Antwort

​Fehlercodes

​GET products/variants/{id}

​Beispiel (Attribut)

​Antwort (Attribut)

​Beispiel (Option)

​Antwort (Option)

​Fehlercodes

​POST products/variants

​Beispiel

​Request-Body

​Antwort

​Fehlercodes

​PUT products/variants/{attributeId}

​Query-Parameter

​Beispiel

​Request-Body

​Antwort

​Fehlercodes

Unterstützte Methoden

Datenfelder

Beispielhafter Datensatz

Zeitgesteuerte Preise (Aktionspreise)

Preisfelder in Antworten

Antwort (Auszug)

Parameterübersicht

Preisfelder in Requests

Request Body (Auszug)

Wirkung im Shop

Validierung und Fehlerschlüssel

Hinweis zum internen Speicherformat

Methoden für Produkte

GET products

Reihenfolge bei `inCategory`

Beispiel

Antwort

Filterfelder

Sortierfelder

Sonstige Parameter

Fehlercodes

GET products/{productId}

Beispiel

Antwort

Fehlercodes

GET products/{productId}/url

Beispiel

Antwort

Fehlercodes

GET products/{productId}/categories

Beispiel

Antwort

Fehlercodes

GET products/testRule

Beispiel

Antwort

Mögliche Werte für `mode`

Fehlercodes

POST products

Beispiel

Request Body

Antwort

Fehlercodes

PUT products/{productId}

Beispiel

Request-Body

Antwort

Fehlercodes

DELETE products/{productId}

Beispiel

Antwort

Fehlercodes

Bulk-Methoden für Produkte

POST bulk/products

Beispiel

Request Body

Antwort

Fehlercodes

Methoden für Variantenattribute

GET products/variants

Beispiel

Antwort

Fehlercodes

GET products/variants/{id}

Beispiel (Attribut)

Antwort (Attribut)

Beispiel (Option)

Antwort (Option)

Fehlercodes

POST products/variants

Beispiel

Request-Body

Antwort

Fehlercodes

PUT products/variants/{attributeId}

Query-Parameter

Beispiel

Request-Body

Antwort

Fehlercodes