Wishlist Cart Tutorial

The Cart Service lets a customer keep multiple open carts at the same time by giving each cart a distinct type parameter. Use the type to separate a regular checkout cart (typically shopping) from carts that hold products for later, for example, wishlists or favorites. There is no dedicated wishlist type in the API, and the type is a free-form string you choose. This tutorial uses wishlist as an example, but you can use any value that fits your storefront (for example, favorites or save-for-later). Cart uniqueness is defined by the combination of siteCode, type, legalEntityId, and (sessionId or customerId).

Use the Cart Service with a non-shopping type for save-for-later functionality – choose any value that distinguishes these carts from your regular shopping cart. The Shopping List Service is intended for frequently purchased items and reorder lists, not classic wishlists.

Wishlists should be used by authenticated customers. Although the Cart API allows creating any type of cart for an anonymous session, such carts are assigned to the sessionId and are only accessible during that session. If the guest customer never logs in, the wishlist is lost when the session ends or the token expires. For storefronts, it is better to prompt guest customers to log in before adding products to a wishlist.

How wishlists work

Wishlists require a customerId so saved items persist across visits. Unlike a shopping cart — which can be used anonymously and merged on login (see the How to merge carts in the Cart Tutorial) — a wishlist cart is not suitable for anonymous sessions because session-bound carts are lost when the session ends.

Prerequisites

Log in the customer with the Logging in a customer endpoint to get the {{CUSTOMER_ACCESS_TOKEN}} to authenticate subsequent requests. Use the customer identity from the login response as {{customerId}} when retrieving carts.

How to manage a wishlist for a logged-in customer

The steps below use wishlist as the cart type in all examples. This is not a required value — use any non-shopping type that fits your storefront.

1

Create or retrieve a wishlist cart

Retrieve an existing wishlist cart or create one if none exists by calling the Retrieving a cart by criteria with type=wishlist and create=true. If the customer has several wishlists, use the appropriate type in the query parameters (or create the cart with Creating a new cart) so you target the correct list.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

curl -i -X GET \
  'https://api.emporix.io/cart/{{tenant}}/carts?siteCode=main&customerId={{customerId}}&type=wishlist&create=true' \
  -H 'Authorization: Bearer {{CUSTOMER_ACCESS_TOKEN}}' \

Use the cart id from the response as {{wishlistCartId}} in the following steps.

2

Add a product to the wishlist

Use the same cart item endpoints as for a shopping cart. Provide the wishlist cart ID in the cartId path parameter.

To add a product, call the Adding a product to cart endpoint.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

curl -i -X POST \
  'https://api.emporix.io/cart/{{tenant}}/carts/{{wishlistCartId}}/items?siteCode=main' \
  -H 'Authorization: Bearer {{CUSTOMER_ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "itemYrn": "urn:yaas:saasag:caasproduct:product:{{tenant}};{{productId}}",
    "price": {
      "priceId": "{{priceId}}",
      "effectiveAmount": 50,
      "originalAmount": 50,
      "currency": "EUR"
    },
    "quantity": 1
  }'

3

Remove a wishlist item

To remove a single item, call the Deleting a cart item endpoint with the wishlist cart ID and item ID. Use the item id from the wishlist cart response as {{itemId}}.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

curl -i -X DELETE \
  'https://api.emporix.io/cart/{{tenant}}/carts/{{wishlistCartId}}/items/{{itemId}}' \
  -H 'Authorization: Bearer {{CUSTOMER_ACCESS_TOKEN}}' \

How to move a wishlist item to the shopping cart

To move a wishlist item to the shopping cart, add the product to the customer's shopping cart and remove it from the wishlist cart.

1

Add the product to the shopping cart

• Retrieve the shopping cart and wishlist cart independently using the type query parameter on the Retrieving a cart by criteria endpoint (shopping and wishlist). Use create=true on the shopping cart request if the customer does not have an open shopping cart yet.

To test the endpoint, open the API reference or check the example of a curl request.

Shopping cart

curl -i -X GET \
  'https://api.emporix.io/cart/{{tenant}}/carts?siteCode=main&customerId={{customerId}}&type=shopping&create=true' \
  -H 'Authorization: Bearer {{CUSTOMER_ACCESS_TOKEN}}' \

Wishlist cart

curl -i -X GET \
  'https://api.emporix.io/cart/{{tenant}}/carts?siteCode=main&customerId={{customerId}}&type=wishlist' \
  -H 'Authorization: Bearer {{CUSTOMER_ACCESS_TOKEN}}' \

Use the shopping cart id as {{shoppingCartId}}, the wishlist cart id as {{wishlistCartId}}, and the wishlist item id as {{itemId}}.

• Add the product to the customer's type: "shopping" cart by calling the Adding a product to cart endpoint.

API Reference

curl -i -X POST \
  'https://api.emporix.io/cart/{{tenant}}/carts/{{shoppingCartId}}/items?siteCode=main' \
  -H 'Authorization: Bearer {{CUSTOMER_ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "itemYrn": "urn:yaas:saasag:caasproduct:product:{{tenant}};{{productId}}",
    "price": {
      "priceId": "{{priceId}}",
      "effectiveAmount": 50,
      "originalAmount": 50,
      "currency": "EUR"
    },
    "quantity": 1
  }'

2

Remove the product from the wishlist

Remove the product from the type: "wishlist" cart by calling the Deleting a cart item endpoint.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

curl -i -X DELETE \
  'https://api.emporix.io/cart/{{tenant}}/carts/{{wishlistCartId}}/items/{{itemId}}' \
  -H 'Authorization: Bearer {{CUSTOMER_ACCESS_TOKEN}}'

How to handle guest add-to-wishlist

Guest customers cannot persist a wishlist without logging in. When a guest chooses to add an item to a wishlist on the storefront, the right flow is to first trigger customer authentication. See the below guest flow diagram for details.

Follow these steps to implement wishlist functionality for guest customers on the storefront.

1

Store the pending product

This step belongs to the storefront logic, not a Cart Service call itself. Store the selected product before redirecting to login, for example, in the sessionStorage. After a successful login, read the stored value, add the product to the wishlist cart, then clear it.

Example of storing the pending product:

{
  "kind": "wishlist-add",
  "productId": "123",
  "quantity": 1,
  "sourcePath": "/product/123"
}

2

Redirect the customer to login

Redirect the customer to the login or registration page. Keep the pending product in sessionStorage until login succeeds.

3

Log in the customer

Log in the customer as described in Prerequisites.

4

Add the product to the wishlist

Read the stored productId from sessionStorage, then continue with Create or retrieve a wishlist cart and Add a product to the wishlist. Clear the pending product from storage after the item is added.