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 wish list 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.
Promotions at the item level within the basket are always included if a promotionId is present. However, the validity of the promotion (promotion.isValid) and any failed conditions (promotion.failedConditions) depends on whether the promotion meets its specified conditions. If the conditions are met, isValid is true, and failedConditions is an empty array; otherwise, it could be vice versa. If there is no promotionId, both promotionId and the promotion object will be null at the basket item level.
Retrieve a list of all applicable promotions by including the ?with=applicablePromotions query parameter. To display applicable promotions, submit a basket item without the "promotionId" parameter. If the "promotionId" is included, the promotion becomes directly associated with the item, and no other applicable promotions will be displayed.
For example, to get basket items with 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
- add items to the basket
- add items to the basket with promotionId
- add items to the basket with promotionCode
- add items to the basket with PPK
- add items to the basket with combined promotionId and PPK
- update items in the basket
- update basket item with
promotionId - update basket item with
promotionCode - update basket item with PPK
- update basket item with combined promotionId and PPK
- remove item from the basket
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 the variant was added before it was unavailable, it will be flagged as sold out.
Item quantity
You cannot add an item, which is already in the basket. In this case, you need to update the quantity.
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.
Use addOrUpdateItem()
The NodeJS SDK provides the method addOrUpdateItem() which works similar to addItem() but can be run again for the same variant with an updated quantity. If you run addItem() for a variant which exists in the basket it results in a failure.
For PHP and Java use update() to change quantity.
| Parameter | Type | Required | Description |
|---|---|---|---|
basketKey | string | true | Key of the basket. |
variantId | integer | true | ID of the variant to be added to the basket. |
quantity | integer | true | Quantity of variants to be added to the basket. |
promotionId | string | false | ID of promotion to be added to the basket. |
promotionCode | string | false | Code of promotion to be added to the basket. |
with | object | false | Defines which optional fields should be included in the response. Contained as with inside the options object (fourth parameter). |
customData | string | false | For each item, you can add an additional custom data array. The data will remain attached to the basket item and you may retrieve it at any time during or after the checkout and order process. You can specify |
Response
Add items to the basket with promotionId
We are going to add our first product variant to the basket of a customer. In this example it is about customer 1235 who wants 2 pieces of a specific shirt with variant id 100, and promotion ID 6522f4b2b857b289b920c12e. Each basket has a specific key which we can freely come up with. Here we can with 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.
Use addOrUpdateItem()
The NodeJS SDK provides the method addOrUpdateItem() which works similar to addItem() but can be run again for the same variant with an updated quantity. If you run addItem() for a variant which exists in the basket it results in a failure.
For PHP and Java use update() to change quantity.
Response
Add items to the basket with promotionCode
It is also possible to add an item to the basket with a promotionCode. It works the same way as with a promotionId and you also need to include the promotionId.
Response
Add items to the basket with PPK
It is possible to add an item to the basket using a PPK (Price Promotion Key). This process applies the PPK discount directly to the item's original price. Below is an example of how this works:
Example:
- Product Original price: €999
- After applying the PPK: €777
The final payable amount after the PPK discount is €777.
Response
Add items to the basket with combined promotionId and PPK
It is possible to add an item to the basket using both a promotionId and a PPK (Price Promotion Key) simultaneously. This process first applies the PPK discount, and then the promotion's automatic discount is applied on top of it. Below is an example of how to make this request, along with the expected outcomes.
In below example: Original price: €999. After applying the PPK, price drops to €777. With a 17% promotion discount (on orders above €500), the final payable amount is €644.91.
Response
Get all basket items
We can request the current state of a basket by simply passing the basket key. Here we can also define which attributes of the product and its variant we want to retrieve.
Note that you need to have an item in the basket.
Optionally you can add a campaignKey to retrieve updated discounted prices.
Response
Get Basket items with Applicable Promotions
Retrieve a list of all applicable promotions along with basket items by including the?with=applicablePromotions query parameter. To display applicable promotions, submit a basket item without the "promotionId" parameter. If the "promotionId" is included (not null), the promotion becomes directly associated with the item, and no other applicable promotions will be displayed.
Optionally you can add a with=applicablePromotions to retrieve active applicable promotions.
Response
Get Basket items with Applicable Promotions by Promotion Code
Retrieve a list of all applicable promotions along with basket items by promotion code.
Response
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.
| Parameter | type | Required | Description |
|---|---|---|---|
basketKey | string | true | Key of the basket. |
itemKey | string | true | Key of the basket item. |
quantity | integer | true | New quantity of the item. |
promotionId | string | false | ID of promotion to be updated to the basket item |
promotionCode | string | false | Code of promotion to be updated to the basket item |
with | object | false | Defines which optional fields should be included in the response. Contained as with inside the options object (second parameter). |
Response
Update Basket Item with promotionId
We can update promotionId to the basket item by passing the item key, like so:
Response
Update Basket Item with promotionCode
We can update the promotionCode of the basket item by passing the item key, like so:
Response
Update Basket Item with PPK
We can update the pricePromotionKey (PPK) for the basket item by passing the item key, like so:
Response
Update basket item with combined promotionId and PPK
We can update the promotionId and pricePromotionKey (PPK) for the basket item by passing the item key, like so:
// Update a basket item and set PricePromotionKey and PromotionId
const { basket } = await client.basket.get("myshop_customer_1236");
console.log(`PromotionId: ${basket.items[0].promotionId}`);
console.log(`PricePromotionKey: ${basket.customData.pricePromotionKey}`);
// PromotionId: null
// PricePromotionKey: null
const item = basket.items[0];
const { basket: updatedBasket } = await client.basket.updateItem(
"myshop_customer_1236",
item.key,
item.quantity,
{
promotionId:"672b8324cc574c81c1a24938",
pricePromotionKey: "sapiqappk",
},
);
console.log(`PromotionId: ${updatedBasket.items[0].promotionId}`);
console.log(`PricePromotionKey: ${updatedBasket.customData.pricePromotionKey}`);
// PromotionId: 672b8324cc574c81c1a24938
// PricePromotionKey: "sapiqappk"
Response
Delete basket item
To delete an item from the basket we simply need to pass the item key.
currently for deleteItem() in NodeJS SDK the basket object is not nested under the key basket but included directly. This will be fixed in the next upcoming version
| Parameter | Type | Required | Description |
|---|---|---|---|
basketKey | string | true | Unique identifier of the basket. |
with | BasketWith | false | Defines which optional fields should be included in the response. Contained as with inside the options object (second parameter). |