Storefront API Warenkorb

Die Warenkorb API steuert sämtliche Interaktionen rund um den Warenkorb: Artikel können hinzugefügt, Mengen geändert und Positionen entfernt werden. Zusätzlich stellt die API die Warenkorbinhalte inklusive Summen, Rabatten und Regeln wie Mindestbestellwerten oder Maximalbestellmengen bereit. Gutscheincodes lassen sich im Warenkorb erfassen, aktualisieren oder entfernen; die Auswirkungen auf Rabatte und Summen werden entsprechend zurückgegeben. Je nach Konfiguration können auch Versandkosten bereits im Warenkorb vorab berechnet und angezeigt werden, damit frühzeitig Transparenz über die zu erwartenden Kosten besteht. Die Schnittstelle liefert konsistente JSON-Antworten und informiert bei fehlerhaften Aktionen über eindeutige Fehlercodes (z. B. fehlende oder ungültige Produkt-/Positions-IDs, Mengenbeschränkungen, gesperrte Änderungen) inklusive Detailangaben, die eine schnelle Ursachenanalyse ermöglichen. Für die korrekte Verwaltung des Warenkorbs muss eine Session per x-session übermittelt werden. Mehr dazu hier.

Unterstützte Methoden

Angabe aller Unterstützten Methoden.

Befehl	Endpunkte	GET	PUT	POST	DELETE
Warenkorb lesen	`basket/item/get`
Produkt(e) hinzufügen	`basket/item/add`
Warenkorbposition ändern	`basket/item/update`
Warenkorbposition entfernen	`basket/item/delete`
Werbemittelkennzeichen-Konfiguration lesen	`config/inserts`

Methoden für den Warenkorb

Diese Methoden steuern den Warenkorb im Shop. Sie können den aktuellen Warenkorb auslesen, Produkte in der gewünschten Menge hinzufügen, bestehende Positionen ändern oder wieder entfernen.

GET basket/item/get

Der folgende Aufruf liefert den aktuellen Warenkorb mit allen Positionen und Summen (Netto/Brutto/Steuer). Die Daten unter „items[].product” repräsentieren den Zustand des Produkts zum Zeitpunkt, als es in den Warenkorb gelegt wurde. Ändert sich beispielsweise der Preis während des Bezahlvorgangs, wird die Bestellung trotzdem zum ursprünglichen, im Warenkorb gespeicherten Preis abgeschlossen. So werden Fehler oder Nachberechnungen verhindert. Welche Produktdaten in „items[].product” enthalten sind, wird in der Konfiguration der benutzerdefinierten Produktfelder festgelegt. Mehr dazu hier: content - Katalog (Kategorien & Produkte).
Dieser Befehl kann zum Anzeigen des Warenkorbs verwendet werden. Beispiel-Aufruf für das Anzeigen des aktuellen Warenkorbs

GET https://<ihr-shop>.de/api/v1/basket/item/get

Parameterübersicht

Header-Parameter

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

Beispiel Response

{
  "items": [
    {
      "id": "0921e5b44dcd6034248f",
      "quantity": 1,
      "price": 59.99,
      "total": 59.99,
      "totalNet": 50.41,
      "totalTax": 9.58,
      "product": {
        "id": "155-03082",
        "name": "Wollmantel mit Bindegürtel",
        "price": 59.99
      }
    },
    {
      "id": "0d1b062c8225f817aa3e",
      "quantity": 3,
      "price": 499.99,
      "total": 1499.97,
      "totalNet": 1260.48,
      "totalTax": 239.49,
      "product": {
        "id": "179-33468",
        "name": "Handtasche",
        "price": 499.99
      }
    }
  ],
  "lastBasketAction": "add",
  "lastUpdatedItem": {
    "id": "179-33468",
    "price": 499.99,
    "quantity": 3,
    "taxId": "19"
  },
  "totalQuantity": 4,
  "total": 1559.96,
  "totalGross": 1559.96,
  "totalNet": 1310.89,
  "totalTax": 249.07,
  "totalTaxDeduction": 19.99,
  "isTaxExempt": true,
  */ je nachdem, was das Template angibt, kann bei den folgenden zwei Werten
  entweder der isoAlpha2, isoAlpha3 oder isoNum Code vorkommen */
  "billingCountry": "DE" , | "DEU", | "276", 
  "shippingCountry": "DE" , | "DEU", | "276", 
  "usedExemptionRule": "shippingOnly"
}

