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`	WishliteItemCreationID	true	Contains either a `masterKey`, `productId`, or `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.

// Add variant with id 1 to our customer's wishlist
const response = await client.wishlist.addItem(
  "myshop_customer_1234",
  {
    variantId: 1
  }
);

console.log(`Items count: ${response.wishlist.items.length}`);
// Items count: 1

Response

{
  "type": "success",
  "wishlist": {
    "key": "myshop_customer_1234",
    "items": [
      {
        "key": "c4ca4238a0b923820dcc509a6f75849b",
        "packageId": 1,
        "quantity": 1,
        "status": "available",
        "customData": {},
        "variant": {
          "id": 1,
          "referenceKey": "THS0906008000001_S",
          "firstLiveAt": "0001-01-01T00:00:00+00:00",
          "createdAt": "2023-06-12T14:05:33+00:00",
          "updatedAt": "2023-07-07T11:50:06+00:00",
          "stock": {
            "supplierId": 1,
            "warehouseId": 1,
            "quantity": 31,
            "isSellableWithoutStock": false
          },
          "price": {
            "currencyCode": "EUR",
            "withTax": 3990,
            "withoutTax": 3353,
            "recommendedRetailPrice": null,
            "tax": { "vat": { "amount": 637, "rate": 0.19 } },
            "appliedReductions": []
          },
          "customData": {}
        },
        "product": {
          "id": 1,
          "isActive": true,
          "isSoldOut": false,
          "isNew": false,
          "createdAt": "2023-06-12T14:05:33+00:00",
          "updatedAt": "2023-06-12T14:05:34+00:00",
          "indexedAt": "2023-07-18T09:31:55+00:00",
          "firstLiveAt": "2023-06-12T14:05:33+00:00",
          "masterKey": "THS090600",
          "referenceKey": "THS0906008000001",
          "images": [
            {
              "hash": "https://cdn.aboutstatic.com/file/cd81a5d37e4241686586812d9e179553?bg=F4F4F5&quality=75&trim=1&height=1067&width=800,https://cdn.aboutstatic.com/file/1c98f7fc408b9d2cca91abfbf5650df1?bg=F4F4F5&quality=75&height=1067&width=800, https://cdn.aboutstatic.com/f"
            }
          ],
          "customData": {}
        },
        "variantId": 1,
        "productId": 1
      }
    ]
  }
}

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.

// Add configurable product with id 1 to our customer's wishlist
const response = await client.wishlist.addItem(
  "myshop_customer_1234",
  {
    productId: 1,
    itemGroup: {
      id: "ed4yp7cm",
      isMainItem: true,
      isRequired: true,
    },
  }
);

console.log(`Items count: ${response.wishlist.items.length}`);
// Items count: 1

Response

{
  "key": "myshop_customer_1234",
  "items": [
    {
      "key": "c4ca4238a0b923820dcc509a6f75849b",
      "packageId": 1,
      "quantity": 1,
      "status": "available",
      "customData": {
        "productId": 1
      },
      "product": {
        "id": 1,
        "isActive": true,
        "isSoldOut": false,
        "isNew": false,
        "createdAt": "2023-06-12T14:05:33+00:00",
        "updatedAt": "2023-06-12T14:05:34+00:00",
        "indexedAt": "2023-07-18T09:31:55+00:00",
        "firstLiveAt": "2023-06-12T14:05:33+00:00",
        "masterKey": "THS090600",
        "referenceKey": "THS0906008000001",
        "images": [
          {
            "hash": "images/9cfbc1346d4cbf08a726429b6ca45c91.jpg"
          }
        ],
        "customData": {}
      },
      "variantId": null,
      "productId": 1,
      "itemGroup": {
        "id": "ed4yp7cm",
        "isMainItem": true,
        "isRequired": true
      }
    }
  ]
}

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.

// Get the current state of wishlist by key "myshop_customer_1234"
const response = await client.wishlist.get("myshop_customer_1234", {
  with: {
    items: {
      product: {
          attributes: { withKey: ["name", "brand"] },
       },
      variant: {
        attributes: "all"
      },
    },
  },
  campaignKey: "promo_test_20",
});

const item = response.items[0];
console.log(item.product.attributes.name.values.label);
console.log(`Size: ${item.variant.attributes.size.values.label}`);
// Hilfiger Shirt
// Size: S

