> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Storefront API Warenkorb

> Warenkorb der Storefront über die Storefront API steuern: Artikel hinzufügen, Mengen ändern, Positionen entfernen, Gutscheine und Summen pflegen.

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](/schnittstellen/storefront-api/storefront-api-basics).

***

## Unterstützte Methoden

Angabe aller Unterstützten Methoden.

| **Befehl**                  | **Endpunkte**        | **GET**               | **PUT**               | **POST**              | **DELETE**            |
| --------------------------- | -------------------- | --------------------- | --------------------- | --------------------- | --------------------- |
| Warenkorb lesen             | `basket/item/get`    | <Icon icon="check" /> | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="ban" />   |
| Produkt(e) hinzufügen       | `basket/item/add`    | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="check" /> | <Icon icon="ban" />   |
| Warenkorbposition ändern    | `basket/item/update` | <Icon icon="ban" />   | <Icon icon="check" /> | <Icon icon="ban" />   | <Icon icon="ban" />   |
| Warenkorbposition entfernen | `basket/item/delete` | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="check" /> |

## 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)](https://websaleag-44ee7ea6.mintlify.app/konfiguration/content-katalog-kategorien-produkte#6-content-customproductfield-benutzerdefinierte-produktfelder).\
Dieser Befehl kann zum Anzeigen des Warenkorbs verwendet werden.

**Beispiel-Aufruf für das Anzeigen des aktuellen Warenkorbs**

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<ihr-shop>.de/api/v1/basket/item/get
```

#### Parameterübersicht

#### Header-Parameter

| **Parameter** | **Typ** | **Beschreibung**                                                                                                                                              |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session`   | string  | **Pflichtfeld**<br />ID der aktuellen Session.   <br />Mehr Informationen dazu: [Storefront API Basics](/schnittstellen/storefront-api/storefront-api-basics) |

#### Beispiel Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "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-3953`**und der Geschenknachricht “Alles Gute!” zum Warenkorb**

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
POST https://<ihr-shop>.de/api/v1/basket/item/add
```

#### Beispiel Request

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "productId": "71-3953",
  "quantity": 3,
  "freeFields": {
    "giftMessage": "Alles Gute!"
  }
}
```

#### Parameterübersicht

#### Header-Parameter

| **Parameter** | **Beschreibung**                                                                                                                                              |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session`   | **Pflichtfeld**<br />ID der aktuellen Session.   <br />Mehr Informationen dazu: [Storefront API Basics](/schnittstellen/storefront-api/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.                                           |
| `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

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "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

| **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** `0921e5b44dcd6034248f`**auf die Menge 2**

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
PUT https://<ihr-shop>.de/api/v1/basket/item/update
```

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "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](../storefront-api/storefront-api-basics.md#2-session-handling) |

#### 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)                                                                                                 |
| `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

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "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`

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
DELETE https://<ihr-shop>.de/api/v1/basket/item/delete
```

#### Beispiel-Request

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "basketItemId": "0d1b062c8225f817aa3e"
}
```

#### Parameterübersicht

#### Header-Parameter

| **Parameter** | **Beschreibung**                                                                                                                                                                                               |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session`   | **Pflichtfeld**   ID der aktuellen Session.   Mehr Informationen dazu: [Storefront API Basics](https://websaleag-44ee7ea6.mintlify.app/schnittstellen/storefront-api/storefront-api-basics#3-session-handling) |

#### Body-Parameter

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

#### Beispiel-Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "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.                                                                                                          |