Wishlist Management

Wishlist API Documentation

Author: Josh S. Sakweli, Backend Lead Team
Last Updated: 2025-09-232026-06-04
Version: v1.0

Base URL: {base_url}/api/v1/e-commerce/wishlist

Short Description: The Wishlist Management API provideslets comprehensiveauthenticated wishlistusers functionalitysave products for thelater, NextGateorganize e-commercethem platform.into Itnamed supportsgroups, addingtransfer productsitems tobetween wishlist, viewing saved items, removing products, clearing wishlist,groups, and movingmove items directly to cartthe withcart. real-timeEvery pricingwishlist operation is strictly private — users can only read and stockmodify information.their own wishlist.

Hints:

• All wishlist operationsendpoints require a valid JWT Bearer token — there are no public wishlist endpoints
• When adding a product, pass either groupId (existing group) or groupName (creates a new group) — passing both returns 400
• Group names are unique per user authentication— viaattempting Bearerto create a duplicate name returns 400
• Deleting a group with ?deleteProducts=false (default) moves all items in that group to Ungrouped; ?deleteProducts=true permanently removes those items from the wishlist
• PATCH /{itemId}/group with groupId: null moves an item to Ungrouped without deleting it
• isInWishlist, wishlistItemId, wishlistGroupId, and wishlistGroupName are populated on the single product detail response (GET /api/v1/e-commerce/products/{slug}) for authenticated users

---

Standard Response Format

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {}
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-09-23T10:30:45",
  "data": "Error description"
}

Standard Response Fields

Field	Type	Description
success	boolean	true for successful operations, false for errors
httpStatus	string	HTTP status name (OK, BAD_REQUEST, NOT_FOUND, etc.)
message	string	Human-readable message describing the result
action_time	string	ISO 8601 timestamp of when the response was generated
data	object/string	Response payload on success, error details on failure

Standard Error Types

• 400 BAD_REQUEST: Business rule violation (duplicate product, duplicate group name, ambiguous group fields)
• 401 UNAUTHORIZED: Missing, expired, or invalid JWT token
• Each404 userNOT_FOUND: has their own persistentProduct, wishlist thatitem, maintainsor stategroup acrossnot sessionsfound
• Prevents422 duplicateUNPROCESSABLE_ENTITY: productsValidation -errors eachwith productfield-level can only be added once per userdetail
• Real-time500 priceINTERNAL_SERVER_ERROR: andUnexpected stockserver information displayed for all wishlist items
• Supports moving items directly from wishlist to cart with specified quantity
• Wishlist items show current product pricing (prices may change after adding)
• Only existing products can be added to wishlist (deleted products filtered out)
• Wishlist persistence survives user logout/login cycles
• Integration with cart service for seamless move-to-cart functionalityerror

---

Endpoints

1. Add Product to Wishlist

Purpose: Adds a product to the authenticated user's wishlistwishlist. forOptionally futureplaces purchaseit considerationin an existing group (via groupId) or creates a new group on the fly (via groupName). If neither is provided the item lands in Ungrouped.

Endpoint: POST {base_url}/api/v1/e-commerce/wishlist/add

Access Level: 🔒 Protected (Requires authentication)valid JWT)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer <token for authentication
Content-Type	string	Yes	application/json>

Request JSON Sample:

{
  "productId": "456e7890-e89b-12d3-a456-426614174001"a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "groupName": "Birthday Gifts"
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
productId	UUID	Yes	ID of the product to add	Must be a valid, non-deleted product
groupId	UUID	No	Add to wishlistan existing group	ValidMust UUID,belong to the authenticated user. Cannot be combined with groupName
groupName	string	No	Create a new group with this name and add product mustto it	Must not already exist andfor notthis user. Cannot be deletedcombined with groupId

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Product added to wishlist successfully"in group 'Birthday Gifts'",
  "action_time": "2026-06-04T14:22:10",
  "data": null
}

BusinessSuccess LogicResponse Fields:

