Storefront API Shopping Cart

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. Shipping costs are not part of the cart response. total, totalNet, totalGross, and totalTax are pure goods-value subtotals without shipping, payment, or surcharge costs and without voucher deduction. Shipping costs (shippingCost), payment costs (paymentCost), surcharges (surchargeCost), the voucher deduction (totalVoucher), and the final total are delivered by the checkout endpoints in the sum object. 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/items/add`
Update cart position	`basket/items/update`
Remove cart position	`basket/item/delete`
Read insert code configuration	`config/inserts`

Error format

All errors are returned with HTTP 400 and the following body:

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

error = invalidParameters for errors in parameters or field types (details in paramErrors, key = parameter name, value {"type": "missing" | "invalidFormat" | "invalidValue" | "unknownField" | …}).
error = actionFailed for business errors. The error codes listed in the following tables then appear in actionErrors[].code.
A call with an incorrect HTTP method is answered with HTTP 404 (not 405).
If the session (x-session) is missing, the response is HTTP 400.

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

billingCountry and shippingCountry are each a single country code as a string. Which format is delivered (isoAlpha2 = DE, isoAlpha3 = DEU, or isoNum = 276) depends on the shop configuration. lastBasketAction marks the most recently performed change. Possible values: add, delete, unknown. A quantity change sets add or delete depending on the result. The value update does not exist. lastUpdatedItem describes the most recently changed position. Note: lastUpdatedItem.id contains the product ID, not the cart position ID from items[].id. Additional fields: productNumber, categories (string[]), parentCategories (string[]), freeFields, voucherIds.

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

If the same product (same variant and same freeFields) is added multiple times, no second cart position is created: the quantity of the existing position is increased by quantity and its items[].id remains unchanged. Set products are never merged.

Example request

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

Body parameters

Parameter	Type	Description
`productId`	string	Required field ID of the product to be added to the cart.
`quantity`	int	Required field Specifies how many times the product is to be added to the cart.
`insert`	string	Optional insert code. 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. A submitted code is additionally stored as a session-wide code and applies as a default for all positions added afterwards. If `insert` is omitted, the last session-wide code applies. 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.

Only the fields listed above are allowed. Any additional field in the request body results in HTTP 400 with error: "invalidParameters" and an entry unknownField in paramErrors. Note on set products: The endpoint accepts only the four fields listed above. Any additional field is rejected with unknownField. The variant selection for set sub-items (setChildVar_<childId>) can therefore not currently be transmitted. Set products whose sub-items have variants cannot be ordered via the Storefront API.

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

Each position in items[] may additionally contain the following fields:

Field	Type	Description
`id`	string	ID of the cart position (for `update`/`delete`).
`quantity`	float	Quantity of the position.
`price`	float	Unit price of the position.
`orgPrice`	float	Original unit price before discount.
`discountPrice`	float	Discount amount of the position.
`total` / `totalGross` / `totalNet` / `totalTax`	float	Position total gross/net/tax portion.
`oneTimeFee`	float	One-time fee of the position.
`insert`	string	Resolved insert code of the position.
`itemNumberWithInsert`	string	Product number including insert code.
`freeFields`	Object (String → String)	Free fields of the position.
`voucherIds`	string[]	IDs of the vouchers generated for this position (voucher products).
`isSetProduct`	bool	Only present for set parent items and then `true`.
`isSetChild`	bool	Only present for set sub-items and then `true`.
`parentBasketItemId`	string	Only for set sub-items: ID of the set parent item.
`product`	Object	Product data at the time of cart addition.

Non-visible positions (isVisible = false) and hidden set sub-items do not appear in items.

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

For quantityExceeded, details contains the fields productId (affected product ID), quantity (requested total quantity), and maxQuantity (globally configured maximum quantity per position). subCode contains the product ID, field the value quantity. In addition to the global maximum, a product may have a lower limit via the product field for the maximum quantity.

PUT basket/items/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/items/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)
`insert`	string	Sets or changes the insert code of the position. Behaves like when adding: a valid code is applied, otherwise the default code is used. A submitted code is also stored as a session-wide code for subsequent positions. 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" }`

Only the fields listed above are allowed. Any additional field in the request body results in HTTP 400 with error: "invalidParameters" and an entry unknownField in paramErrors.

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

lastBasketAction, lastUpdatedItem, totalCommission, and totalWeight are only delivered by the read endpoint GET basket/items/get. The fields of the positions in items[] correspond to those of POST basket/items/add, see there.

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).
`invalidProductId`	The product ID does not exist, or a set refers to a non-existent set sub-product or a non-existent sub-item variant.
`expressCheckoutNotAllowed`	An Express Checkout is active — the cart may not currently be changed.
`basketLocked`	The cart is locked (for example due to an approval process for sub-accounts) and may not be changed.
`missingBasketItemId`	`basketItemId` was not provided or is empty.
`invalidQuantity`	The quantity is not a positive integer (or 0 when removal is allowed) or the position is a set sub-item whose quantity may not be changed directly.
`internalError`	A set product could not be saved during rebuild.

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.
`invalidChildItemDelete`	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. (`field` = `childItemDelete`)
`itemNotRemovable`	The position may not be removed (e.g. automatically added item).
`expressCheckoutNotAllowed`	PayPal Express is active — the cart may not currently be changed.
`basketLocked`	The cart is locked (for example due to an approval process for sub-accounts) and may not be changed.
`missingBasketItemId`	`basketItemId` was not provided or is empty.

Configuration methods

GET config/inserts

The following call returns the current configuration of the insert code feature. 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

GET https://<your-shop>.de/api/v1/config/inserts

Parameter overview

Header parameters

This endpoint does not require a session. The x-session header is optional and is ignored.

Example response

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

Interfaces

Admin Interface API

Storefront API

More

Supported methods

Error format

Methods for the shopping cart

GET basket/item/get

Parameter overview

Header parameters

Example response

POST basket/items/add

Example request

Parameter overview

Header parameters

Body parameters

Example response

Error codes

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

Configuration methods

GET config/inserts

Parameter overview

Header parameters

Example response

​Supported methods

​Error format

​Methods for the shopping cart

​GET basket/item/get

​Parameter overview

​Header parameters

​Example response

​POST basket/items/add

​Example request

​Parameter overview

​Header parameters

​Body parameters

​Example response

​Error codes

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

​Configuration methods

​GET config/inserts

​Parameter overview

​Header parameters

​Example response

Supported methods

Error format

Methods for the shopping cart

GET basket/item/get

Parameter overview

Header parameters

Example response

POST basket/items/add

Example request

Parameter overview

Header parameters

Body parameters

Example response

Error codes

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

Configuration methods

GET config/inserts

Parameter overview

Header parameters

Example response