POST basket/item/add

Mit diesem Aufruf wird ein Produkt in der gewünschten Menge in den Warenkorb gelegt. Durch mehrmaliges Ausführen des Befehls können mehrere Produkte hinzugefügt werden. Der Befehl kann verwendet werden, um ein Produkt zum Warenkorb hinzuzufügen. Falls mehrere Produkte hinzugefügt werden sollen, muss der Befehl entsprechend oft ausgeführt werden. Beispiel-Aufruf für das Hinzufügen von drei Einheiten des Produktes mit der ID 71-3953und der Geschenknachricht “Alles Gute!” zum Warenkorb

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

Beispiel Request

{
  "productId": "71-3953",
  "quantity": 3,
  "insert": "09",
  "freeFields": {
    "giftMessage": "Alles Gute!"
  }
}

Parameterübersicht

Header-Parameter

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

Body-Parameter

Parameter	Typ	Beschreibung
`productId`	string	ID des Produkts, das in den Warenkorb gelegt werden soll.
`quantity`	int	Gibt an, wie oft das Produkt in den Warenkorb gelegt werden soll.
`insert`	string	Optionales Werbemittelkennzeichen für die Position. Ist die Funktion aktiv, wird der Code serverseitig gegen die für das Produkt gültigen Codes geprüft: Bei einem gültigen Code wird er übernommen, andernfalls greift der konfigurierte Standardcode. Ist die Funktion inaktiv, wird der Wert ignoriert.
`freeFields`	Objekt (String → String)	Freie Schlüssel/Wert-Paare, die an der Position angehängt und in die Bestelldaten exportiert werden können.

Beispiel Response

{
  "basket": {
    "items": [
      {
        "id": "f28e67292c99759e5fb9",
        "quantity": 3,
        "price": 139,
        "insert": "09",
        "itemNumberWithInsert": "71-3953-09",
        "total": 417,
        "totalNet": 350.42,
        "totalTax": 66.58,
        "freeFields": {
          "giftMessage": "Alles Gute!"
        },
        "product": {
          "id": "71-3953",
          "name": "Beispielprodukt",
          "price": 139,
          "taxRateId": "1",
          "custom": {
            "...": "benutzerdefinierte Produktfelder laut Konfiguration"
          }
        }
      }
    ],
    "totalQuantity": 3,
    "total": 417,
    "totalGross": 417,
    "totalNet": 350.42,
    "totalTax": 66.58
  }
}

Fehlercodes

Fehlercode	Beschreibung
`invalidProductId`	Das angefragte Produkt existiert nicht.
`invalidVariantId`	Die angefragte Variante existiert nicht.
`insufficientAmount`	Es sind nicht genügend Produkte auf Lager.
`quantityExceeded`	Die maximal erlaubte Anzahl für dieses Produkt wurde überschritten (zusätzliche Details unter “details” - siehe unten).
`childProductOnly`	Das Produkt kann nur als Bestandteil eines Sets bestellt werden.
`expressCheckoutNotAllowed`	PayPal Express Checkout ist aktiv - der Warenkorb darf aktuell nicht verändert werden.
`noVariantFound`	Für ein Variantenprodukt wurde keine Variante angegeben (Produkt-ID enthält keine Variantenauswahl).

PUT basket/item/update

Mit folgendem Aufruf kann man eine bestehende Warenkorb-Position aktualisieren bzw. ändern, typischerweise die Menge. Er ist für Mengenänderungen im Warenkorb verwendbar. Beispiel-Aufruf für das ändern der Warenkorbposition mit der ID 0921e5b44dcd6034248fauf die Menge 2

PUT https://<ihr-shop>.de/api/v1/basket/item/update

Beispiel-Request (Menge einer Position auf 2 reduzieren)

{
  "basketItemId": "0921e5b44dcd6034248f",
  "quantity": 2
}

Hinweis: Wenn quantity auf 0 gesetzt wird, wird die Position aus dem Warenkorb entfernt. Alternativ kann die Position auch über DELETE basket/delete gelöscht werden.

Parameterübersicht

Header-Parameter

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

Body-Parameter