• Prevents
duplicateentries-each
• Only
allowsnon-deleted products to be added
• No quantity concept in wishlist (unlike cart)

Field	Description
message	Confirms the product canwas onlyadded; beincludes addedgroup oncename perwhen userapplicable

Error Responses:

Response
JSON
• 400 Bad Request: Invalid productId format
• 401 Unauthorized: Authentication required or invalid token
• 404 Not Found: Product not found or has been deleted
• 422 Unprocessable Entity: Product already in wishlist

Error ExampleSample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "'iPhoneSony 15 Pro'WH-1000XM5' is already in your wishlist",
  "action_time": "2026-06-04T14:22:10",
  "data": null"'Sony WH-1000XM5' is already in your wishlist"
}

---

2. Get Wishlist (Flat)

Purpose: RetrievesReturns the completeauthenticated user's full wishlist withas alla savedflat items,list. pricing,Each item includes its group ID and availabilitygroup informationname (or null if Ungrouped). Useful for list views where grouping is handled client-side.

Endpoint: GET {base_url}/api/v1/e-commerce/wishlist

Access Level: 🔒 Protected (Requires authentication)valid JWT)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer <token for authentication>

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Wishlist retrieved successfully",
  "action_time": "2026-06-04T14:22:10",
  "data": {
    "user": {
      "userId": "111e2222-e89b-12d3-a456-426614174003"uuid",
      "userName": "john.doe"josh_dev",
      "name": "JohnJosh Doe"Sakweli"
    },
    "wishlistSummary": {
      "totalItems": 4,3,
      "totalValue": 3596.00,749.97,
      "inStockItems": 3,2,
      "outOfStockItems": 1
    },
    "wishlistItems": [
      {
        "wishlistId": "wish001-e89b-12d3-a456-426614174004"uuid",
        "productId": "456e7890-e89b-12d3-a456-426614174001"uuid",
        "productName": "iPhoneSony 15 Pro Max 512GB"WH-1000XM5",
        "productSlug": "iphone-15-pro-max-512gb"sony-wh-1000xm5",
        "productImage": "https://cdn.example.com/images/iphone15-pro-max.img.jpg",
        "unitPrice": 1199.00,
        "discountAmount": 100.00,349.99,
        "isOnSale": true,false,
        "shop": {
          "shopId": "123e4567-e89b-12d3-a456-426614174000"uuid",
          "shopName": "TechStoreTech Pro"Haven",
          "shopSlug": "techstore-pro"tech-haven",
          "logoUrl": "https://cdn.example.com/logos/techstore-pro.png"logo.jpg"
        },
        "availability": {
          "inStock": true,
          "stockQuantity": 2512
        },
        "groupId": "uuid",
        "groupName": "Birthday Gifts",
        "addedAt": "2025-09-23T10:30:00Z"
      },
      {
        "wishlistId": "wish002-e89b-12d3-a456-426614174005",
        "productId": "567e8901-e89b-12d3-a456-426614174002",
        "productName": "MacBook Air M3",
        "productSlug": "macbook-air-m3",
        "productImage": "https://example.com/images/macbook-air-m3.jpg",
        "unitPrice": 999.00,
        "discountAmount": 0.00,
        "isOnSale": false,
        "shop": {
          "shopId": "123e4567-e89b-12d3-a456-426614174000",
          "shopName": "TechStore Pro",
          "shopSlug": "techstore-pro",
          "logoUrl": "https://example.com/logos/techstore-pro.png"
        },
        "availability": {
          "inStock": true,
          "stockQuantity": 8
        },
        "addedAt": "2025-09-22T14:15:00Z"
      },
      {
        "wishlistId": "wish003-e89b-12d3-a456-426614174006",
        "productId": "678e9012-e89b-12d3-a456-426614174003",
        "productName": "Samsung Galaxy Watch 6",
        "productSlug": "samsung-galaxy-watch-6",
        "productImage": "https://example.com/images/galaxy-watch-6.jpg",
        "unitPrice": 299.00,
        "discountAmount": 50.00,
        "isOnSale": true,
        "shop": {
          "shopId": "234e5678-e89b-12d3-a456-426614174001",
          "shopName": "Gadget World",
          "shopSlug": "gadget-world",
          "logoUrl": "https://example.com/logos/gadget-world.png"
        },
        "availability": {
          "inStock": false,
          "stockQuantity": 0
        },
        "addedAt": "2025-09-21T09:45:00Z"2026-06-04T10:00:00"
      }
    ],
    "updatedAt": "2025-09-23T10:30:00Z"2026-06-04T10:00:00"
  }
}

