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

PreviousCart Management

Last updated