Zum Hauptinhalt springen
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.
BefehlEndpunkteGETPUTPOSTDELETE
Warenkorb lesenbasket/item/get
Produkt(e) hinzufügenbasket/item/add
Warenkorbposition ändernbasket/item/update
Warenkorbposition entfernenbasket/item/delete

​
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

ParameterTypBeschreibung
x-sessionstringPflichtfeld
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,
  "freeFields": {
    "giftMessage": "Alles Gute!"
  }
}

​
Parameterübersicht

​
Header-Parameter

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

​
Body-Parameter

ParameterTypBeschreibung
productIdstringID des Produkts, das in den Warenkorb gelegt werden soll.
quantityintGibt an, wie oft das Produkt in den Warenkorb gelegt werden soll.
freeFieldsObjekt (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,
        "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

FehlercodeBeschreibung
invalidProductIdDas angefragte Produkt existiert nicht.
invalidVariantIdDie angefragte Variante existiert nicht.
insufficientAmountEs sind nicht genügend Produkte auf Lager.
quantityExceededDie maximal erlaubte Anzahl für dieses Produkt wurde überschritten (zusätzliche Details unter “details” - siehe unten).
childProductOnlyDas Produkt kann nur als Bestandteil eines Sets bestellt werden.
expressCheckoutNotAllowedPayPal Express Checkout ist aktiv - der Warenkorb darf aktuell nicht verändert werden.
noVariantFoundFü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

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

​
Body-Parameter

ParameterTypBeschreibung
basketItemIdstringPflichtfeld ID der Warenkorb-Position (entspricht items[].id aus dem Warenkorb.
quantityintPflichtfeld Neue Menge der Position.
productIdstringÄ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)
freeFieldsObject (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

FehlercodeBeschreibung
invalidBasketItemIdDie angegebene Positions-ID gehört nicht zum aktuellen Warenkorb.
insufficientAmountNicht genügend Bestand, um die gewünschte Menge zu setzen.
quantityExceededDie maximal erlaubte Anzahl für dieses Produkt wurde überschritten. Zusätzliche Details siehe unten.
itemNotChangeableDie Position darf nicht verändert werden (z.B. automatisch hinzugefügter Artikel)
invalidChildItemDas angefragte Produkt ist ein Set und verweist auf ein nicht existentes Set-Unterprodukt (Datenfehler zum Produkt).
expressCheckoutNotAllowedEin 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

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

​
Body-Parameter

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

FehlercodeBeschreibung
invalidBasketItemIdDie angegebene ID gehört nicht zum aktuellen Warenkorb.
basketItemIsSetChildEs 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.
itemNotRemovableDie Position darf nicht entfernt werden (z.B. automatisch hinzugefügter Artikel).
expressCheckoutNotAllowedPayPal Express ist aktiv - der Warenkorb darf derzeit nicht verändert werden.