Success Response StructureFields:

User Summary

Field	Description
user.userId	Unique identifierUUID of the wishlistauthenticated owneruser
user.userName	User's loginSystem username
user.name	User's fullFull name (firstName + lastName)

Wishlist Summary

Field	Description
wishlistSummary.totalItems	Total number of productsitems in the wishlist
wishlistSummary.totalValue	CombinedSum valueof unit prices of all wishlist items at current prices
wishlistSummary.inStockItems	NumberCount of items currently availablein stock
wishlistSummary.outOfStockItems	NumberCount of items currently out of stock

Wishlist Item Details

towishlist

Field	Description
wishlistItems[].wishlistId	UniqueUUID identifier forof the wishlist itementry (used for remove/transfer)
wishlistItems[].productId	ProductUUID identifierof the product
wishlistItems[].productName	CurrentProduct productdisplay name
wishlistItems[].productSlug	URL-friendly product identifier
wishlistItems[].productImage	PrimaryURL of the primary product image URL
wishlistItems[].unitPrice	Current price of the product price
discountAmount	Current discount amount (if product on sale)
wishlistItems[].isOnSale	Whether the product is currently on sale
wishlistItems[].shop	Shop informationthat sells the product (id, name, slug, logo)
availabilitywishlistItems[].availability.inStock	Real-timeWhether the product is in stock information
addedAtwishlistItems[].availability.stockQuantity	WhenCurrent stock count
wishlistItems[].groupId	UUID of the group this item belongs to (null if Ungrouped)
wishlistItems[].groupName	Name of the group (null if Ungrouped)
wishlistItems[].addedAt	Timestamp when the product was added
updatedAt	Timestamp of the most recently added item

Real-time Information:

• Prices reflect current product pricing (may differ from when added)
• Stock quantities show real-time availability
• Sale status and discounts updated automatically

Error Responses:

• 401 Unauthorized: Authentication required
• 404 Not Found: User not found

---

3. Remove fromGet Wishlist (Grouped)

Purpose: RemovesReturns the wishlist organized into sections — one section per named group plus a specificseparate itemUngrouped fromsection. theUseful user'sfor wishlistgrouped display views.

Endpoint: DELETEGET {base_url}/api/v1/e-commerce/wishlist/{itemId}grouped

Access Level: 🔒 Protected (Requires authentication)valid JWT)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer <token for authentication>

PathSuccess Parameters:

Parameter	Type	Required	Description	Validation
itemId	UUID	Yes	ID of the wishlist item to remove	Valid UUID, must belong to user's wishlist

Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Product removed fromGrouped wishlist retrieved successfully",
  "action_time": "2026-06-04T14:22:10",
  "data": null{
    "user": {
      "userId": "uuid",
      "userName": "josh_dev",
      "name": "Josh Sakweli"
    },
    "wishlistSummary": {
      "totalItems": 3,
      "totalValue": 749.97,
      "inStockItems": 2,
      "outOfStockItems": 1
    },
    "groups": [
      {
        "groupId": "uuid",
        "groupName": "Birthday Gifts",
        "itemCount": 2,
        "items": [ ]
      }
    ],
    "ungrouped": {
      "groupId": null,
      "groupName": "Ungrouped",
      "itemCount": 1,
      "items": [ ]
    },
    "updatedAt": "2026-06-04T10:00:00"
  }
}

BusinessSuccess LogicResponse Fields:

