> ## 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 Shopping Cart
> Control the storefront cart via the Storefront API: add items, change quantities, remove positions, manage insert codes, vouchers, and totals.
The Shopping Cart API controls all interactions around the shopping cart: items can be added, quantities changed, and positions removed.
In addition, the API provides the cart contents including totals, discounts, and rules such as minimum order values or maximum order quantities. Voucher codes can be entered, updated, or removed in the cart; the effects on discounts and totals are returned accordingly. Depending on the configuration, shipping costs can also be pre-calculated and displayed in the cart in advance so that there is early transparency about the expected costs.
The interface delivers consistent JSON responses and informs about incorrect actions via clear error codes (e.g. missing or invalid product/position IDs, quantity limits, blocked changes) including detail information that enables a quick root cause analysis.
For the correct management of the shopping cart, a session must be transmitted via `x-session`. More about this [here](/en/schnittstellen/storefront-api/storefront-api-basics).
***
## Supported methods
List of all supported methods.
| **Command** | **Endpoints** | **GET** | **PUT** | **POST** | **DELETE** |
| ------------------------------ | -------------------- | --------------------- | --------------------- | --------------------- | --------------------- |
| Read cart | `basket/item/get` | | | | |
| Add product(s) | `basket/item/add` | | | | |
| Update cart position | `basket/item/update` | | | | |
| Remove cart position | `basket/item/delete` | | | | |
| Read insert code configuration | `config/inserts` | | | | |
## Methods for the shopping cart
These methods control the shopping cart in the shop. You can read the current cart, add products in the desired quantity, change existing positions, or remove them again.
### GET basket/item/get
The following call returns the current cart with all positions and totals (net/gross/tax).
The data under "`items[].product`" represents the state of the product at the time it was added to the cart. If, for example, the price changes during the payment process, the order is still completed at the original price stored in the cart. This prevents errors or recalculations.
Which product data is included in "`items[].product`" is defined in the configuration of the user-defined product fields.
More information here: [content - Catalog (categories & products)](https://websaleag-44ee7ea6.mintlify.app/konfiguration/content-katalog-kategorien-produkte#6-content-customproductfield-benutzerdefinierte-produktfelder).
This command can be used to display the cart.
**Example call for displaying the current cart**
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://.de/api/v1/basket/item/get
```
#### Parameter overview
#### Header parameters
| **Parameter** | **Type** | **Description** |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session` | string | **Required field**
ID of the current session.
More information: [Storefront API Basics](/en/schnittstellen/storefront-api/storefront-api-basics) |
#### Example 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": "Wool coat with tie belt",
"price": 59.99
}
},
{
"id": "0d1b062c8225f817aa3e",
"quantity": 3,
"price": 499.99,
"total": 1499.97,
"totalNet": 1260.48,
"totalTax": 239.49,
"product": {
"id": "179-33468",
"name": "Handbag",
"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,
*/ depending on what the template specifies, the following two values may
contain either the isoAlpha2, isoAlpha3 or isoNum code */
"billingCountry": "DE" , | "DEU", | "276",
"shippingCountry": "DE" , | "DEU", | "276",
"usedExemptionRule": "shippingOnly"
}
```
### POST basket/item/add
This call adds a product in the desired quantity to the cart. By executing the command multiple times, several products can be added. The command can be used to add a product to the cart. If multiple products are to be added, the command must be executed accordingly often.
**Example call for adding three units of the product with the ID** `71-3953` **and the gift message "Best wishes!" to the cart**
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
POST https://.de/api/v1/basket/item/add
```
#### Example request
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"productId": "71-3953",
"quantity": 3,
"insert": "09",
"freeFields": {
"giftMessage": "Best wishes!"
}
}
```
#### Parameter overview
#### Header parameters
| **Parameter** | **Description** |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session` | **Required field**
ID of the current session.
More information: [Storefront API Basics](/en/schnittstellen/storefront-api/storefront-api-basics) |
#### Body parameters
| **Parameter** | **Type** | **Description** |
| ------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `productId` | string | ID of the product to be added to the cart. |
| `quantity` | int | Specifies how many times the product is to be added to the cart. |
| `insert` | string | Optional [insert code](/en/frontend/funktionsubersicht/werbemittelkennzeichnung) for the position. If the feature is active, the code is validated server-side against the codes valid for the product: if the code is valid, it is applied; otherwise, the configured default code is used. If the feature is inactive, the value is ignored. |
| `freeFields` | Object (String → String) | Free key/value pairs that can be attached to the position and exported into the order data. |
#### Example response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"basket": {
"items": [
{
"id": "f28e67292c99759e5fb9",
"quantity": 3,
"price": 139,
"insert": "09",
"itemNumberWithInsert": "71-3953-09",
"total": 417,
"totalNet": 350.42,
"totalTax": 66.58,
"freeFields": {
"giftMessage": "Best wishes!"
},
"product": {
"id": "71-3953",
"name": "Example product",
"price": 139,
"taxRateId": "1",
"custom": {
"...": "user-defined product fields according to configuration"
}
}
}
],
"totalQuantity": 3,
"total": 417,
"totalGross": 417,
"totalNet": 350.42,
"totalTax": 66.58
}
}
```
#### Error codes
| **Error code** | **Description** |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `invalidProductId` | The requested product does not exist. |
| `invalidVariantId` | The requested variant does not exist. |
| `insufficientAmount` | There are not enough products in stock. |
| `quantityExceeded` | The maximum permitted number for this product has been exceeded (additional details under "details" — see below). |
| `childProductOnly` | The product can only be ordered as part of a set. |
| `expressCheckoutNotAllowed` | PayPal Express Checkout is active — the cart may not currently be changed. |
| `noVariantFound` | No variant was specified for a variant product (product ID contains no variant selection). |
### PUT basket/item/update
The following call lets you update or change an existing cart position, typically the quantity. It can be used for quantity changes in the cart.
**Example call for changing the cart position with the ID** `0921e5b44dcd6034248f` **to quantity 2**
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
PUT https://.de/api/v1/basket/item/update
```
#### Example request (reduce quantity of a position to 2)
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"basketItemId": "0921e5b44dcd6034248f",
"quantity": 2
}
```
Note: If `quantity` is set to 0, the position is removed from the cart. Alternatively, the position can also be deleted via `DELETE basket/delete`.
#### Parameter overview
#### Header parameters
| **Parameter** | **Description** |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session` | **Required field** ID of the current session. More information: [Storefront API Basics](../storefront-api/storefront-api-basics.md#2-session-handling) |
#### Body parameters
| **Parameter** | **Type** | **Description** |
| -------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `basketItemId` | string | **Required field** ID of the cart position (corresponds to `items[].id` from the cart). |
| `quantity` | int | **Required field** New quantity of the position. |
| `productId` | string | Changes the associated product in an existing cart position (e.g. change of size / color / variant). Example: T-Shirt M → T-Shirt L (same model, different variant) |
| `insert` | string | Sets or changes the [insert code](/en/frontend/funktionsubersicht/werbemittelkennzeichnung) of the position. Behaves like when adding: a valid code is applied, otherwise the default code is used; if the feature is inactive, the value is ignored. |
| `freeFields` | Object (String → String) | New free key/value pairs for the position (exported into the order data). Example: Personalization of the product. `"freeFields": { "engraving": "A.K.", "giftMessage": "Best wishes!", "costCenter": "MKT-2025-11", "configId": "cfg_7f2a9" }` |
#### Example 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": "Wool coat with tie belt",
"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": "Handbag",
"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
}
}
```
#### Error codes
| **Error code** | **Description** |
| --------------------------- | -------------------------------------------------------------------------------------------------------- |
| `invalidBasketItemId` | The specified position ID does not belong to the current cart. |
| `insufficientAmount` | Not enough stock to set the desired quantity. |
| `quantityExceeded` | The maximum permitted number for this product has been exceeded. See additional details below. |
| `itemNotChangeable` | The position may not be changed (e.g. automatically added item). |
| `invalidChildItem` | The requested product is a set and refers to a non-existent set sub-product (data error on the product). |
| `expressCheckoutNotAllowed` | An Express Checkout is active — the cart may not currently be changed. |
### DELETE basket/item/delete
The following call lets you permanently remove an existing cart position. With this command, items can be removed from the cart.
**Example call for deleting the product with the item ID** `0d1b062c8225f817aa3e`
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
DELETE https://.de/api/v1/basket/item/delete
```
#### Example request
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"basketItemId": "0d1b062c8225f817aa3e"
}
```
#### Parameter overview
#### Header parameters
| **Parameter** | **Description** |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session` | **Required field** ID of the current session. More information: [Storefront API Basics](https://websaleag-44ee7ea6.mintlify.app/schnittstellen/storefront-api/storefront-api-basics#3-session-handling) |
#### Body parameters
| **Parameter** | **Type** | **Description** |
| -------------- | -------- | --------------------------------------------------------------------------------------- |
| `basketItemId` | String | **Required field** ID of the cart position (corresponds to `items[].id` in the cart). |
#### Example 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
}
}
```
#### Error codes
| **Error code** | **Description** |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalidBasketItemId` | The specified ID does not belong to the current cart. |
| `basketItemIsSetChild` | An attempt was made to remove a set sub-item individually. Sub-items are automatically removed together with the corresponding parent set item and cannot be deleted separately. |
| `itemNotRemovable` | The position may not be removed (e.g. automatically added item). |
| `expressCheckoutNotAllowed` | PayPal Express is active — the cart may not currently be changed. |
## Configuration methods
### GET config/inserts
The following call returns the current configuration of the [insert code feature](/en/frontend/funktionsubersicht/werbemittelkennzeichnung). Use it in a storefront application to decide whether to display an input field for the insert code and how the combination of product number and code is composed.
**Example call**
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://.de/api/v1/config/inserts
```
#### Parameter overview
#### Header parameters
| **Parameter** | **Description** |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session` | **Required field**
ID of the current session.
More information: [Storefront API Basics](/en/schnittstellen/storefront-api/storefront-api-basics) |
#### Example response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"enabled": true,
"defaultInsertCode": "",
"separator": "-",
"position": "after"
}
```
| **Field** | **Type** | **Description** |
| ------------------- | -------- | ---------------------------------------------------------------------------------------- |
| `enabled` | bool | Whether the insert code feature is active in the shop. |
| `defaultInsertCode` | string | Default code that applies if no code or an invalid code has been provided. May be empty. |
| `separator` | string | Separator between product number and code (for example `-`). |
| `position` | string | Position of the code relative to the product number: `before` or `after`. |