Wishlist
General
The wishlist feature is a bookmark service. Customers can add items to their wishlist for quick access and remembering products for a later purchase. Items on the wishlist can be edited, removed, and added to the basket.
Products are kept for 360 days in the wishlist. After this period, the product is deleted and no longer available in the wishlist of the customer.
When retrieving items from a wishlist, it is essential to keep in mind that the actual entity to be sold is the variant. Therefore, you should always make sure not to retrieve only the products themselves but also the variants in question. You use a unique wishlist identifier to retrieve a customer’s wishlist.
You need a configured Storefront API client to:
- get wishlist items
- add items to wishlist
- remove items from wishlist
Storefront API
Each wishlist is referenced by its unique wishlistkey to access and manipulate its items. addItem, get and remove are our three methods to work with. The related product and its selected variant are always included with their default properties.
How to choose a wishlist key?
Wishlist keys need to be unique. It may be a hash, it may be our customer's ID or a combination of both. In the following examples we use the following pattern myshop_customer_$customerId.
Manage wishlist items
Parameters
| param name | type | required | Description |
|---|---|---|---|
wishlistKey | string | true | Unique identifier of the wishlist. |
with | Wishlist | false | Defines which optional fields should be included in the response. Contained as with inside the options object (second parameter). |
Add Item
| param name | type | required | Description |
|---|---|---|---|
wishlistKey | string | true | Key of the wishlist. |
itemCreationId | WishlistItemCreationID | true | Contains either a productId or a variantId. |
with | WishlistWith | false | Defines which optional fields should be included in the response. Contained as with inside the options object (second parameter). |
Delete / remove item
| param name | type | required | Description |
|---|---|---|---|
wishlistKey | string | true | Key of the wishlist. |
itemKey | string | true | Unique identifier of the wishlist item. |
with | Wishlist | false | Defines which optional fields should be included in the response. Contained as with inside the options object (second parameter). |
Add item to wishlist
In this example we will work with the wishlist with key myshop_customer_1234. Of course you may want to choose a different key (pattern). Our customer's wishlist is new and still empty. We can add a new item by specifying a product's variantId.
Response
Add a configurable item to the wishlist
You can add a configurable product to the wishlist by assigning the same itemGroup to each item it is made up of. The group ID can be any non-empty string up to 8 characters in length.
Response
Only one item from the same group can be designated as the main item.
Get a wishlist
To get the current state of a wishlist we simply ask by passing our wishlist key. Additional product or variant fields can be included by with parameters, similar to other Storefront API endpoints.
Optionally you can add a campaignKey to retrieve updated discounted prices.
Response
Remove items from wishlist
We can remove an item by using the remove method.
Let's say we want to remove the item again which we just added in the previous example. We would first get the current wishlist and lookup key field of the item which we want to remove. Then we pass this key to the remove method.
Response
Bulk add and remove wishlist items
Sometimes you need to change many wishlist items at once, for example when a shopper logs in and you merge the items they saved as a guest. Instead of sending one request per item, you can send all the changes in one request to POST /v1/wishlists/{wishlistId}/bulk, where {wishlistId} is the wishlist key. You get the updated wishlist back once, plus one result for each change.
Each change in the request is called an operation. An operation adds or removes one item.
| param name | type | required | Description |
|---|---|---|---|
wishlistKey | string | true | Key of the wishlist. |
operations | array | true | The changes to apply, in the order you send them. Up to 100 operations per request by default. The fields of each operation are listed in the next table. |
campaignKey | string | false | Applies campaign pricing to the product and variant data in the returned wishlist. Passed as a query parameter. |
with | string | false | Defines which optional fields should be included in the returned wishlist. Passed as a query parameter. |
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:
| Action | Same as | Required fields | Optional fields |
|---|---|---|---|
add | Add item to wishlist | variantId or productId | customData, itemGroup |
remove | Remove items from wishlist | key |
key is the key that the wishlist returns on each item. See Get a wishlist. If an add has both variantId and productId, the variantId is used. There is no update action, because wishlist items have no quantity to change.
remove only works on items that were on the wishlist before the request. An item added in the same request gets its key only in the response, so send a second request to remove it.
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.
Merge a guest wishlist after login
A shopper saves four items as a guest, then logs in. Their account wishlist myshop_customer_1234 already holds the sneakers. You merge the guest items with one request:
- You add the T-shirt by its variant.
- You add the jeans by their product.
- The jacket went offline while it sat on the guest wishlist, so its product no longer exists.
- The sneakers are already on the account wishlist.
The response status is 207 because two operations failed. The jeans result names the item by productId, because the operation sent no variantId. A failed add has no key.
Response
You can ignore both failures here. The sneakers are already saved, and nobody can buy the jacket anymore.
Move items from the wishlist to the basket
To move several items to the basket, send one request for each list:
- Add the variants with
POST /v1/baskets/{basketId}/bulk. - Remove only the wishlist items whose
addsucceeded, so a sold-out item stays on the wishlist.
Items saved by productId need a variant, such as a size, before they can go to the basket. Match each basket result to its wishlist item by variantId, then remove that item by its key.
Here the T-shirt and the sneakers made it into the basket, so you remove both from the wishlist:
Both operations succeed, so the status is 200.
Response
Read the results
Check results on every response. The status code only tells you whether any operation failed:
| Status | Meaning | What to do |
|---|---|---|
200 OK | Every operation succeeded. | Use the returned wishlist. |
207 Multi-Status | At least one operation failed. The rest went through. | Find the results with "status": "failed" and handle each error.code. |
400 Bad Request | The request is invalid, so no operation ran. | Fix the fields listed in details and send the request again. |
423 Locked | Another request is changing the same wishlist. | Retry after a short wait. |
500 Internal Server Error | The request didn't finish. Some operations may have gone through. | Get the wishlist before you retry. |
A failed result carries an error with a code and a message. The message is for developers, so don't show it to shoppers.
| Code | Actions | Meaning |
|---|---|---|
VARIANT_NOT_FOUND | add | The variant doesn't exist in this shop. |
PRODUCT_NOT_FOUND | add | The product doesn't exist in this shop or has no variants. |
ITEM_ALREADY_EXISTS | add | The wishlist already holds this item. |
ITEM_LIMIT_EXCEEDED | add | The wishlist already holds the maximum number of items. |
ITEM_NOT_FOUND | remove | No item with this key is on the wishlist. |
INTERNAL_ERROR | all | The operation failed for another reason. Get the wishlist to see its current state. |
Limits
- A request can hold up to 100 operations by default. With more, you get a
400whosedetails[0].descriptionstarts withTOO_MANY_OPERATIONS. - If one operation is invalid, for example an
addwith neithervariantIdnorproductId, the whole request fails with400and no operation runs. - If the wishlist doesn't exist yet, the request creates it, as a single add does. A
removeon the new, empty wishlist fails withITEM_NOT_FOUND. - A bulk request counts as one request against your rate limit, however many operations it holds.