Storefront API Shopping Cart - WEBSALE Dokumentation

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.

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`

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).
This command can be used to display the cart. Example call for displaying the current cart

GET https://<your-shop>.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

Example response

{
  "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

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

Example request

{
  "productId": "71-3953",
  "quantity": 3,
  "freeFields": {
    "giftMessage": "Best wishes!"
  }
}

Parameter overview

Header parameters

Parameter	Description
`x-session`	Required field ID of the current session. More information: 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.
`freeFields`	Object (String → String)	Free key/value pairs that can be attached to the position and exported into the order data.

Example response

{
  "basket": {
    "items": [
      {
        "id": "f28e67292c99759e5fb9",
        "quantity": 3,
        "price": 139,
        "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

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

Example request (reduce quantity of a position to 2)

{
  "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

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

{
  "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

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

Example request

{
  "basketItemId": "0d1b062c8225f817aa3e"
}

Parameter overview

Header parameters

Parameter	Description
`x-session`	Required field ID of the current session. More information: Storefront API Basics

Body parameters

Parameter	Type	Description
`basketItemId`	String	Required field ID of the cart position (corresponds to `items[].id` in the cart).

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

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.

​Supported methods

​Methods for the shopping cart

​GET basket/item/get

​Parameter overview

​Header parameters

​Example response

​POST basket/item/add

​Example request

​Parameter overview

​Header parameters

​Body parameters

​Example response

​Error codes

​PUT basket/item/update

​Example request (reduce quantity of a position to 2)

​Parameter overview

​Header parameters

​Body parameters

​Example response

​Error codes

​DELETE basket/item/delete

​Example request

​Parameter overview

​Header parameters

​Body parameters

​Example response

​Error codes

Supported methods

Methods for the shopping cart

GET basket/item/get

Parameter overview

Header parameters

Example response

POST basket/item/add

Example request

Parameter overview

Header parameters

Body parameters

Example response

Error codes

PUT basket/item/update

Example request (reduce quantity of a position to 2)

Parameter overview

Header parameters

Body parameters

Example response

Error codes

DELETE basket/item/delete

Example request

Parameter overview

Header parameters

Body parameters

Example response

Error codes