Storefront API Merkliste - WEBSALE Dokumentation

Mithilfe der Storefront-API für Merklisten können Produkte gespeichert, verwaltet und später schnell wiedergefunden werden. Sie bietet Endpunkte zum Anlegen, Umbenennen und Löschen von Merklisten sowie zum Hinzufügen und Entfernen einzelner Produkte.

Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl	Endpunkte	GET	PUT	POST	DELETE
Eine Merkliste abrufen.	`watchList/load`
Alle Merklisten abrufen.	`watchList/list`
Position eines Produktes auf der Merkliste abrufen.	`watchList/getItemId`
Prüfung, ob ein Produkt sich bereits auf einer bestimmten Merkliste befindet.	`watchList/checkHasProduct`
Prüfung, in wie vielen Merklisten ein bestimmtes Produkt enthalten sind.	`watchList/countListsWithProduct`
Eine neue Merkliste erstellen.	`watchList/add`
Ein oder mehrere Produkte zu einer oder mehreren Merkliste(n) hinzufügen.	`watchList/addItem`
Ein Produkt aus einer Merkliste löschen.	`watchList/deleteItem`
Den Namen einer Merkliste ändern.	`watchList/rename`
Eine Merkliste dauerhaft löschen.	`watchList/delete`

Methoden für die Merkliste

Mit diesen Methoden können Merklisten im Kundenkonto verwaltet werden: Sie laden entweder einzelne Merklisten inklusive der gespeicherten Produkte oder listen alle zum eingeloggten Nutzer gehörenden Merklisten auf. Darüber hinaus können Sie prüfen, ob bzw. wie oft ein Produkt auf Merklisten steht, neue Merklisten anlegen, Produkte (einzeln oder gesammelt) zu einer oder mehreren Merklisten hinzufügen oder wieder entfernen sowie komplette Merklisten umbenennen oder löschen. Alle Endpunkte akzeptieren ausschließlich die jeweils dokumentierten Parameter. Ein nicht dokumentierter Parameter führt zu HTTP 400 mit einer Fehlerliste im Body.

watchList/load

Mit dem folgenden Aufruf wird eine Merkliste inklusive aller gespeicherten Artikel geladen. Er kann verwendet werden, um Merklisten samt Produktdaten weiterzuverarbeiten. Beispiel-Aufruf, der die Merkliste mit der ID watchlist_132_cf76964799db4ce anzeigt

GET https://<ihr-shop>.de/api/v1/watchList/load?watchListId=watchlist_132_cf76964799db4ce

Parameterübersicht

Header-Parameter

Parameter	Beschreibung
`x-session`	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

Query-Parameter

Parameter	Typ	Beschreibung
`watchListId`	string	Pflichtfeld ID der Merkliste, die geladen werden soll.

Beispiel-Response

{
  "id": "watchlist_132_cf76964799db4ce",
  "watchListName": "testlist67",
  "items": [
    {
      "id": "6d90bbb6c33294ddcd91",
      "freeFields": {},
      "product": {
        "id": "146-78608",
        "itemNumber": "67",
        "name": "Plushie",
        "price": 6.7,
        "custom": { "image": {} },
        "isSetProduct": true,
        "setProducts": [
          { "id": "147-15732", "quantityFactor": 1, "usePrice": true, "hidden": false, "fixQuantity": false }
        ],
        "taxRateId": "19",
        "new": true,
        "timestampCreatedAt": "2025-11-04T09:27:18.000Z",
        "timestampUpdatedAt": "2025-11-10T07:52:20.000Z"
      }
    }
  ]
}

Hinweis: Einträge, deren Produkt im aktuellen Subshop nicht geladen werden kann (beispielsweise gelöscht oder nicht freigeschaltet), werden in items übersprungen. Die Merkliste selbst bleibt unverändert.

GET watchList/list

Mit folgendem Aufruf werden alle Merklisten des aktuell eingeloggten Kundenkontos angezeigt. Er kann zum Anzeigen, Auswählen oder Umschalten zwischen mehreren Merklisten eines Nutzers verwendet werden.

GET https://<ihr-shop>.de/api/v1/watchList/list

Parameterübersicht

Header-Parameter

Parameter	Beschreibung
`x-session`	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

Beispiel-Response

[
  {
    "watchListId": "watchlist_37_default",
    "watchListName": "Merkliste"
  },
  {
    "watchListId": "watchlist_37_basket",
    "watchListName": "Für später gespeichert"
  }
]

GET watchList/getItemId