• Only
allowsremovinguser'sown
• Wishlist
ispermanentlydeleted from database
• No undo functionality available

Error Responses:

• 401 Unauthorized: Authentication required
• 404 Not Found: Wishlist item not found or doesn't belong to user

Field	Description
user	Same user summary as flat response
wishlistSummary	Same summary totals across all items
groups	Array of named group sections, ordered by creation date (oldest first)
groups[].groupId	UUID of the group
groups[].groupName	Name of the group
groups[].itemCount	Number of items in this group
groups[].items	Array of wishlist item responses (same shape as flat list items)
ungrouped	Section for items with no group assigned
ungrouped.groupId	Always null
ungrouped.groupName	Always "Ungrouped"
ungrouped.itemCount	Count of items with no group
ungrouped.items	Array of ungrouped wishlist items
updatedAt	Timestamp of the most recently added item

---

4. ClearRemove Item from Wishlist

Purpose: RemovesPermanently allremoves itemsa specific item from the authenticated user's wishlistwishlist.

Endpoint: DELETE {base_url}/api/v1/e-commerce/wishlist/clear{itemId}

Access Level: 🔒 Protected (Requires authentication)valid JWT — owns the item)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer <token for authentication>

Path Parameters:

Parameter	Type	Required	Description	Validation
itemId	UUID	Yes	The wishlistId of the item to remove	Must belong to the authenticated user

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "WishlistProduct clearedremoved from wishlist successfully",
  "action_time": "2026-06-04T14:22:10",
  "data": null
}

Business Logic:

• Removes all wishlist items for the authenticated user
• Permanent deletion - cannot be undone
• Wishlist becomes empty after operation

Use Cases:

• User wants to start fresh with empty wishlist
• Bulk cleanup of saved items
• Administrative wishlist reset

Error Responses:

• 401 Unauthorized: Authentication required
• 404 Not Found: User not found

---

5. MoveClear to CartWishlist

Purpose: MovesPermanently aremoves wishlistall itemitems directly tofrom the shoppingauthenticated cartuser's withwishlist. specifiedGroups quantityare not deleted — only the items inside them.

Endpoint: POSTDELETE {base_url}/api/v1/e-commerce/wishlist/move-to-cart/{itemId}clear

Access Level: 🔒 Protected (Requires authentication)valid JWT)

Authentication: Bearer Token

Request Headers:

forauthentication

Header	Type	Required	Description
Authorization	string	Yes	Bearer <token>

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Wishlist cleared successfully",
  "action_time": "2026-06-04T14:22:10",
  "data": null
}

---

6. Move Item to Cart

Purpose: Adds a wishlist item to the user's cart at the specified quantity. The item remains in the wishlist — it is not automatically removed.

Endpoint: POST {base_url}/api/v1/e-commerce/wishlist/move-to-cart/{itemId}

Access Level: 🔒 Protected (Requires valid JWT)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer <token>

Path Parameters:

Parameter	Type	Required	Description	Validation
itemId	UUID	Yes	IDThe wishlistId of the wishlist item to move	Valid UUID, mustMust belong to user'sthe wishlistauthenticated user

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
quantity	integer	No	Quantity to add to cart	Min: 1, must not exceed available stock1	1

RequestSuccess URL Examples:

POST /api/v1/wishlist/move-to-cart/wish001-e89b-12d3-a456-426614174004
POST /api/v1/wishlist/move-to-cart/wish001-e89b-12d3-a456-426614174004?quantity=2

Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Product moved to cart successfully",
  "action_time": "2026-06-04T14:22:10",
  "data": null
}

---

7. Transfer Item to Group

Purpose: Moves a wishlist item to a different group, or removes it from its current group by setting groupId to null (moves to Ungrouped). The item stays in the wishlist — only its group assignment changes.

Endpoint: PATCH {base_url}/api/v1/e-commerce/wishlist/{itemId}/group

Access Level: 🔒 Protected (Requires valid JWT — owns the item)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer <token>

Path Parameters:

