Skip to main content

Wishlist Management

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

Short Description: The Wishlist Management API provides comprehensive wishlist functionality for the NextGate e-commerce platform. It supports adding products to wishlist, viewing saved items, removing products, clearing wishlist, and moving items directly to cart with real-time pricing and stock information.

Hints:

  • All wishlist operations require user authentication via Bearer token
  • Each user has their own persistent wishlist that maintains state across sessions
  • Prevents duplicate products - each product can only be added once per user
  • Real-time price and stock 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 functionality

Endpoints

1. Add Product to Wishlist

Purpose: Adds a product to the user's wishlist for future purchase consideration

Endpoint: POST /api/v1/wishlist/add

Access Level: 🔒 Protected (Requires authentication)

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"
}

Request Body Parameters:

Parameter Type Required Description Validation
productId UUID Yes ID of the product to add to wishlist Valid UUID, product must exist and not be deleted

Response JSON Sample:

{
  "success": true,
  "message": "Product added to wishlist successfully",
  "data": null
}

Business Logic:

  • Prevents duplicate entries - each product can only be added once per user
  • Only allows non-deleted products to be added
  • No quantity concept in wishlist (unlike cart)

Error Responses:

  • 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 Example:

{
  "success": false,
  "message": "'iPhone 15 Pro' is already in your wishlist",
  "data": null
}

2. Get Wishlist

Purpose: Retrieves the complete wishlist with all saved items, pricing, and availability information

Endpoint: GET /api/v1/wishlist

Access Level: 🔒 Protected (Requires authentication)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication

Response JSON Sample:

{
  "success": true,
  "message": "Wishlist retrieved successfully",
  "data": {
    "user": {
      "userId": "111e2222-e89b-12d3-a456-426614174003",
      "userName": "john.doe",
      "name": "John Doe"
    },
    "wishlistSummary": {
      "totalItems": 4,
      "totalValue": 3596.00,
      "inStockItems": 3,
      "outOfStockItems": 1
    },
    "wishlistItems": [
      {
        "wishlistId": "wish001-e89b-12d3-a456-426614174004",
        "productId": "456e7890-e89b-12d3-a456-426614174001",
        "productName": "iPhone 15 Pro Max 512GB",
        "productSlug": "iphone-15-pro-max-512gb",
        "productImage": "https://example.com/images/iphone15-pro-max.jpg",
        "unitPrice": 1199.00,
        "discountAmount": 100.00,
        "isOnSale": true,
        "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": 25
        },
        "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"
      }
    ],
    "updatedAt": "2025-09-23T10:30:00Z"
  }
}

Response Structure:

User Summary

Field Description
userId Unique identifier of the wishlist owner
userName User's login username
name User's full name (firstName + lastName)

Wishlist Summary

Field Description
totalItems Total number of products in wishlist
totalValue Combined value of all wishlist items at current prices
inStockItems Number of items currently available
outOfStockItems Number of items currently out of stock

Wishlist Item Details

Field Description
wishlistId Unique identifier for the wishlist item
productId Product identifier
productName Current product name
productSlug URL-friendly product identifier
productImage Primary product image URL
unitPrice Current product price
discountAmount Current discount amount (if product on sale)
isOnSale Whether product is currently on sale
shop Shop information (id, name, slug, logo)
availability Real-time stock information
addedAt When item was added to wishlist

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 from Wishlist

Purpose: Removes a specific item from the user's wishlist

Endpoint: DELETE /api/v1/wishlist/{itemId}

Access Level: 🔒 Protected (Requires authentication)

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 ID of the wishlist item to remove Valid UUID, must belong to user's wishlist

Response JSON Sample:

{
  "success": true,
  "message": "Product removed from wishlist successfully",
  "data": null
}

Business Logic:

  • Only allows removing user's own wishlist items
  • Wishlist item is permanently deleted 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

4. Clear Wishlist

Purpose: Removes all items from the user's wishlist

Endpoint: DELETE /api/v1/wishlist/clear

Access Level: 🔒 Protected (Requires authentication)

Authentication: Bearer Token

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authentication

Response JSON Sample:

{
  "success": true,
  "message": "Wishlist cleared successfully",
  "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. Move to Cart

Purpose: Moves a wishlist item directly to the shopping cart with specified quantity

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

Access Level: 🔒 Protected (Requires authentication)

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 ID of the wishlist item to move Valid UUID, must belong to user's wishlist

Query Parameters:

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

Request 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,
  "message": "Product moved to cart successfully",
  "data": null
}

Business Logic:

  • Adds the product to cart using Cart 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

Stock Validation:

  • Validates requested quantity doesn't exceed available stock
  • Leverages cart service stock validation logic
  • Provides detailed error messages for stock issues

Error Responses:

  • 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 Examples:

{
  "success": false,
  "message": "Insufficient stock for 'iPhone 15 Pro'. Only 1 units available",
  "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 endpoints 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 Comparison

Feature Wishlist Cart
Purpose Save for later Ready to purchase
Quantity No quantity concept Specific quantities
Duplicates Prevents duplicates Allows quantity updates
Persistence Permanent until removed Permanent until checkout/clear
Stock Validation Display only Strict validation
Integration Moves to cart Proceeds to checkout

Common Use Cases

  • Save for Later: POST /api/v1/wishlist/add with productId
  • View Saved Items: GET /api/v1/wishlist for complete wishlist
  • Remove Item: DELETE /api/v1/wishlist/{itemId}
  • Clear All: DELETE /api/v1/wishlist/clear
  • Move to Purchase: POST /api/v1/wishlist/move-to-cart/{itemId}?quantity=2

Error Handling Patterns

  • Duplicate Product: Clear message indicating product already saved
  • Stock Issues: Real-time stock validation with detailed messages
  • Authentication: Standard authentication error responses
  • Not Found: Generic messages for security (don't reveal item existence)

No comments to display

Back to top