Wishlist Management

Author: NextGate Development Team, Backend Engineers Last Updated: 2025-09-22 Version: v1.0

Short Description: The Wishlist API allows authenticated users to manage their product wishlists, including adding/removing products, viewing wishlist contents, and moving items to cart. This service provides comprehensive wishlist management functionality for e-commerce applications.

Hints:

• All endpoints require user authentication via Bearer token

• Product IDs must be valid UUIDs for existing, non-deleted products

• Duplicate products cannot be added to the same user's wishlist

• Moving items to cart automatically removes them from wishlist

• Wishlist items are ordered by creation date (newest first)

---

Endpoints

1. Add Product to Wishlist

Purpose: Adds a product to the authenticated user's wishlist

Endpoint: POST /api/v1/wishlist/add

Access Level: 🔒 Protected (Requires Bearer Token)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for user authentication
Content-Type	string	Yes	Must be "application/json"

Request JSON Sample:

{
  "productId": "123e4567-e89b-12d3-a456-426614174000"
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
productId	UUID	Yes	Unique identifier of the product to add	Must be valid UUID format, product must exist and not be deleted

Response JSON Sample:

{
  "success": true,
  "message": "Product added to wishlist successfully",
  "timestamp": "2025-09-22T14:30:00Z"
}

Response Fields:

Field	Description
success	Boolean indicating operation success
message	Success confirmation message
timestamp	ISO 8601 timestamp of response

Error Responses:

• 400 Bad Request: Invalid request data or validation errors

• 401 Unauthorized: Missing or invalid authentication token

• 404 Not Found: Product not found or user not authenticated

• 422 Unprocessable Entity: Product already exists in wishlist

---

2. Get User's Wishlist

Purpose: Retrieves the authenticated user's complete wishlist with product details and summary

Endpoint: GET /api/v1/wishlist

Access Level: 🔒 Protected (Requires Bearer Token)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for user authentication

Response JSON Sample:

{
  "success": true,
  "message": "Wishlist retrieved successfully",
  "data": {
    "user": {
      "userId": "123e4567-e89b-12d3-a456-426614174000",
      "userName": "johndoe",
      "name": "John Doe"
    },
    "wishlistSummary": {
      "totalItems": 3,
      "totalValue": 299.97,
      "inStockItems": 2,
      "outOfStockItems": 1
    },
    "wishlistItems": [
      {
        "wishlistId": "987fcdeb-51a2-43d1-9c4e-123456789abc",
        "productId": "123e4567-e89b-12d3-a456-426614174000",
        "productName": "Premium Smartphone",
        "productSlug": "premium-smartphone",
        "productImage": "https://example.com/images/smartphone.jpg",
        "unitPrice": 99.99,
        "discountAmount": 10.00,
        "isOnSale": true,
        "shop": {
          "shopId": "456e7890-e12b-34c5-d678-901234567def",
          "shopName": "TechStore",
          "shopSlug": "tech-store",
          "logoUrl": "https://example.com/logos/techstore.jpg"
        },
        "availability": {
          "inStock": true,
          "stockQuantity": 15
        },
        "addedAt": "2025-09-22T10:15:30Z"
      }
    ],
    "updatedAt": "2025-09-22T14:30:00Z"
  },
  "timestamp": "2025-09-22T14:30:00Z"
}

Response Fields:

Field	Description
success	Boolean indicating operation success
message	Success confirmation message
data	Complete wishlist response object
timestamp	ISO 8601 timestamp of response

Error Responses:

• 401 Unauthorized: Missing or invalid authentication token

• 404 Not Found: User not authenticated or not found

---

3. Remove Product from Wishlist

Purpose: Removes a specific product from the authenticated user's wishlist

Endpoint: DELETE /api/v1/wishlist/products/{productId}

Access Level: 🔒 Protected (Requires Bearer Token)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for user authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
productId	UUID	Yes	Unique identifier of the product to remove	Must be valid UUID format

Response JSON Sample:

{
  "success": true,
  "message": "Product removed from wishlist successfully",
  "timestamp": "2025-09-22T14:30:00Z"
}

Response Fields:

Field	Description
success	Boolean indicating operation success
message	Success confirmation message
timestamp	ISO 8601 timestamp of response

Error Responses:

• 401 Unauthorized: Missing or invalid authentication token

• 404 Not Found: Product not found or user not authenticated

---

4. Clear Entire Wishlist

Purpose: Removes all products from the authenticated user's wishlist

Endpoint: DELETE /api/v1/wishlist/clear

Access Level: 🔒 Protected (Requires Bearer Token)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for user authentication

Response JSON Sample:

{
  "success": true,
  "message": "Wishlist cleared successfully",
  "timestamp": "2025-09-22T14:30:00Z"
}

Response Fields:

Field	Description
success	Boolean indicating operation success
message	Success confirmation message
timestamp	ISO 8601 timestamp of response

Error Responses:

• 401 Unauthorized: Missing or invalid authentication token

• 404 Not Found: User not authenticated

---

5. Move Product to Cart

Purpose: Moves a product from wishlist to shopping cart and removes it from wishlist

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

Access Level: 🔒 Protected (Requires Bearer Token)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for user authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
productId	UUID	Yes	Unique identifier of the product to move to cart	Must be valid UUID format

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
quantity	integer	No	Quantity to add to cart	Must be positive integer	1

Response JSON Sample:

{
  "success": true,
  "message": "Product moved to cart successfully",
  "timestamp": "2025-09-22T14:30:00Z"
}

Response Fields:

Field	Description
success	Boolean indicating operation success
message	Success confirmation message
timestamp	ISO 8601 timestamp of response

Error Responses:

• 400 Bad Request: Invalid quantity parameter or cart operation failed

• 401 Unauthorized: Missing or invalid authentication token

• 404 Not Found: Product not found or user not authenticated

• 422 Unprocessable Entity: Product cannot be added to cart

---

Quick Reference Guide

Common HTTP Status Codes

• 200 OK: Successful GET/PUT/PATCH request

• 201 Created: Successful POST request

• 204 No Content: Successful DELETE request

• 400 Bad Request: Invalid request data

• 401 Unauthorized: Authentication required/failed

• 403 Forbidden: Insufficient permissions

• 404 Not Found: Resource not found

• 422 Unprocessable Entity: Validation errors

• 429 Too Many Requests: Rate limit exceeded

• 500 Internal Server Error: Server error

Authentication Types

• Bearer Token: Include Authorization: Bearer your_token in headers

Data Format Standards

• Dates: Use ISO 8601 format (2025-09-22T14:30:00Z)

• Currency: Use smallest currency unit (cents for USD)

• IDs: Use consistent format across endpoints

• Pagination: Include limit, offset, total_count, has_more