Parameter	Type	Required	Description	Validation
itemId	UUID	Yes	The wishlistId of the item to transfer	Must belong to the authenticated user

Request JSON Sample — move to a group:

{
  "groupId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Request JSON Sample — remove from group (move to Ungrouped):

{
  "groupId": null
}

BusinessRequest LogicBody Parameters:

• Adds
cartusingCart Service integration
• Uses specified quantity (default: 1)
• Validates stock availability before adding to cart
• Keeps item in wishlist after moving to cart (doesn't remove)
• If product already in cart, increases quantity

Parameter	Type	Required	Description	Validation
groupId	UUID or null	Yes	Target group UUID, or null to move to Ungrouped	When a UUID, must be a group that belongs to the productauthenticated touser

StockSuccess ValidationResponse JSON Sample:

{
  
Validates"success": requestedtrue,
  quantity"httpStatus": doesn't"OK",
  exceed"message": available"Item stock
moved 
Leveragesto cartgroup service'Electronics'",
  stock"action_time": validation"2026-06-04T14:22:10",
  logic
"data": 
Providesnull
detailed}
error

messages

---

8. Create Group

Purpose: Creates a new named wishlist group for stockthe issuesauthenticated

user. Group names must be unique per user.

Endpoint: POST {base_url}/api/v1/e-commerce/wishlist/groups

Access Level: 🔒 Protected (Requires valid JWT)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer <token>

Request JSON Sample:

{
  "name": "Electronics"
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
name	string	Yes	Display name for the group	Must not be blank. Must be unique for the authenticated user

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Wishlist group created successfully",
  "action_time": "2026-06-04T14:22:10",
  "data": {
    "groupId": "uuid",
    "name": "Electronics",
    "itemCount": 0,
    "createdAt": "2026-06-04T14:22:10"
  }
}

Success Response Fields:

Field	Description
groupId	UUID of the newly created group
name	Name of the group as saved
itemCount	Always 0 on creation
createdAt	Timestamp of group creation

Error Responses:

Response
JSON
• 401 Unauthorized: Authentication required
• 404 Not Found: Wishlist item not found or product no longer available
• 422 Unprocessable Entity: Insufficient stock for requested quantity

Error ExamplesSample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "InsufficientA stockgroup fornamed 'iPhoneElectronics' 15already Pro'exists",
  "action_time": "2026-06-04T14:22:10",
  "data": "A group named 'Electronics' already exists"
}

---

9. Get Groups

Purpose: Returns all wishlist groups created by the authenticated user, ordered by creation date (oldest first). OnlyEach 1group unitsincludes available"a live item count.

Endpoint: GET {base_url}/api/v1/e-commerce/wishlist/groups

Access Level: 🔒 Protected (Requires valid JWT)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer <token>

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Wishlist groups retrieved successfully",
  "action_time": "2026-06-04T14:22:10",
  "data": [
    {
      "groupId": "uuid",
      "name": "Birthday Gifts",
      "itemCount": 3,
      "createdAt": "2026-06-01T09:00:00"
    },
    {
      "groupId": "uuid",
      "name": "Electronics",
      "itemCount": 1,
      "createdAt": "2026-06-03T11:30:00"
    }
  ]
}

Success Response Fields:

Field	Description
[].groupId	UUID of the group
[].name	Display name of the group
[].itemCount	Current number of wishlist items in this group
[].createdAt	Timestamp of group creation

---

10. Delete Group

Purpose: Deletes a wishlist group. Controls what happens to the items inside via the deleteProducts query parameter.

Endpoint: DELETE {base_url}/api/v1/e-commerce/wishlist/groups/{groupId}

Access Level: 🔒 Protected (Requires valid JWT — owns the group)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer <token>

Path Parameters:

Parameter	Type	Required	Description	Validation
groupId	UUID	Yes	UUID of the group to delete	Must belong to the authenticated user

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
deleteProducts	boolean	No	true → permanently delete all items in the group from wishlist. false → move items to Ungrouped, then delete group	true or false	false