Parameter	Typ	Beschreibung
`basketItemId`	string	Pflichtfeld ID der Warenkorb-Position (entspricht `items[].id` aus dem Warenkorb.
`quantity`	int	Pflichtfeld Neue Menge der Position.
`productId`	string	Ändert in einer bestehenden Warenkorb-Position das zugehörige Produkt (z.B. wechsel der Größe / Farbe / Variante). Beispiel: T-Shirt M → T-Shirt L (gleiches Modell, andere Variante)
`insert`	string	Setzt oder ändert das Werbemittelkennzeichen der Position. Verhält sich wie beim Hinzufügen: gültiger Code wird übernommen, sonst greift der Standardcode; bei inaktiver Funktion wird der Wert ignoriert.
`freeFields`	Object (String → String)	Neue freie Schlüssel/Werte-Paare für die Position (werden in Bestelldaten exportiert). Beispiel: Personalisierung des Produkts. `"freeFields": { "engraving": "A.K.", "giftMessage": "Alles Gute!", "costCenter": "MKT-2025-11", "configId": "cfg_7f2a9" }`

Beispiel-Response

{
  "basket": {
    "items": [
      {
        "id": "0921e5b44dcd6034248f",
        "quantity": 2.0,
        "price": 59.99,
        "total": 119.98,
        "totalGross": 119.98,
        "totalNet": 100.82,
        "totalTax": 19.16,
        "freeFields": {},
        "product": {
          "id": "155-03082",
          "name": "Wollmantel mit Bindegürtel",
          "price": 59.99
        },
        "voucherIds": []
      },
      {
        "id": "0d1b062c8225f817aa3e",
        "quantity": 3.0,
        "price": 499.99,
        "total": 1499.97,
        "totalGross": 1499.97,
        "totalNet": 1260.48,
        "totalTax": 239.49,
        "freeFields": {},
        "product": {
          "id": "179-33468",
          "name": "Handtasche",
          "price": 499.99
        },
        "voucherIds": []
      }
    ],
    "lastBasketAction": "update",
    "lastUpdatedItem": {
      "id": "155-03082",
      "price": 59.99,
      "quantity": 2.0,
      "taxId": "19",
      "voucherIds": []
    },
    "totalQuantity": 5.0,
    "total": 1619.95,
    "totalGross": 1619.95,
    "totalNet": 1361.3,
    "totalTax": 258.65,
    "totalCommission": 0.0,
    "totalWeight": 0.0
  }
}

Fehlercodes

Fehlercode	Beschreibung
`invalidBasketItemId`	Die angegebene Positions-ID gehört nicht zum aktuellen Warenkorb.
`insufficientAmount`	Nicht genügend Bestand, um die gewünschte Menge zu setzen.
`quantityExceeded`	Die maximal erlaubte Anzahl für dieses Produkt wurde überschritten. Zusätzliche Details siehe unten.
`itemNotChangeable`	Die Position darf nicht verändert werden (z.B. automatisch hinzugefügter Artikel)
`invalidChildItem`	Das angefragte Produkt ist ein Set und verweist auf ein nicht existentes Set-Unterprodukt (Datenfehler zum Produkt).
`expressCheckoutNotAllowed`	Ein Express-Checkout ist aktiv - der Warenkorb darf aktuell nicht verändert werden.

DELETE basket/item/delete

Mit folgendem Aufruf kann eine bestehende Warenkorb-Position dauerhaft entfernt werden. Mit diesem Befehl können Artikel aus dem Warenkorb entfernt werden. Beispiel-Aufruf für das Löschen des Produktes mit der Item-ID 0d1b062c8225f817aa3e

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

Beispiel-Request

{
  "basketItemId": "0d1b062c8225f817aa3e"
}

Parameterübersicht

Header-Parameter

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

Body-Parameter

Parameter	Typ	Beschreibung
`basketItemId`	String	Pflichtfeld ID der Warenkorb-Position (entspricht `items[].id` im Warenkorb).

Beispiel-Response

{
  "basket": {
    "items": [],
    "lastBasketAction": "delete",
    "lastUpdatedItem": {
      "id": "0d1b062c8225f817aa3e",
      "price": 499.99,
      "quantity": 0.0,
      "taxId": "19",
      "voucherIds": []
    },
    "total": 0.0,
    "totalCommission": 0.0,
    "totalGross": 0.0,
    "totalNet": 0.0,
    "totalQuantity": 0.0,
    "totalTax": 0.0,
    "totalWeight": 0.0
  }
}

Fehlercodes

Fehlercode	Beschreibung
`invalidBasketItemId`	Die angegebene ID gehört nicht zum aktuellen Warenkorb.
`basketItemIsSetChild`	Es wurde versucht, einen Set-Unterartikel einzeln zu entfernen. Unterartikel werden automatisch mit dem zugehörigen Set-Oberartikel entfernt und können nicht separat gelöscht werden.
`itemNotRemovable`	Die Position darf nicht entfernt werden (z.B. automatisch hinzugefügter Artikel).
`expressCheckoutNotAllowed`	PayPal Express ist aktiv - der Warenkorb darf derzeit nicht verändert werden.

Methoden für die Konfiguration

GET config/inserts

Der folgende Aufruf liefert die aktuelle Konfiguration der Werbemittelkennzeichnung. Nutzen Sie ihn, um in einer Storefront-Anwendung zu entscheiden, ob ein Eingabefeld für das Werbemittelkennzeichen angezeigt wird und wie die Anzeige aus Produktnummer und Code zusammengesetzt ist. Beispiel-Aufruf

GET https://<ihr-shop>.de/api/v1/config/inserts

Parameterübersicht

Header-Parameter

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

Beispiel Response

{
  "enabled": true,
  "defaultInsertCode": "",
  "separator": "-",
  "position": "after"
}

Feld	Typ	Beschreibung
`enabled`	bool	Ob die Werbemittelkennzeichnung im Shop aktiv ist.
`defaultInsertCode`	string	Standardcode, der greift, wenn kein oder ein ungültiger Code erfasst wurde. Kann leer sein.
`separator`	string	Trennzeichen zwischen Produktnummer und Code (beispielsweise `-`).
`position`	string	Position des Codes relativ zur Produktnummer: `before` oder `after`.

Schnittstellen

Admin Interface API

Storefront API

Weitere

Unterstützte Methoden

Methoden für den Warenkorb

GET basket/item/get

Parameterübersicht

Header-Parameter

Beispiel Response

POST basket/item/add

Beispiel Request

Parameterübersicht

Header-Parameter

Body-Parameter

Beispiel Response

Fehlercodes

PUT basket/item/update

Beispiel-Request (Menge einer Position auf 2 reduzieren)

Parameterübersicht

Header-Parameter

Body-Parameter

Beispiel-Response

Fehlercodes

DELETE basket/item/delete

Beispiel-Request

Parameterübersicht

Header-Parameter

Body-Parameter

Beispiel-Response

Fehlercodes

Methoden für die Konfiguration

GET config/inserts

Parameterübersicht

Header-Parameter

Beispiel Response

​Unterstützte Methoden

​Methoden für den Warenkorb

​GET basket/item/get

​Parameterübersicht

​Header-Parameter

​Beispiel Response

​POST basket/item/add

​Beispiel Request

​Parameterübersicht

​Header-Parameter

​Body-Parameter

​Beispiel Response

​Fehlercodes

​PUT basket/item/update

​Beispiel-Request (Menge einer Position auf 2 reduzieren)

​Parameterübersicht

​Header-Parameter

​Body-Parameter

​Beispiel-Response

​Fehlercodes

​DELETE basket/item/delete

​Beispiel-Request

​Parameterübersicht

​Header-Parameter

​Body-Parameter

​Beispiel-Response

​Fehlercodes

​Methoden für die Konfiguration

​GET config/inserts

​Parameterübersicht

​Header-Parameter

​Beispiel Response

Unterstützte Methoden

Methoden für den Warenkorb

GET basket/item/get

Parameterübersicht

Header-Parameter

Beispiel Response

POST basket/item/add

Beispiel Request

Parameterübersicht

Header-Parameter

Body-Parameter

Beispiel Response

Fehlercodes

PUT basket/item/update

Beispiel-Request (Menge einer Position auf 2 reduzieren)

Parameterübersicht

Header-Parameter

Body-Parameter

Beispiel-Response

Fehlercodes

DELETE basket/item/delete

Beispiel-Request

Parameterübersicht

Header-Parameter

Body-Parameter

Beispiel-Response

Fehlercodes

Methoden für die Konfiguration

GET config/inserts

Parameterübersicht

Header-Parameter

Beispiel Response