baskets

Add a variant

Adds a new variant to a given basket, so the user can purchase it in the checkout process.

Baskets are created on demand when the first variant is added to the basket.

Only one variant can be added to the basket with each request. Use multiple requests to add more variants.

The variant and quantity to be added is specified in the POST request body (see below). The only strictly required parameters are variantId and quantity.

The response will return the updated content of the basket.

post/v1/baskets/{basketId}/items

Path parameters

basketIdstring required

Example:fySXbTJxa9q_xu_t8edGOHYeJSpaxe7A

The ID of the Basket

Query parameters

campaignKeystring

Adjust prices based on the specified campaignKey. If results are not having a matching campaign, the default price is returned.

Please note, that campaign prices are stored in advance and available earlier than the campaign starts.

includeItemsWithoutProductDataboolean

If includeItemsWithoutProductData is set to true, basket items will be included even if there is no product information available (items.product and items.variant might be empty).

pricePromotionKeystring

Adjust variant price based on the specified pricePromotionKey. If the variant does not have a matching price promotion, the default price is returned.

skipAvailabilityCheckboolean

This parameter allows disabling the availability check when adding an item into the wishlist or basket. This is needed to make sure that sold out products can be reserved via Click & Reserve in retail stores (where they are still available). Important – Check if this resource is available for your shop.

withstring[]

The with parameter can be applied to include related resources, for example, the attributes of a product can be attached using with=items.product.attributes. It is also possible to filter attributes by key with=items.product.attributes:key(plusSize) or by type with=items.product.attributes:type(material_care). The with=applicablePromotions parameter can also be applied to include all promotions applicable for the current basket. In the following table, there is more information about possible includes.

Include	Nested Includes	Available Filters
items.product	See available includes for products	Check the filters available for products
items.variant	See available includes for variants	Check the filters available for variants
applicablePromotions

shopIdstring required

In case you are operating multiple shops (for example, for different domain names or different languages), each shop is identified by its specific shopId

Headers

X-Order-Custom-Datastring

Base64-encoded data for custom order information. Should be in the format of map[string]any.

X-Customer-Tokenstring

A JWT token containing the customer ID used to validate promotions in the promotion engine.

Request body

quantityinteger required

The quantity for the variant.

variantIdinteger required

The variant to be added to the basket.

promotionIdstring

An optional promotion ID which should be applied to this item.

Example request

{
  "displayData": {
    "meta": {
      "key": "size",
      "label": "Size",
      "value": "M"
    },
    "name": {
      "key": "size",
      "label": "Size",
      "value": "M"
    },
    "identifier": {
      "key": "size",
      "label": "Size",
      "value": "M"
    },
    "attribute-1": {
      "key": "size",
      "label": "Size",
      "value": "M"
    },
    "attribute-2": {
      "key": "size",
      "label": "Size",
      "value": "M"
    },
    "attribute-3": {
      "key": "size",
      "label": "Size",
      "value": "M"
    }
  }
}

Response

The variant was added to the Basket with all of the request quantity.

keystring

A unique key identifying the basket.

Changes

Changed in 2 of the 3 revisions of this API.163454

Jul 17, 20268cfa924ae7033643See the full diff
- ▲
  added the new required query request parameter shopId
  new-required-request-parameter
- ▲
  the request property quantity became required
  request-property-became-required
- ▲
  the request property variantId became required
  request-property-became-required
- ●
  removed the request property shopId
  request-property-removed
- ●
  removed the optional property items/items/cost from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property items/items/items from the response with the 201 status
  response-optional-property-removed
- ●
  added the new campaign enum value to the cost/appliedReductions/items/category response property for the response status 201
  response-property-enum-value-added
- ●
  added the new promotion enum value to the cost/appliedReductions/items/category response property for the response status 201
  response-property-enum-value-added
- ●
  added the new sale enum value to the cost/appliedReductions/items/category response property for the response status 201
  response-property-enum-value-added
- ○
  added the new optional header request parameter X-Customer-Token
  new-optional-request-parameter
- ○
  added the new optional header request parameter X-Order-Custom-Data
  new-optional-request-parameter
- ○
  added the new optional request property customData/pricePromotionKey
  new-optional-request-property
- ○
  added the new optional request property displayData/attribute-1
  new-optional-request-property
- ○
  added the new optional request property displayData/attribute-2
  new-optional-request-property
- ○
  added the new optional request property displayData/attribute-3
  new-optional-request-property
- ○
  added the new optional request property displayData/identifier
  new-optional-request-property
- ○
  added the new optional request property displayData/meta
  new-optional-request-property
- ○
  added the new optional request property displayData/name
  new-optional-request-property
- ○
  added the new optional request property itemGroup
  new-optional-request-property
- ○
  the quantity request property default value 1 was removed
  request-property-default-value-removed
- ○
  added the media type application/json for the response with the status 409
  response-media-type-added
- ○
  added the media type application/json for the response with the status 412
  response-media-type-added
- ○
  added the media type application/json for the response with the status 413
  response-media-type-added
- ○
  added the non-success response with the status 404
  response-non-success-status-added