Success Response JSON Sample — items moved to Ungrouped:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Group deleted, products moved to Ungrouped",
  "action_time": "2026-06-04T14:22:10",
  "data": null
}

Success Response JSON Sample — items permanently deleted:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Group and all its products deleted from wishlist",
  "action_time": "2026-06-04T14:22:10",
  "data": null
}

---

Quick Reference Guide

Common HTTP Status Codes

• 200 OK: Successful GET/POST/DELETE request
• 400 Bad Request: Invalid request data or validation errors
• 401 Unauthorized: Authentication required or invalid token
• 404 Not Found: Wishlist item, product, or user not found
• 422 Unprocessable Entity: Duplicate product or stock validation errors
• 500 Internal Server Error: Server error during processing

Authentication Requirements

• Bearer Token: Include Authorization: Bearer your_token in headers
• All endpointsEndpoints require authentication - no public wishlist operations
• User-specific wishlists - each user has their own isolated wishlist

Data Format Standards

• Dates: ISO 8601 format (2025-09-23T14:30:00Z)
• Prices: Decimal with 2 decimal places (999.00)
• UUIDs: Standard UUID format (123e4567-e89b-12d3-a456-426614174000)

Business Rules

Wishlist Management

• One Product Per User: Each product can only be added once per user
• No Quantity Concept: Wishlist doesn't store quantities (unlike cart)
• Real-time Pricing: Prices shown are current, not when added
• Stock Awareness: Shows current availability status
• Persistent Storage: Survives logout/login cycles
• No Expiration: Items remain until manually removed

Integration with Cart

• Move to Cart: Seamless integration with cart service
• Stock Validation: Validates availability when moving to cart
• Quantity Support: Can specify quantity when moving to cart
• Preserves Wishlist: Item remains in wishlist after moving to cart

Wishlist vs Cart ComparisonSummary

quantitiesquantityuntilvalidation

Feature#	WishlistMethod	CartPath	Description
Purpose1	Save for laterPOST	Ready/wishlist/add	Add product to purchasewishlist
Quantity2	No quantity conceptGET	Specific/wishlist	Get flat wishlist
Duplicates3	Prevents duplicatesGET	Allows/wishlist/grouped	Get updatesgrouped wishlist
Persistence4	Permanent until removedDELETE	Permanent/wishlist/{itemId}	Remove checkout/clearitem from wishlist
Stock Validation5	Display onlyDELETE	Strict/wishlist/clear	Clear entire wishlist
Integration6	MovesPOST	/wishlist/move-to-cart/{itemId}	Move item to cart
Proceeds7	PATCH	/wishlist/{itemId}/group	Transfer item to checkoutgroup
8	POST	/wishlist/groups	Create group
9	GET	/wishlist/groups	Get all groups
10	DELETE	/wishlist/groups/{groupId}	Delete group

CommonGroup UseBehavior CasesRules

• Save
forLater:POST/api/v1/wishlist/add Savedforcompletewishlist

Error

Handling Patterns
• Duplicate Product: Clear message indicating product already saved
• Stock Issues: Real-time stock validation
reveal

Scenario	Behavior
Add with productIdno Viewgroup	Item Items:lands GETin /api/v1/wishlistUngrouped
Add Removewith groupId	Item: DELETE /api/v1/wishlist/{itemId} Clear All: DELETE /api/v1/wishlist/clear Moveadded to Purchase:that POSTexisting /api/v1/wishlist/move-to-cart/{itemId}?quantity=2 group
Add with detailed messages Authentication: Standard authentication error responses Not Found: Generic messages for securitygroupName (don'tnew)	New group created, item existence)added to it
Add with groupName (exists)	400 — duplicate group name
Add with both groupId and groupName	400 — ambiguous request
Delete group ?deleteProducts=false	Items move to Ungrouped, group deleted
Delete group ?deleteProducts=true	Items permanently removed, group deleted
Transfer item with groupId: null	Item moved to Ungrouped