> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/api-references/api-guides/checkout/cart/wishlist.md). # 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`). {% hint style="info" %} 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. {% endhint %} {% hint style="warning" %} 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. {% endhint %} ## 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](/api-references/api-guides/checkout/cart/cart.md#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](https://developer.emporix.io/api-references/api-guides/companies-and-customers/customer-management/api-reference/authentication-and-authorization#post-customer-tenant-login) 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 {% hint style="info" %} 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. {% endhint %} {% stepper %} {% step %} #### 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](https://developer.emporix.io/api-references/api-guides/checkout/cart/api-reference/carts#get-cart-tenant-carts) 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](https://developer.emporix.io/api-references/api-guides/checkout/cart/api-reference/carts#post-cart-tenant-carts)) so you target the correct list. {% hint style="success" %} To test the endpoint, open the API reference or check the example of a curl request. {% endhint %} {% content-ref url="/pages/f8hOR1no1XBBq7IjHBA4" %} [API Reference](/api-references/api-guides/checkout/cart/api-reference.md) {% endcontent-ref %} ```bash 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. {% endstep %} {% step %} #### 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](https://developer.emporix.io/api-references/api-guides/checkout/cart/api-reference/cart-items#post-cart-tenant-carts-cartid-items) endpoint. {% hint style="success" %} To test the endpoint, open the API reference or check the example of a curl request. {% endhint %} {% content-ref url="/pages/f8hOR1no1XBBq7IjHBA4" %} [API Reference](/api-references/api-guides/checkout/cart/api-reference.md) {% endcontent-ref %} ```bash 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 }' ``` {% endstep %} {% step %} #### Remove a wishlist item To remove a single item, call the [Deleting a cart item](https://developer.emporix.io/api-references/api-guides/checkout/cart/api-reference/cart-items#delete-cart-tenant-carts-cartid-items-itemid) endpoint with the wishlist cart ID and item ID. Use the item `id` from the wishlist cart response as `{{itemId}}`. {% hint style="success" %} To test the endpoint, open the API reference or check the example of a curl request. {% endhint %} {% content-ref url="/pages/f8hOR1no1XBBq7IjHBA4" %} [API Reference](/api-references/api-guides/checkout/cart/api-reference.md) {% endcontent-ref %} ```bash curl -i -X DELETE \ 'https://api.emporix.io/cart/{{tenant}}/carts/{{wishlistCartId}}/items/{{itemId}}' \ -H 'Authorization: Bearer {{CUSTOMER_ACCESS_TOKEN}}' \ ``` {% endstep %} {% endstepper %} ## 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. {% stepper %} {% step %} #### 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](https://developer.emporix.io/api-references/api-guides/checkout/cart/api-reference/carts#get-cart-tenant-carts) endpoint (`shopping` and `wishlist`). Use `create=true` on the shopping cart request if the customer does not have an open shopping cart yet. {% hint style="success" %} To test the endpoint, open the API reference or check the example of a curl request. {% endhint %} **Shopping cart** ```bash 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** ```bash 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](https://developer.emporix.io/api-references/api-guides/checkout/cart/api-reference/cart-items#post-cart-tenant-carts-cartid-items) endpoint. {% content-ref url="/pages/f8hOR1no1XBBq7IjHBA4" %} [API Reference](/api-references/api-guides/checkout/cart/api-reference.md) {% endcontent-ref %} ```bash 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 }' ``` {% endstep %} {% step %} #### Remove the product from the wishlist Remove the product from the `type: "wishlist"` cart by calling the [Deleting a cart item](https://developer.emporix.io/api-references/api-guides/checkout/cart/api-reference/cart-items#delete-cart-tenant-carts-cartid-items-itemid) endpoint. {% hint style="success" %} To test the endpoint, open the API reference or check the example of a curl request. {% endhint %} {% content-ref url="/pages/f8hOR1no1XBBq7IjHBA4" %} [API Reference](/api-references/api-guides/checkout/cart/api-reference.md) {% endcontent-ref %} ```bash curl -i -X DELETE \ 'https://api.emporix.io/cart/{{tenant}}/carts/{{wishlistCartId}}/items/{{itemId}}' \ -H 'Authorization: Bearer {{CUSTOMER_ACCESS_TOKEN}}' ``` {% endstep %} {% endstepper %} ## 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. ```mermaid --- config: layout: fixed theme: base themeVariables: primaryColor: '#DDE6EE' primaryBorderColor: '#4C5359' actorBkg: '#DDE6EE' actorBorder: '#4C5359' actorLineColor: '#4C5359' signalColor: '#E86C07' signalTextColor: '#7B8B99' background: transparent --- sequenceDiagram participant Guest participant Storefront participant Storage as Session Storage participant Auth as Customer Service participant Cart as Cart Service Guest->>Storefront: Choose Add to wishlist Storefront->>Storage: Save pending product Storefront->>Guest: Redirect to login Guest->>Storefront: Submit credentials Storefront->>Auth: POST /customer/{tenant}/login Auth-->>Storefront: Customer token Storefront->>Storage: Read pending product Storefront->>Cart: Create or retrieve wishlist cart Storefront->>Cart: POST item with saved productId Storefront->>Storage: Remove pending product ``` Follow these steps to implement wishlist functionality for guest customers on the storefront. {% stepper %} {% step %} #### 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: ```json { "kind": "wishlist-add", "productId": "123", "quantity": 1, "sourcePath": "/product/123" } ``` {% endstep %} {% step %} #### Redirect the customer to login Redirect the customer to the login or registration page. Keep the pending product in `sessionStorage` until login succeeds. {% endstep %} {% step %} #### Log in the customer Log in the customer as described in [Prerequisites](#prerequisites). {% endstep %} {% step %} #### Add the product to the wishlist Read the stored `productId` from `sessionStorage`, then continue with [Create or retrieve a wishlist cart](#create-or-retrieve-a-wishlist-cart) and [Add a product to the wishlist](#add-a-product-to-the-wishlist). Clear the pending product from storage after the item is added. {% endstep %} {% endstepper %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.emporix.io/api-references/api-guides/checkout/cart/wishlist.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.