- ○
  removed the non-success response with the status 422
  response-non-success-status-removed
- ○
  added the optional property applicablePromotions to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property cost/reference to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property items/items/availableQuantity to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property items/items/customData to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property items/items/deliveryForecast to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property items/items/displayData to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property items/items/itemGroup to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property items/items/key to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property items/items/lowestPriorPrice to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property items/items/packageId to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property items/items/price to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property items/items/product to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property items/items/promotion to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property items/items/promotionId to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property items/items/quantity to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property items/items/status to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property items/items/variant to the response with the 201 status
  response-optional-property-added
- ○
  the response property cost/appliedReductions became required for the status 201
  response-property-became-required
- ○
  the response property cost/appliedReductions/items/amount became required for the status 201
  response-property-became-required
- ○
  the response property cost/appliedReductions/items/category became required for the status 201
  response-property-became-required
- ○
  the response property cost/appliedReductions/items/type became required for the status 201
  response-property-became-required
- ○
  the response property cost/currencyCode became required for the status 201
  response-property-became-required
- ○
  the response property cost/withTax became required for the status 201
  response-property-became-required
- ○
  the response property cost/withoutTax became required for the status 201
  response-property-became-required
- ○
  added the required property cost/recommendedRetailPrice to the response with the 201 status
  response-required-property-added
- ○
  added the required property cost/tax to the response with the 201 status
  response-required-property-added
- ○
  added the success response with the status 206
  response-success-status-added
This revision also has 6 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 6, 2023302b7c443b51132811See the full diff
- ▲
  removed the media type application/json for the response with the status 409
  response-media-type-removed
- ▲
  removed the media type application/json for the response with the status 412
  response-media-type-removed
- ▲
  removed the media type application/json for the response with the status 413
  response-media-type-removed
- ▲
  the response property cost/appliedReductions became optional for the status 201
  response-property-became-optional
- ▲
  the response property cost/appliedReductions/items/amount became optional for the status 201
  response-property-became-optional
- ▲
  the response property cost/appliedReductions/items/category became optional for the status 201
  response-property-became-optional
- ▲
  the response property cost/appliedReductions/items/type became optional for the status 201
  response-property-became-optional
- ▲
  the response property cost/currencyCode became optional for the status 201
  response-property-became-optional
- ▲
  the response property cost/withTax became optional for the status 201
  response-property-became-optional
- ▲
  the response property cost/withoutTax became optional for the status 201
  response-property-became-optional
- ▲
  removed the required property cost/recommendedRetailPrice from the response with the 201 status
  response-required-property-removed
- ▲
  removed the required property cost/tax from the response with the 201 status
  response-required-property-removed
- ▲
  removed the success response with the status 206
  response-success-status-removed
- ●
  deleted the header request parameter X-Customer-Token
  request-parameter-removed
- ●
  deleted the header request parameter X-Order-Custom-Data
  request-parameter-removed
- ●
  deleted the query request parameter shopId
  request-parameter-removed
- ●
  removed the request property customData/pricePromotionKey
  request-property-removed
- ●
  removed the request property displayData/attribute-1
  request-property-removed
- ●
  removed the request property displayData/attribute-2
  request-property-removed
- ●
  removed the request property displayData/attribute-3
  request-property-removed
- ●
  removed the request property displayData/identifier
  request-property-removed
- ●
  removed the request property displayData/meta
  request-property-removed
- ●
  removed the request property displayData/name
  request-property-removed
- ●
  removed the request property itemGroup
  request-property-removed
- ●
  removed the optional property applicablePromotions from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property cost/reference from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property items/items/availableQuantity from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property items/items/customData from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property items/items/deliveryForecast from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property items/items/displayData from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property items/items/itemGroup from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property items/items/key from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property items/items/lowestPriorPrice from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property items/items/packageId from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property items/items/price from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property items/items/product from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property items/items/promotion from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property items/items/promotionId from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property items/items/quantity from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property items/items/status from the response with the 201 status
  response-optional-property-removed
- ●
  removed the optional property items/items/variant from the response with the 201 status
  response-optional-property-removed
- ○
  added the new optional request property shopId
  new-optional-request-property
- ○
  the request property quantity became optional
  request-property-became-optional
- ○
  the request property variantId became optional
  request-property-became-optional
- ○
  the quantity request property default value 1 was added
  request-property-default-value-added
- ○
  added the non-success response with the status 422
  response-non-success-status-added
- ○
  removed the non-success response with the status 404
  response-non-success-status-removed
- ○
  added the optional property items/items/cost to the response with the 201 status
  response-optional-property-added
- ○
  added the optional property items/items/items to the response with the 201 status
  response-optional-property-added
- ○
  removed the campaign enum value from the cost/appliedReductions/items/category response property for the response status 201
  response-property-enum-value-removed
- ○
  removed the promotion enum value from the cost/appliedReductions/items/category response property for the response status 201
  response-property-enum-value-removed
- ○
  removed the sale enum value from the cost/appliedReductions/items/category response property for the response status 201
  response-property-enum-value-removed
This revision also has 34 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history