Basket

General

Customers must place items in the basket before proceeding to the checkout and completing a purchase. Included products can be reviewed, edited, or moved to the customer's wishlist at any point in time.

Products in the basket always include the respective variant since this is the entity to be sold. So, whether you are adding, updating, or deleting items, you deal with the individual variant and its availability, without exception.

The products are kept for 60 days in the basket and this time is reset in case any change is made within the basket entity. After this period, the products are deleted from the basket.

You can apply one or more promotions to a basket item through the promotions list. Each entry is a promotion id with an optional code. The applied promotions appear on the item as appliedReductions (one entry per promotion, each with category: "promotion" and its promotionId), so several promotions can stack on the same item.

For every applied promotion, its validity (promotion.isValid) and any failed conditions (promotion.failedConditions) depend on whether the promotion meets its conditions. If the conditions are met, isValid is true and failedConditions is empty; otherwise isValid is false and the failed conditions are listed. If no promotions are applied, the item's promotion list is empty.

Retrieve all promotions that could be applied to the basket by including the ?with=applicablePromotions query parameter. Applicable promotions are returned for items that do not already have promotions attached. If you attach one or more promotions to an item, those become directly associated with it, and no further applicable promotions are returned for that item.

For example, to get basket items together with their applicable promotions: GET /v1/baskets/{basket_key}?with=applicablePromotions

You need a configured Storefront API client to:

• get basket items
• get basket items with applicable promotions
• get basket items for a campaign (campaignKey), returning campaign-discounted prices
• add items to the basket
• add items to the basket with one or more promotions (promotions list)
• add items to the basket with a price promotion key (PPK)
• add items to the basket combining PPK, campaignKey and promotions
• add a configurable item to the basket (itemGroup)
• update items in the basket
• update a basket item's promotions (promotions list)
• change item quantity
• bulk-update the promotions applied across basket items
• delete basket item

Storefront API

When selling products, remember that you are always working with its respective variants.

The number of items you can add to the basket depends on how many product variants are in stock.

If you add a number higher than what is in stock, the system will automatically add the maximum number of what is available. If a product is not available at all, the request will fail. If a variant already in the basket goes out of stock, it is flagged as sold out.

Item quantity

addItem() adds a variant that is not yet in the basket. If the variant is already there, the request returns 409 and the SDK gives you a failure result with kind: "VariantAlreadyPresent".

To change the amount of a variant that is already in the basket, update the quantity, or use addOrUpdateItems(), which resolves add-versus-update per item.

Add basket item

We are going to add our first product variant to the basket of a customer. In this example it is about customer 1234 who wants 3 pieces of a specific shirt with variant ID 1.

Each basket has a specific key which we can freely come up with. Here we can use the pattern myshop_customer_$customerId. Whenever we want to work with this basket, we need to refer to that specific key. We also request some product and variant related information, e.g. product name and variant sizes.

addItem() adds a single variant. It returns 409 with kind: "VariantAlreadyPresent" if that variant is already in the basket, so it is not safe to call twice for the same variant.

The NodeJS SDK also provides addOrUpdateItems(), which takes an array of items and resolves each one for you: it adds the item when the variant is not in the basket, and updates the existing item when it is. The existingItemHandling option controls how an existing item is treated (KEEP_EXISTING, ADD_QUANTITY_TO_EXISTING, REPLACE_EXISTING, or the default REPLACE_EXISTING_WITH_COMBINED_QUANTITY).

JavaScriptcURL

Copy

Response

json

Copy

To add several items in one call, and let the SDK decide per item whether to add or update:

javascript

Copy

Add or update items with one or more promotions

Pass a promotions list to apply one or several promotions to an item in a single request. Each entry is a promotion id, with an optional code for code-based promotions. To apply a promotion by code, include the code alongside its id in the list. To change the promotions on an existing item, send the item's full desired promotions list on the update request, or use the bulk endpoint to update promotions across many items at once.

JavaScriptcURL

Copy

Response

json

Copy

Add items to the basket with PPK

It is possible to add an item to the basket with a PPK (Price Promotion Key). The key is stored in the item's customData and is the key applied during checkout, so it changes the price charged for the item and the basket total. Below is an example of how this works:

Example:

• Product original price: $999.00
• After applying the PPK: $777.00

The final payable amount after the PPK discount is $777.00.

JavaScriptcURL

Copy

Response

json

Copy

Combine PPK, campaignKey and promotions

A price promotion key, a campaign, and item promotions are independent and can be used together on the same request. campaignKey is a query parameter, while pricePromotionKey (PPK) and the promotions list go in the item body.

JavaScriptcURL

Copy

Response

json

Copy

Add a configurable item

Configurable products are added as grouped basket items. Each item in a group carries an itemGroup object with a group id that you define, a flag for whether it is the group's main item (isMainItem), and a flag for whether it is required within the group (isRequired). Add the main item and its members with the same itemGroup.id.

JavaScriptcURL

Copy

Removing a required member of a group (including the main item) removes the entire group from the basket. A member marked as not required can be removed on its own, leaving the rest of the group in place. Quantities are managed per item and are not linked across the group. Each item carries its itemGroup in basket responses (null for items that are not part of a group).

Response

json

Copy

Get all basket items

We can request the current state of a basket by passing the basket key. Here we can also define which attributes of the product and its variant we want to retrieve.

A basket key that has never been used is not an error. The request returns 200 with an empty basket ("items": []). Baskets are created on demand when the first variant is added.

Note that you need to have an item in the basket.

JavaScriptcURL

Copy

Response

json

Copy

Get basket items with applicable promotions

Retrieve all applicable promotions alongside the basket items by including the ?with=applicablePromotions query parameter.

JavaScriptcURL

Copy

Response

json

Copy

Get basket items with applicable promotions by promotion code

Send a promotion code to retrieve the promotions it unlocks for the basket. The matched promotions are returned under applicablePromotions, each with the itemId it applies to. Add ?with=applicablePromotions to include them in the response.

JavaScriptcURL

Copy

Response

json

Copy

Update basket item with PPK

We can update the pricePromotionKey (PPK) for the basket item by passing the item key, like so:

JavaScriptcURL

Copy

Response

json

Copy

Change quantity

Sometimes our customers change their mind and change quantity. We can update basket items by passing the item key and the updated quantity.

JavaScriptcURL

Copy

Response

json

Copy

Bulk-update promotions across items

Use the bulk endpoint to set the promotions on several basket items in one request. The submitted list is treated as the complete set of promotions for each item, so any promotion you do not include is removed. To avoid unintended removals, always send the full active list per item. Items you omit from the payload keep their existing promotions unchanged.

JavaScriptcURL

Copy

Response

json

Copy

Delete basket item

To delete an item from the basket we need to pass the item key.

JavaScriptcURL

Copy

Response

json

Copy