API-Referenz Produkte - WEBSALE Dokumentation

Der Endpunkt /products stellt Ihnen eine Schnittstelle bereit, mit der Sie Produktdaten und Lagerbestände in unserem Shop-System verwalten können. Darüber können Sie Produkte erstellen, bearbeiten, filtern, abrufen und löschen sowie Lagerbestandsinformationen zu Produkten abrufen, aktualisieren und löschen.

Unterstützte Methoden

Befehl/Info	Endpunkte	GET	POST	PUT	DELETE
Allgemeines Produkt	products/
Allgemeines Produkt (Bulk)	bulk/products
Variantenattribute	products/variants
Varianten	products/{productId}/variants
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
Set-Produkte	products/{parentProductId}/setproducts

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	Integer	Maximal zulässige Bewertung (beispielsweise 5)
ratingApprovalConfig.minimumRating	Integer	Minimal zulässige Bewertung (beispielsweise 0)
statistics.averageRating	Float	Durchschnittliche Bewertung des Produkts
statistics.ratingCount	Integer	Anzahl der abgegebenen Bewertungen
statisticsPerPoint	Array	Bewertungshistogramm: für jeden möglichen Wert Anzahl 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)

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. 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. Wenn der Parameter inCategory verwendet wird, erfolgt die Ausgabe der Produkte nicht in der im Shop gepflegten Reihenfolge innerhalb der Kategorie. Um die Produkte in der korrekten Reihenfolge zu erhalten, verwenden Sie bitte den Endpunkt GET categories/{categoryId}/products. 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?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": "WzAuMCwiMTEtMjgxNV9kZXV0c2NoXzMiXQ",
    "totalCount": 1296
}

Filterfelder

Alle Produktdatenfelder, inCategory, notInCategory, inSetProduct, notInSetProduct

Sortierfelder

Alle Produktdatenfelder

Sonstige Parameter

