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

Bulk add, update and remove basket items

Sometimes a customer changes many items at once, for example when a returning customer reorders a past order with 40 items. Instead of sending one request per item, you can send all the changes in one request to POST /v1/baskets/{basketId}/bulk, where {basketId} is the basket key. You get the updated basket back once, plus one result for each change.

Each change in the request is called an operation. An operation adds, updates or removes one item.

Each operation has an action and the same fields as the matching single-item request, except that the item key is sent as key instead of itemKey:

key is the key that the basket returns on each item. See Get all basket items.

To apply a price promotion key, set pricePromotionKey inside the operation's customData.

The operations run in the order you send them, and the API handles each one separately. If one fails, the others still apply. results[0] describes operations[0], results[1] describes operations[1], and so on.

In this example, one request adds five T-shirts and a hoodie, sets the jeans to two pairs and removes the socks. Three of them don't go to plan:

• Only three T-shirts are left, so the basket gets three.
• The hoodie sold out a minute ago.
• The customer had already removed the jeans in another browser tab.

cURL

Copy

The response status is 207 because one is only partly added and two fail. The basket holds the sneakers that were already in it and the three new T-shirts.

Response

json

Copy

Read the results

Check results on every response, including a 200. The status code only tells you whether any operation failed:

A failed result carries an error with a code and a message. The message is for developers, so don't show it to customers. These are the codes for each action:

Less stock than requested

If fewer units are available than an add or update asks for, the operation still succeeds with the units that are left. The same happens when a shop category's basket limit leaves room for fewer units. The result then has two quantities:

• quantity is what went into the basket.
• requestedQuantity is what you asked for. It only appears in this case.

In the example above, the T-shirt result has "quantity": 3 and "requestedQuantity": 5. Use the difference to tell the customers that only three were added. The single-item requests answer 206 when they add fewer units than requested. The bulk endpoint keeps the status at 200 if nothing else failed.

Limits

• A request can hold up to 100 operations by default. With more, you get a 400 whose details[0].description starts with TOO_MANY_OPERATIONS.
• If the basket doesn't exist yet, the request creates it, as a single add does. An update or remove on the new, empty basket fails with ITEM_NOT_FOUND.
• A bulk request counts as one request against your rate limit, however many operations it holds.

If one operation is invalid, for example a quantity of 0, the whole request fails with 400 and no operation runs. details names each problem by its position in operations:

json

Copy

Replace a loop of single requests

If your shop adds items one request at a time, for a reorder or a "complete the look" button, you can move that loop to the bulk endpoint:

1. Build one add operation per item.
2. Send all operations in one request. If you have more than 100, split them into chunks of up to 100 and send the chunks one after the other, not in parallel. Two requests on the same basket at the same time can fail with 423.
3. Match each failed result to its item by position and tell the customers which items couldn't be added. ITEM_ALREADY_EXISTS means the variant is already in the basket, so don't report it as missing. To change its quantity, send an update with the item's key.

javascript

Copy