Der folgende Aufruf liefert die Positions-ID eines bestimmten Produkts innerhalb einer konkreten Merkliste. Die Positions-ID ist dieselbe wie die ID eines Eintrags bei watchList/load. Beispiel Aufruf, der die Position des Produkts mit der ID 146-78608 aus der Merkliste mit der ID watchlist_132_cf76964799db4ce zurückgibt

GET https://<ihr-shop>.de/api/v1/watchList/getItemId?watchListId=watchlist_132_cf76964799db4ce&productId=146-78608

Parameterübersicht

Header-Parameter

Parameter	Beschreibung
`x-session`	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

Query-Parameter

Parameter	Typ	Beschreibung
`watchListId`	string	Pflichtfeld ID der Merkliste, in der sich das Produkt befindet.
`productId`	string	Pflichtfeld ID des Produktes in der Watchlist.

Beispiel-Response

{
  "itemId": "6d90bbb6c33294ddcd91"
}

Liegt das Produkt nicht auf der angegebenen Merkliste, ist itemId null.

GET watchList/checkHasProduct

Mit folgendem Aufruf lässt sich prüfen, ob ein bestimmtes Produkt bereits auf einer konkreten Merkliste liegt. Er kann verwendet werden, um Wunschlisten-Buttons umzuschalten oder Doppelanlagen zu verhindern. Beispiel-Aufruf, ob das Produkt mit der ID 146-78608 auf der Merkliste mit der ID watchlist_132_cf76964799db4ce vorhanden ist

GET https://<ihr-shop>.de/api/v1/watchList/checkHasProduct?watchListId=watchlist_132_cf76964799db4ce&productId=146-78608

Parameterübersicht

Header-Parameter

Parameter	Beschreibung
`x-session`	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

Query-Parameter

Parameter	Typ	Beschreibung
`watchListId`	string	Pflichtfeld ID der Merkliste, die durchsucht werden soll.
`productId`	string	Optional. ID des Produktes, nach dem gesucht werden soll. Wird der Parameter weggelassen, antwortet der Endpunkt mit `{"isOnList": false}` statt mit einem Fehler.

Beispiel-Response

{
  "isOnList": true
}

HTTP-Status

Status	Bedeutung
`400`	Kein oder ungültiger `x-session`-Header, oder unbekannter Query-Parameter übergeben.
`404`	Die angegebene `watchListId` gehört nicht zu den Merklisten der aktuellen Session.

GET watchList/countListsWithProduct

Der folgende Aufruf zählt, in wie vielen Merklisten das angegebene Produkt gespeichert ist. Er kann auf Produkt- und Kategorieseiten verwendet werden, um zu signalisieren, dass das Produkt begehrt ist, und kann beispielsweise mit dem Hinweis „Auf xxx Merklisten gespeichert” angezeigt werden. Beispiel-Aufruf, der zählt, wie oft sich das Produkt mit der ID 146-78608 auf Merklisten befindet

GET https://<ihr-shop>.de/api/v1/watchList/countListsWithProduct?productId=146-78608

Parameterübersicht

Header-Parameter

Parameter	Beschreibung
`x-session`	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

Query-Parameter

Parameter	Typ	Beschreibung
`productId`	string	Pflichtfeld ID des Produktes, nach dem Merklisten durchsucht werden sollen.

Beispiel-Response

{
  "count": 2
}

POST watchList/add

Mit dem folgenden Aufruf wird eine neue Merkliste für den aktuell angemeldeten Nutzer angelegt. Beispiel-Aufruf, der eine neue Merkliste mit dem Namen “Please, I need this” anlegt

POST https://<ihr-shop>.de/api/v1/watchList/add

Beispiel-Request

{
  "watchListName": "Please, I need this"
}

Parameterübersicht

Header-Parameter

Parameter	Beschreibung
`x-session`	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

Body-Parameter

Parameter	Typ	Beschreibung
`watchListName`	string	Pflichtfeld Name der zu erstellenden Watchlist.

Beispiel-Response

{}

Fehlercodes

Code	Beschreibung
`notLoggedIn`	Der Nutzer ist nicht eingeloggt.
`missingWatchListName`	`watchListName` fehlt oder ist leer.
`missingService`	Der Merklisten-Dienst ist nicht verfügbar.

PUT watchList/addItem

Mit folgendem Aufruf können ein oder mehrere Produkte zu einer oder mehreren Merklisten hinzugefügt werden. Er kann für Merklisten-Buttons auf Produkt-/Listing-Seiten sowie für Bulk-Aktionen verwendet werden. Beispiel-Aufruf, der die Produkte mit der ID 147-15732 und 146-78608 zu der Merkliste mit der ID watchlist_132_cf76964799db4ce hinzufügt

