Zum Hauptinhalt springen
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.
BefehlEndpunkteGETPUTPOSTDELETE
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.

​
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

ParameterBeschreibung
x-sessionPflichtfeld
ID der aktuellen Session.
Mehr Informationen dazu: Storefront API Basics

​
Body-Parameter

ParameterTypBeschreibung
watchListIdstringPflichtfeld
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"
      }
    }
  ]
}

​
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

ParameterBeschreibung
x-sessionPflichtfeld
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

ParameterBeschreibung
x-sessionPflichtfeld
ID der aktuellen Session.
Mehr Informationen dazu: Storefront API Basics

​
Body-Parameter

ParameterTypBeschreibung
watchListIdstringPflichtfeld
ID der Merkliste, in der sich das Produkt befindet.
productIdstringPflichtfeld
ID des Produktes in der Watchlist.

​
Beispiel-Response

{
  "itemId": "6d90bbb6c33294ddcd91"
}

​
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

ParameterBeschreibung
x-sessionPflichtfeld
ID der aktuellen Session.
Mehr Informationen dazu: Storefront API Basics

​
Body-Parameter

ParameterTypBeschreibung
watchListIdstringPflichtfeld ID der Merkliste, die durchsucht werden soll.
productIdstringPflichtfeld ID des Produktes, nach dem gesucht werden soll.

​
Beispiel-Response

{
  "isOnList": true
}

​
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

ParameterBeschreibung
x-sessionPflichtfeld
ID der aktuellen Session.
Mehr Informationen dazu: Storefront API Basics

​
Body-Parameter

ParameterTypBeschreibung
productIdstringPflichtfeld 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

ParameterBeschreibung
x-sessionPflichtfeld ID der aktuellen Session. Mehr Informationen dazu: Storefront API Basics

​
Body-Parameter

ParameterTypBeschreibung
watchListNamestringPflichtfeld
Name der zu erstellenden Watchlist.

​
Beispiel-Response

{}

​
Fehlercodes

CodeBeschreibung
notLoggedInDer Nutzer ist nicht eingeloggt.

​
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": "147-15732",
    "146-78608": "146-78608"
  }
}

​
Parameterübersicht

​
Header-Parameter

ParameterBeschreibung
x-sessionPflichtfeld
ID der aktuellen Session.
Mehr Informationen dazu: Storefront API Basics

​
Body-Parameter

ParameterTypBeschreibung
watchListIdsobjectPflichtfeld Liste der Ziel-Merklisten. Schlüssel und Wert sind die Watchlist-IDs. Es muss mindestens eine ID angegeben werden.
productIdstringEin Produkt, das hinzugefügt werden soll. Pflichtfeld, wenn multiproductsnicht übergeben wird.
multiProductsobjectFügt mehrere Produkte in einem Aufruf hinzu. Schlüssel und Wert sind Produkt-IDs. Pflichtfeld, wenn productId nicht übergeben wird.
freeFieldsobjectOptional. Freie Zusatzdaten zu den Produkten. Bei multiProducts gelten diese Werte für alle hinzugefügten Produkte.

​
Beispiel-Response

{}

​
Fehlercodes

CodeBeschreibung
invalidProductIdDas angefragte Produkt existiert nicht.
invalidVariantIdDas Produkt wurde gefunden, aber die zugehörige Variante nicht.
watchListNotFoundDie angegebene Merkliste existiert nicht.

​
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

ParameterBeschreibung
x-sessionPflichtfeld
ID der aktuellen Session.
Mehr Informationen dazu: Storefront API Basics

​
Body-Parameter

ParameterTypBeschreibung
watchListIdstringPflichtfeld ID der umzubenennenden Merkliste.
newWatchListNamestringPflichtfeld Neuer Name für die Merkliste.

​
Beispiel-Response

{}

​
Fehlercodes

CodeBeschreibung
watchListNotFoundDie Merkliste mit der angegebenen ID existiert nicht.Die Merkliste mit der angegebenen ID existiert nicht.
notChangeablenotChangeableDie Merkliste darf nicht umbenannt werden. (Die Merkliste darf nicht umbenannt werden. (nur für die automatisch erstellten Standardmerklisten aktiv)

​
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

ParameterBeschreibung
x-sessionPflichtfeld
ID der aktuellen Session.
Mehr Informationen dazu: Storefront API Basics

​
Body-Parameter

ParameterTypBeschreibung
watchListIdstringPflichtfeld ID der Watchlist, aus der der Eintrag entfernt werden soll.
watchListItemIdstringPflichtfeld Positions-ID des zu entfernenden Produktes.

​
Beispiel-Response

{}

​
Fehlercodes

ParameterCode
invalidItemIdEs existiert kein Eintrag mit dieser ID auf der Merkliste.
watchListNotFoundDie Merkliste mit der angegebenen ID existiert nicht.

​
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

ParameterBeschreibung
x-sessionPflichtfeld
ID der aktuellen Session.
Mehr Informationen dazu: Storefront API Basics

​
Body-Parameter

ParameterTypBeschreibung
watchListIdstringPflichtfeld ID der zu löschenden Merkliste.

​
Beispiel-Response

{}

​
Fehlercodes

ParameterBeschreibung
watchListNotFoundDie angegebene Merkliste existiert nicht.
notChangeableDie Merkliste darf nicht umbenannt werden. (Die Merkliste darf nicht umbenannt werden. (nur für die automatisch erstellten Standardmerklisten aktiv)