Response

{
  "key": "myshop_customer_1234",
  "items": [
    {
      "key": "c4ca4238a0b923820dcc509a6f75849b",
      "packageId": 1,
      "quantity": 1,
      "status": "available",
      "customData": {},
      "itemGroup": {
        "id": "sun_glasses_hhbdz6",
        "isMainItem": true,
        "isRequired": true
      },
      "variant": {
        "id": 1,
        "referenceKey": "THS0906008000001_S",
        "attributes": {
          "size": {
            "id": 1002,
            "key": "size",
            "label": "Größe",
            "type": "",
            "multiSelect": false,
            "values": { "id": 28, "label": "S", "value": "s" }
          }
        },
        "firstLiveAt": "0001-01-01T00:00:00+00:00",
        "createdAt": "2023-06-12T14:05:33+00:00",
        "updatedAt": "2023-07-07T11:50:06+00:00",
        "stock": {
          "supplierId": 1,
          "warehouseId": 1,
          "quantity": 31,
          "isSellableWithoutStock": false
        },
        "price": {
          "currencyCode": "EUR",
          "withTax": 3990,
          "withoutTax": 3353,
          "recommendedRetailPrice": null,
          "tax": { "vat": { "amount": 637, "rate": 0.19 } },
          "appliedReductions": []
        },
        "customData": {}
      },
      "product": {
        "id": 1,
        "isActive": true,
        "isSoldOut": false,
        "isNew": false,
        "createdAt": "2023-06-12T14:05:33+00:00",
        "updatedAt": "2023-06-12T14:05:34+00:00",
        "indexedAt": "2023-07-18T09:31:55+00:00",
        "firstLiveAt": "2023-06-12T14:05:33+00:00",
        "masterKey": "THS090600",
        "referenceKey": "THS0906008000001",
        "attributes": {
          "fit": {
            "id": 1008,
            "key": "fit",
            "label": "Passform",
            "type": "",
            "multiSelect": true,
            "values": [
              {
                "id": 25,
                "label": "Schmale Passform",
                "value": "schmale_passform"
              }
            ]
          },
          "designExtras": {
            "id": 1005,
            "key": "designExtras",
            "label": "Design & Extras",
            "type": "",
            "multiSelect": true,
            "values": [
              { "id": 13, "label": "Melange", "value": "melange" },
              { "id": 14, "label": "Jersey", "value": "jersey" },
              {
                "id": 15,
                "label": "Rundhals-Ausschnitt",
                "value": "rundhalsausschnitt"
              },
              {
                "id": 16,
                "label": "Abgesteppter Saum/Kante",
                "value": "abgesteppter_saumkante"
              },
              { "id": 17, "label": "Gerader Saum", "value": "gerader_saum" },
              {
                "id": 18,
                "label": "Gerader Schnitt",
                "value": "gerader_schnitt"
              },
              { "id": 19, "label": "Necktape", "value": "necktape" },
              {
                "id": 20,
                "label": "Flammgarn-Struktur",
                "value": "flammgarnstruktur"
              },
              {
                "id": 21,
                "label": "Label Stickerei",
                "value": "label_stickerei"
              },
              {
                "id": 22,
                "label": "Ton-in-Ton-Nähte",
                "value": "tonintonnhte"
              },
              { "id": 23, "label": "Weicher Griff", "value": "weicher_griff" }
            ]
          },
          "material": {
            "id": 1003,
            "key": "material",
            "label": "Material",
            "type": "",
            "multiSelect": false,
            "values": { "id": 11, "label": "Baumwolle", "value": "baumwolle" }
          },
          "description": {
            "id": 20006,
            "key": "description",
            "label": "Description",
            "type": "",
            "multiSelect": false,
            "values": { "id": 20006, "label": "", "value": "description" }
          },
          "name": {
            "id": 20005,
            "key": "name",
            "label": "Name",
            "type": "",
            "multiSelect": false,
            "values": {
              "id": 20005,
              "label": "Hilfiger Shirt",
              "value": "name"
            }
          },
          "sleevelength": {
            "id": 1006,
            "key": "sleevelength",
            "label": "Ärmellänge",
            "type": "",
            "multiSelect": false,
            "values": { "id": 31, "label": "Viertelarm", "value": "viertelarm" }
          },
          "color": {
            "id": 1001,
            "key": "color",
            "label": "Farbe",
            "type": "",
            "multiSelect": false,
            "values": { "id": 9, "label": "Dunkelblau", "value": "dunkelblau" }
          },
          "elasticity": {
            "id": 1010,
            "key": "elasticity",
            "label": "Elastizität",
            "type": "",
            "multiSelect": false,
            "values": {
              "id": 27,
              "label": "Elastisch/strech",
              "value": "elastischstrech"
            }
          },
          "category": {
            "id": 551,
            "key": "category",
            "label": "Master Categories (AG)",
            "type": "",
            "multiSelect": true,
            "values": [
              { "id": 5, "label": "Herren", "value": "5" },
              { "id": 6, "label": "Herren|Bekleidung", "value": "6" },
              { "id": 7, "label": "Herren|Bekleidung|Shirts", "value": "7" }
            ]
          },
          "overallLength": {
            "id": 1009,
            "key": "overallLength",
            "label": "Gesamtlänge",
            "type": "",
            "multiSelect": false,
            "values": { "id": 26, "label": "70 cm", "value": "70_cm" }
          },
          "badges": {
            "id": 1011,
            "key": "badges",
            "label": "Badges",
            "type": "",
            "multiSelect": true,
            "values": [
              {
                "id": 32,
                "label": "Nicht Trocknergeeignet",
                "value": "nicht_trocknergeeignet"
              },
              {
                "id": 33,
                "label": "Nicht heiß Bügeln",
                "value": "nicht_heiss_buegeln"
              },
              {
                "id": 34,
                "label": "30°C Feinwäsche",
                "value": "30c_feinwsche"
              },
              {
                "id": 35,
                "label": "Trockenreinigung mit Perchlorerethylen",
                "value": "trockenreinigung_mit_perchlorerethylen"
              },
              { "id": 36, "label": "Nicht bleichen", "value": "nicht_bleichen" }
            ]
          },
          "countrypermission": {
            "id": 1013,
            "key": "countrypermission",
            "label": "Länderfreigabe",
            "type": "",
            "multiSelect": true,
            "values": [
              { "id": 37, "label": "Deutschland", "value": "deutschland" },
              { "id": 38, "label": "England", "value": "england" },
              { "id": 39, "label": "Spanien", "value": "spanien" }
            ]
          },
          "brandLogo": {
            "id": 20000,
            "key": "brandLogo",
            "label": "Brand logo",
            "type": "",
            "multiSelect": false,
            "values": { "id": 10, "label": "Tommy Hilfiger", "value": "" }
          },
          "length": {
            "id": 1007,
            "key": "length",
            "label": "Länge",
            "type": "",
            "multiSelect": true,
            "values": [
              { "id": 24, "label": "Normale Länge", "value": "normale_lnge" }
            ]
          },
          "producttype": {
            "id": 1004,
            "key": "producttype",
            "label": "Produkttyp",
            "type": "",
            "multiSelect": false,
            "values": { "id": 12, "label": "Shirt", "value": "shirt" }
          },
          "brand": {
            "id": 550,
            "key": "brand",
            "label": "Marke",
            "type": "",
            "multiSelect": false,
            "values": {
              "id": 10,
              "label": "Tommy Hilfiger",
              "value": "tommy_hilfiger"
            }
          }
        },
        "images": [
          {
            "hash": "https://cdn.aboutstatic.com/file/cd81a5d37e4241686586812d9e179553?bg=F4F4F5&quality=75&trim=1&height=1067&width=800,https://cdn.aboutstatic.com/file/1c98f7fc408b9d2cca91abfbf5650df1?bg=F4F4F5&quality=75&height=1067&width=800, https://cdn.aboutstatic.com/f",
            "attributes": {}
          }
        ],
        "customData": {}
      },
      "variantId": 1,
      "productId": 1
    }
  ]
}

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.

// Find key of item and remove it from wishlist
const wishlist = await adminApi.wishlist.get("myshop_customer_1234");
const item = wishlist.items[0];
console.log(item.key);
// c4ca4238a0b923820dcc509a6f75849b

const response = await client.wishlist.deleteItem(
  "myshop_customer_1234",
  item.key
);

console.log(`Items count: ${response.items.length}`);
// Items count: 0

Response

{
  "key": "myshop_customer_1234",
  "items": []
}