PUT https://<ihr-shop>.de/api/v1/watchList/addItem

Beispiel-Request

{
  "watchListIds": {
    "watchlist_132_cf76964799db4ce": "watchlist_132_cf76964799db4ce"
  },
  "multiProducts": {
    "147-15732": {},
    "146-78608": {}
  }
}

Parameterübersicht

Header-Parameter

Parameter	Beschreibung
`x-session`	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

Body-Parameter

Parameter	Typ	Beschreibung
`watchListIds`	object	Pflichtfeld Liste der Ziel-Merklisten. Schlüssel und Wert sind die Watchlist-IDs. Es muss mindestens eine ID angegeben werden.
`productId`	string	Ein Produkt, das hinzugefügt werden soll. Pflichtfeld, wenn `multiproducts`nicht übergeben wird.
`multiProducts`	object	Fügt mehrere Produkte in einem Aufruf hinzu. Schlüssel sind die Produkt-IDs. Der Wert ist ein Objekt, das optional `freeFields` für dieses Produkt enthält. Ein leeres Objekt genügt. Pflichtfeld, wenn `productId` nicht übergeben wird.
`freeFields`	object	Optional. Freie Zusatzdaten zum Produkt. Wird nur zusammen mit `productId` ausgewertet. Bei `multiProducts` wird dieses Feld ignoriert, dort werden die Zusatzdaten je Produkt aus dem Wert des Eintrags gelesen, beispielsweise `"multiProducts": { "147-15732": { "freeFields": { "farbe": "rot" } } }`.

Beispiel-Response

{}

Fehlercodes

Code	Beschreibung
`invalidProductId`	Das angefragte Produkt existiert nicht, oder es wurde eine Variantenkennung (`<produktId>.<variantenId>`) an ein Produkt ohne Varianten angehängt.
`invalidVariantId`	Das Produkt wurde gefunden, aber die zugehörige Variante nicht.
`watchListNotFound`	Die angegebene Merkliste existiert nicht.
`missingProductId`	Es wurde weder `productId` noch `multiProducts` übergeben.
`missingService`	Der Merklisten-Dienst ist nicht verfügbar (Speicherdienst nicht erreichbar).

PUT watchList/rename

Mit folgendem Aufruf wird eine bestehende Merkliste umbenannt. Beispiel-Aufruf, der die Merkliste mit der ID watchlist_132_cf76964799db4ce in “Liste 67” umbenennt

PUT https://<ihr-shop>.de/api/v1/watchList/rename

Beispiel-Request

{
	"watchListId": "watchlist_132_cf76964799db4ce",
	"newWatchListName": "Liste 67"
}

Parameterübersicht

Header-Parameter

Parameter	Beschreibung
`x-session`	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

Body-Parameter

Parameter	Typ	Beschreibung
`watchListId`	string	Pflichtfeld ID der umzubenennenden Merkliste.
`newWatchListName`	string	Pflichtfeld Neuer Name für die Merkliste.

Beispiel-Response

{}

Fehlercodes

Code	Beschreibung
`missingWatchListId`	`watchListId` fehlt oder ist leer.
`missingWatchListName`	`newWatchListName` fehlt oder ist leer.
`watchListNotFound`	Die Merkliste mit der angegebenen ID existiert nicht.
`notChangeable`	Die Merkliste darf nicht umbenannt werden (gilt für die automatisch erstellten Standardmerklisten `…_default` und `…_basket`).
`missingService`	Der Merklisten-Dienst ist nicht verfügbar.

DELETE watchList/deleteItem

Mit diesem Aufruf wird ein bestimmtes Produkt aus einer Merkliste entfernt. Beispiel-Aufruf, der das Produkt mit der watchListItemId 6d90bbb6c33294ddcd91(diese ID erhält man über den Aufruf von watchList/getItemId) von der Wunschliste mit der ID watchlist_132_cf76964799db4ce entfernt

DELETE https://<ihr-shop>.de/api/v1/watchList/deleteItem

Beispiel-Request

{
  "watchListId": "watchlist_132_cf76964799db4ce",
  "watchListItemId": "6d90bbb6c33294ddcd91"
}

Parameterübersicht

Header-Parameter

Parameter	Beschreibung
`x-session`	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

Body-Parameter

Parameter	Typ	Beschreibung
`watchListId`	string	Pflichtfeld ID der Watchlist, aus der der Eintrag entfernt werden soll.
`watchListItemId`	string	Pflichtfeld Positions-ID des zu entfernenden Produktes.