from

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` ∉ [1;300] `pageToken` ist keine Zahl oder kleiner als 0. `from` ist größer als 9999. 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.
503 Service Unavailable	”serviceUnavailable”	Das Lesen von Daten ist fehlgeschlagen.

GET products/

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

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%22&active%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 activemuss den Wertalwayshaben.
Es werden nur Produkte berücksichtigt, die dauerhaft aktiv sind.
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)

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

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. Zum Erstellen eines Produkts sind entsprechende Berechtigungen erforderlich.

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.

Fehler in geplanten Aktionspreisen werden je Eintrag gemeldet. Die Schlüssel beschreibt der Abschnitt Validierung und Fehlerschlüssel.

PUT products/

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. Die vollständigen Produktdaten müssen im Request-Body übergeben werden. 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	”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/

Mit dem Endpunkt products/{productId} kann ein Produkt mit der angegebenen ID dauerhaft gelöscht werden. Dieser Vorgang entfernt das Produkt vollständig aus dem System. 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. Wird der Parameter createMissing=yes gesetzt, dann werden Produkte in der Anfrage die noch nicht existieren automatisch neues angelegt. In einem Request können maximal 1000 Einträge verarbeitet werden.

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

Mit den Endpunkten im Bereich products/variants/ lassen sich die Variantenattribute und zugehörige Optionen verwalten, die zur Bildung von Produktvarianten im Shop verwendet werden. Sie können neue Attribut-Optionen hinzufügen, bestehende anpassen oder Attribute löschen. Ebenso können Sie die Anzeige-Reihenfolge von Optionen ändern oder gezielt einzelne Optionen abfragen. Für alle hier dokumentierten Endpunkte ist eine gültige Authentifizierung erforderlich. Zusätzlich benötigen Sie die Berechtigungen zum Lesen, Erstellen oder Bearbeiten von Produktdaten.

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 Produkten verfügen.

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/

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. Für die Nutzung dieses Endpunkts ist eine gültige Authentifizierung notwendig. Sie benötigen die Berechtigung zum Lesen von Produkten.

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. Für die Nutzung dieses Endpunkts ist eine gültige Authentifizierung erforderlich. Sie benötigen die Berechtigung zum Erstellen von Produkten.

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/

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, bestehende bearbeitet und die Reihenfolge der Optionen geändert werden. Das Umbenennen des Attributs ist über den optionalen Parameter newAttributeName möglich. Bereits existierende Optionen, die im Request-Body nicht enthalten sind, bleiben unverändert bestehen. Für die Nutzung dieses Endpunkts ist eine gültige Authentifizierung erforderlich. Sie benötigen die Berechtigung zum Schreiben von Produkten.

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.
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.
400 Bad Request	”missing”	`attributeId` fehlt.
404 Not Found		Das Attribut wurde nicht gefunden.
503 Internal Error	”internalError”	Das Aktualisieren ist fehlgeschlagen.

DELETE products/variants/

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. Für die Nutzung dieses Endpunkts ist eine gültige Authentifizierung erforderlich. Sie benötigen die Berechtigung zum Löschen von Produktdaten. 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

Die folgenden Endpunkte ermöglichen das Verwalten von Produktvarianten innerhalb eines bestehenden Produkts. Varianten stellen spezifische Ausprägungen eines Produkts dar (beispielsweise Größen oder Farben) und basieren auf den zuvor definierten Variantenattributen. Die API erlaubt es, Varianten einzeln abzurufen, zu erstellen, zu aktualisieren oder zu löschen sowie komplette Variantenkombinationen automatisch zu erzeugen. Für alle Endpunkte in diesem Abschnitt ist sicherzustellen, dass die entsprechenden Lese-, Schreib- oder Löschberechtigungen für Produktvarianten vorliegen. 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//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.

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

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

Mit diesem Endpunkt können die Daten einer bestimmten Produktvariante anhand ihrer Produkt-ID und Varianten-ID aktualisiert werden. Die Variante wird anhand der angegebenen ID identifiziert und mit den im Request-Body übermittelten Werten überschrieben. 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",
    "selection": {
        "Größe": "M"
    },
    "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.
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.

POST products//variantAttributes

Mit diesem Endpunkt können für ein bestimmtes Produkt Varianten automatisch aus den übergebenen Attributen erzeugt werden. Dabei wird jede mögliche Kombination der Attribut-Optionen als eigene Produktvariante angelegt. Wenn dem Produkt bisher nicht zugewiesene Attribute ergänzt oder vorhandene Attribute entfernt werden, wird der Vorgang standardmäßig abgebrochen und es wird ein 400-Fehler mit dem Fehlertyp conflict zurückgegeben. Um diesen Abbruch zu umgehen, kann der optionale Parameter force=yes verwendet werden. In diesem Fall werden alle bisherigen Kombinationen gelöscht und durch die neuen ersetzt. Für die Nutzung dieses Endpunkts sind Schreibrechte 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//variants/manage

Dieser Endpunkt ermöglicht es, gezielt bestimmte Varianten-Kombinationen für ein bestehendes Produkt anzulegen. Anders als beim Endpunkt POST products/{productId}/variantAttributes, der automatisch alle möglichen Kombinationen aus den angegebenen Attributen generiert, werden hier nur die explizit übermittelten Kombinationen erzeugt. Bereits existierende Kombinationen werden ignoriert. Bei Kollisionen wird ein entsprechender Fehlercode zurückgegeben. Optional können auch IDs übergeben werden. 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 Schreibrechte 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”	Eine übergebene Attributkombination existiert bereits als Produktvariante.
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//variants/

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 Produktvarianten 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 Produktvarianten.
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 Produktdaten in einem einzigen Request. Der Request-Body ist ein JSON-Array, in dem jedes Element ein Produkt 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. Wird der Parameter createMissing=yes gesetzt, dann werden Produktvarianten in der Anfrage die noch nicht existieren automatisch neues angelegt. In einem Request können maximal 1000 Einträge verarbeitet werden.

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"
        }
        "id": "",
        "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, die üblicherweise mit einer Produkt- oder Varianten-ID übereinstimmt. 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.

GET products/inventory/

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/

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

Request-Body

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

Antwort

{
    "amount": 15.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/

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

PUT bulk/products/inventory

Mit diesem Endpunkt können Sie mehrere Lagerbestände gleichzeitig aktualisieren. Die zu aktualisierenden Einträge werden als Array im Request-Body übergeben. Jeder Eintrag muss eine id (Lagerbestands-ID) enthalten. Für jeden Eintrag können sowohl der Bestand (amount) als auch die Anzahl der offenen Bestellungen (openOrder) angepasst werden, 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 eine angegebene id, kann über den optionalen URL-Parameter createMissing=yes automatisch ein neuer Eintrag angelegt werden. Einträge mit ungültigen Daten werden übersprungen, beispielsweise wenn amount kein Number-Typ ist.

Um diesen Endpunkt verwenden zu können, benötigen Sie die Berechtigung zum Schreiben von Lagerbeständen. In einem Request können maximal 1000 Einträge verarbeitet werden.

Beispiel

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

Request-Body

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

Antwort

{
    "items": ["11-1701 M", "11-1702 L"],
    "skippedLines": []
}

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. Es wurden mehr als 1000 Einträge angegeben.
400 Bad Request	”invalidFormat”	Der URL-Parameter `stageId` ist ungültig.

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

GET products//variants//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//variants//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.

Methoden für Set-Produkte

Dieses Kapitel beschreibt die Endpunkte zur Verwaltung von Set-Produkten (Produktbündeln). Für den Zugriff sind entsprechende Lese- oder Schreibrechte 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.

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

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//setproducts/assign

Produkte aus dem Request Body werden dem Set vom Produkt mit id=parentProductId zugewiesen. Das Feld prodId kann entweder ein einzelner String oder ein Array von Strings sein. 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	”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//setproducts/update/

Daten vom Produkt mit id=childProductId im Set vom Produkt mit id=parentProductId werden aktualisiert. Für diese Abfrage werden Schreib-Rechte auf Produktdaten benötigt.

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.
400 Bad Request	”invalidFormat”	`setData` ist kein Objekt.
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//setproducts/

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.

Verwandte Themen

API-Referenz Kategorien $wsProducts - Produktdaten API-Referenz Meta-Daten API-Referenz Statistiken API-Referenz Videos

⌘I

​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

​Beispiel

​Antwort

​Filterfelder

​Sortierfelder

​Sonstige Parameter

​Fehlercodes

​GET products/

​Beispiel

​Antwort

​Fehlercodes

​GET products//url

​Beispiel

​Antwort

​Fehlercodes

​GET products/testRule

​Beispiel

​Antwort

​Mögliche Werte für mode

​Fehlercodes

​POST products

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​PUT products/

​Beispiel

​Request-Body

​Antwort

​Fehlercodes

​DELETE products/

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

​Beispiel (Attribut)

​Antwort (Attribut)

​Beispiel (Option)

​Antwort (Option)

​Fehlercodes

​POST products/variants

​Beispiel

​Request-Body

​Antwort

​Fehlercodes

​PUT products/variants/

​Beispiel

​Request-Body

​Antwort

​Fehlercodes

​DELETE products/variants/

​Beispiel (Attribut)

​Antwort (Attribut)

​Beispiel (Option)

​Antwort (Option)

​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

Beispiel

Antwort

Filterfelder

Sortierfelder

Sonstige Parameter

Fehlercodes

GET products/

Beispiel

Antwort

Fehlercodes

GET products//url

Beispiel

Antwort

Fehlercodes

GET products/testRule

Beispiel

Antwort

Mögliche Werte für `mode`

Fehlercodes

POST products

Beispiel

Request Body

Antwort

Fehlercodes

PUT products/

Beispiel

Request-Body

Antwort

Fehlercodes

DELETE products/

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/

Beispiel (Attribut)

Antwort (Attribut)

Beispiel (Option)

Antwort (Option)

Fehlercodes

POST products/variants

Beispiel

Request-Body

Antwort

Fehlercodes

PUT products/variants/

Beispiel

Request-Body

Antwort

Fehlercodes

DELETE products/variants/

Beispiel (Attribut)

Antwort (Attribut)

Beispiel (Option)

Antwort (Option)

Fehlercodes