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. Versandkosten sind nicht Teil der Warenkorb-Antwort. total, totalNet, totalGross und totalTax sind reine Warenwert-Zwischensummen ohne Versand-, Zahlarten- und Zuschlagskosten sowie ohne Gutscheinabzug. Versandkosten (shippingCost), Zahlartenkosten (paymentCost), Zuschläge (surchargeCost), den Gutscheinabzug (totalVoucher) und die Endsumme liefern die Checkout-Endpunkte im Objekt sum. 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/items/add`
Warenkorbposition ändern	`basket/items/update`
Warenkorbposition entfernen	`basket/item/delete`
Werbemittelkennzeichen-Konfiguration lesen	`config/inserts`

Fehlerformat

Alle Fehler werden mit HTTP 400 und folgendem Rumpf beantwortet:

{
  "error": "actionFailed",
  "detail": "Action Failed",
  "actionErrors": [
    { "code": "invalidProductId", "subCode": "", "field": "productId", "text": "…", "details": {} }
  ]
}

error = invalidParameters bei Fehlern in Parametern/Feldtypen (Details in paramErrors, Schlüssel = Parametername, Wert {"type": "missing" | "invalidFormat" | "invalidValue" | "unknownField" | …}).
error = actionFailed bei fachlichen Fehlern. Die in den folgenden Tabellen genannten Fehlercodes stehen dann in actionErrors[].code.
Ein Aufruf mit falscher HTTP-Methode wird mit HTTP 404 beantwortet (nicht 405).
Fehlt die Session (x-session), wird mit HTTP 400 geantwortet.

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,
  "billingCountry": "DE",
  "shippingCountry": "DE",
  "usedExemptionRule": "shippingOnly"
}

billingCountry und shippingCountry sind jeweils ein einzelner Länder-Code als String. Welches Format geliefert wird (isoAlpha2 = DE, isoAlpha3 = DEU oder isoNum = 276), hängt von der Shop-Konfiguration ab. lastBasketAction kennzeichnet die zuletzt ausgeführte Änderung. Mögliche Werte: add, delete, unknown. Eine Mengenänderung setzt je nach Ergebnis add oder delete. Den Wert update gibt es nicht. lastUpdatedItem beschreibt die zuletzt geänderte Position. Achtung: lastUpdatedItem.id enthält die Produkt-ID, nicht die Warenkorbpositions-ID aus items[].id. Weitere Felder: productNumber, categories (string[]), parentCategories (string[]), freeFields, voucherIds.

POST basket/items/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/items/add

Wird dasselbe Produkt (gleiche Variante und gleiche freeFields) mehrfach hinzugefügt, entsteht keine zweite Warenkorbposition: Die Menge der bestehenden Position wird um quantity erhöht und ihre items[].id bleibt unverändert. Set-Produkte werden nie zusammengeführt.

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	Pflichtfeld ID des Produkts, das in den Warenkorb gelegt werden soll.
`quantity`	int	Pflichtfeld Gibt an, wie oft das Produkt in den Warenkorb gelegt werden soll.
`insert`	string	Optionales Werbemittelkennzeichen. 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. Ein übergebener Code wird zusätzlich als sessionweiter Code gespeichert und gilt als Vorgabe für alle danach hinzugefügten Positionen. Wird `insert` weggelassen, greift der zuletzt gesetzte sessionweite Code. 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.

Es sind ausschließlich die oben genannten Felder erlaubt. Jedes weitere Feld im Request-Body führt zu HTTP 400 mit error: "invalidParameters" und einem Eintrag unknownField in paramErrors. Hinweis zu Set-Produkten: Der Endpunkt akzeptiert ausschließlich die vier oben genannten Felder. Jedes weitere Feld wird mit unknownField abgelehnt. Die Variantenauswahl für Set-Unterartikel (setChildVar_<childId>) kann daher derzeit nicht übergeben werden. Set-Produkte, deren Unterartikel Varianten haben, sind über die Storefront-API nicht bestellbar.

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
  }
}

Jede Position in items[] kann außerdem folgende Felder enthalten:

Feld	Typ	Beschreibung
`id`	string	ID der Warenkorbposition (für `update`/`delete`).
`quantity`	float	Menge der Position.
`price`	float	Einzelpreis der Position.
`orgPrice`	float	Ursprünglicher Einzelpreis vor Rabatt.
`discountPrice`	float	Rabattbetrag der Position.
`total` / `totalGross` / `totalNet` / `totalTax`	float	Positionssumme brutto/netto/Steueranteil.
`oneTimeFee`	float	Einmalgebühr der Position.
`insert`	string	Aufgelöstes Werbemittelkennzeichen der Position.
`itemNumberWithInsert`	string	Produktnummer inklusive Werbemittelkennzeichen.
`freeFields`	Objekt (String → String)	Freie Felder der Position.
`voucherIds`	string[]	IDs der zu dieser Position generierten Gutscheine (Gutscheinprodukte).
`isSetProduct`	bool	Nur bei Set-Oberartikeln vorhanden und dann `true`.
`isSetChild`	bool	Nur bei Set-Unterartikeln vorhanden und dann `true`.
`parentBasketItemId`	string	Nur bei Set-Unterartikeln: ID des Set-Oberartikels.
`product`	Objekt	Produktdaten zum Zeitpunkt der Warenkorbaufnahme.

Nicht sichtbare Positionen (isVisible = false) und ausgeblendete Set-Unterartikel erscheinen nicht in items.

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

Bei quantityExceeded enthält details die Felder productId (betroffene Produkt-ID), quantity (angeforderte Gesamtmenge) und maxQuantity (global konfigurierte Höchstmenge pro Position). subCode enthält die Produkt-ID, field den Wert quantity. Zusätzlich zur globalen Höchstmenge kann ein Produkt über das Produktfeld für die Maximalmenge eine niedrigere Grenze haben.

PUT basket/items/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/items/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: Ein gültiger Code wird übernommen, sonst greift der Standardcode. Ein übergebener Code wird außerdem als sessionweiter Code für nachfolgende Positionen gespeichert. 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" }`