Beispiel-Response

{}

Fehlercodes

Code	Beschreibung
`missingWatchListId`	`watchListId` fehlt oder ist leer.
`missingItemId`	`watchListItemId` fehlt oder ist leer.
`invalidItemId`	Es existiert kein Eintrag mit dieser ID auf der Merkliste.
`watchListNotFound`	Die Merkliste mit der angegebenen ID existiert nicht.
`missingService`	Der Merklisten-Dienst ist nicht verfügbar.

DELETE watchList/delete

Mit dem folgenden Aufruf wird eine bestehende Merkliste dauerhaft gelöscht. Beispiel-Aufruf, der die Merkliste mit der ID watchlist_132_cf76964799db4ce dauerhaft entfernt

DELETE https://<ihr-shop>.de/api/v1/watchList/delete

Beispiel-Request

{
  "watchListId": "watchlist_132_cf76964799db4ce"
}

Parameterübersicht

Header-Parameter

Parameter	Beschreibung
`x-session`	Pflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

Body-Parameter

Parameter	Typ	Beschreibung
`watchListId`	string	Pflichtfeld ID der zu löschenden Merkliste.

Beispiel-Response

{}

Fehlercodes

Parameter	Beschreibung
`watchListNotFound`	Die angegebene Merkliste existiert nicht.
`notChangeable`	Die Merkliste darf nicht gelöscht werden (gilt für die automatisch erstellten Standardmerklisten `…_default` und `…_basket`).
`missingService`	Der Merklisten-Dienst ist nicht verfügbar.

​Unterstützte Methoden

​Methoden für die Merkliste

​watchList/load

​Parameterübersicht

​Header-Parameter

​Query-Parameter

​Beispiel-Response

​GET watchList/list

​Parameterübersicht

​Header-Parameter

​Beispiel-Response

​GET watchList/getItemId

​Parameterübersicht

​Header-Parameter

​Query-Parameter

​Beispiel-Response

​GET watchList/checkHasProduct

​Parameterübersicht

​Header-Parameter

​Query-Parameter

​Beispiel-Response

​HTTP-Status

​GET watchList/countListsWithProduct

​Parameterübersicht

​Header-Parameter

​Query-Parameter

​Beispiel-Response

​POST watchList/add

​Beispiel-Request

​Parameterübersicht

​Header-Parameter

​Body-Parameter

​Beispiel-Response

​Fehlercodes

​PUT watchList/addItem

​Beispiel-Request

​Parameterübersicht

​Header-Parameter

​Body-Parameter

​Beispiel-Response

​Fehlercodes

​PUT watchList/rename

​Beispiel-Request

​Parameterübersicht

​Header-Parameter

​Body-Parameter

​Beispiel-Response

​Fehlercodes

​DELETE watchList/deleteItem

​Beispiel-Request

​Parameterübersicht

​Header-Parameter

​Body-Parameter

​Beispiel-Response

​Fehlercodes

​DELETE watchList/delete

​Beispiel-Request

​Parameterübersicht

​Header-Parameter

​Body-Parameter

​Beispiel-Response

​Fehlercodes

Unterstützte Methoden

Methoden für die Merkliste

watchList/load

Parameterübersicht

Header-Parameter

Query-Parameter

Beispiel-Response

GET watchList/list

Parameterübersicht

Header-Parameter

Beispiel-Response

GET watchList/getItemId

Parameterübersicht

Header-Parameter

Query-Parameter

Beispiel-Response

GET watchList/checkHasProduct

Parameterübersicht

Header-Parameter

Query-Parameter

Beispiel-Response

HTTP-Status

GET watchList/countListsWithProduct

Parameterübersicht

Header-Parameter

Query-Parameter

Beispiel-Response

POST watchList/add

Beispiel-Request

Parameterübersicht

Header-Parameter

Body-Parameter

Beispiel-Response

Fehlercodes

PUT watchList/addItem

Beispiel-Request

Parameterübersicht

Header-Parameter

Body-Parameter

Beispiel-Response

Fehlercodes

PUT watchList/rename

Beispiel-Request

Parameterübersicht

Header-Parameter

Body-Parameter

Beispiel-Response

Fehlercodes

DELETE watchList/deleteItem

Beispiel-Request

Parameterübersicht

Header-Parameter

Body-Parameter

Beispiel-Response

Fehlercodes

DELETE watchList/delete

Beispiel-Request

Parameterübersicht

Header-Parameter

Body-Parameter

Beispiel-Response

Fehlercodes