Es sind ausschließlich die oben genannten Felder erlaubt. Jedes weitere Feld im Request-Body führt zu HTTP 400 mit error: "invalidParameters" und einem Eintrag unknownField in paramErrors.

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": []
      }
    ],
    "totalQuantity": 5.0,
    "total": 1619.95,
    "totalGross": 1619.95,
    "totalNet": 1361.3,
    "totalTax": 258.65
  }
}

lastBasketAction, lastUpdatedItem, totalCommission und totalWeight liefert nur der Lese-Endpunkt GET basket/items/get. Die Felder der Positionen in items[] entsprechen denen bei POST basket/items/add, siehe dort.

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)
`invalidProductId`	Die Produkt-ID existiert nicht, oder ein Set verweist auf ein nicht existentes Set-Unterprodukt bzw. eine nicht existente Unterartikel-Variante.
`expressCheckoutNotAllowed`	Ein Express-Checkout ist aktiv - der Warenkorb darf aktuell nicht verändert werden.
`basketLocked`	Der Warenkorb ist gesperrt (beispielsweise durch einen Freigabeprozess bei Sub-Accounts) und darf nicht verändert werden.
`missingBasketItemId`	`basketItemId` wurde nicht übergeben oder ist leer.
`invalidQuantity`	Die Menge ist keine positive Ganzzahl (bzw. 0 bei erlaubtem Entfernen) oder die Position ist ein Set-Unterartikel, dessen Menge nicht direkt geändert werden darf.
`internalError`	Ein Set-Produkt konnte beim Neuaufbau nicht gespeichert 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.
`invalidChildItemDelete`	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. (`field` = `childItemDelete`)
`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.
`basketLocked`	Der Warenkorb ist gesperrt (beispielsweise durch einen Freigabeprozess bei Sub-Accounts) und darf nicht verändert werden.
`missingBasketItemId`	`basketItemId` wurde nicht übergeben oder ist leer.

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

Dieser Endpunkt benötigt keine Session. Der Header x-session ist optional und wird ignoriert.

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

Fehlerformat

Methoden für den Warenkorb

GET basket/item/get

Parameterübersicht

Header-Parameter

Beispiel Response

POST basket/items/add

Beispiel Request

Parameterübersicht

Header-Parameter

Body-Parameter

Beispiel Response

Fehlercodes

PUT basket/items/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

​Fehlerformat

​Methoden für den Warenkorb

​GET basket/item/get

​Parameterübersicht

​Header-Parameter

​Beispiel Response

​POST basket/items/add

​Beispiel Request

​Parameterübersicht

​Header-Parameter

​Body-Parameter

​Beispiel Response

​Fehlercodes

​PUT basket/items/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

Fehlerformat

Methoden für den Warenkorb

GET basket/item/get

Parameterübersicht

Header-Parameter

Beispiel Response

POST basket/items/add

Beispiel Request

Parameterübersicht

Header-Parameter

Body-Parameter

Beispiel Response

Fehlercodes

PUT basket/items/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