Shop It Docs
Developer Resourceswishlist

Wishlist API Reference

Detailed wishlist API contracts, DTOs, request/response payloads, errors, and integration guidance.

Wishlist Module API & Integration Guide

1. How to Read / Quick Metadata

  • Module: Wishlist
  • Auth model: JwtAuthGuard
  • Base URL: /api/wishlist
  • Response envelope: ResponseDto<T>
  • Swagger tag: Wishlist (Mobile)

Route ownership note:

  • APIs are mounted at /api/wishlist/*.
  • There is currently no /api/mobile/wishlist/* route composition.

2. High-Level API Overview

Wishlist API provides customer-authenticated operations to:

  • save sellable products
  • list saved products with optional pagination
  • remove one or many saved products

The API is stateless per request and scoped by authenticated customer identity.

3. Core Concepts and Terminology

  • Wishlist item: server-side saved product row.
  • Saved state: product exists in wishlist for user.
  • Bulk remove request: one API request removing up to 100 product IDs.
  • Pagination metadata: count, currentPage, totalPage returned when pagination=true.

4. Route Summary

MethodPathAuth
POST/api/wishlist/itemsUser JWT
GET/api/wishlist/itemsUser JWT
DELETE/api/wishlist/itemsUser JWT

5. DTO Contracts

5.1 AddWishlistItemDto

{
  "productId": 101
}
FieldTypeRequiredValidation
productIdintegeryes@IsInt(), @Min(1)

5.2 WishlistQueryDto

Query params:

FieldTypeRequiredDefaultValidation
pageintegerno1@IsInt(), @Min(1)
sizeintegerno20@IsInt(), @Min(1)
paginationbooleannotrueboolean transform ("false" => false)

5.3 DeleteWishlistItemsDto

{
  "productIds": [101, 102, 103]
}
FieldTypeRequiredValidation
productIdsinteger[]yes@ArrayMinSize(1), @ArrayMaxSize(100), each @IsInt(), each @Min(1)

5.4 WishlistItemResponseDto

{
  "id": 1,
  "productId": 101,
  "addedAt": "2026-04-23T10:30:00.000Z",
  "productTitle": "Lenovo thinkpad t450s",
  "productSlug": "lenovo-thinkpad-t450s",
  "productThumbnail": "https://cdn.example.com/thumb.jpg",
  "productType": "laptop",
  "productKind": "physical",
  "unitMrp": 20000000,
  "unitSp": 195000,
  "discount": 19805000,
  "averageRating": 4.2,
  "reviewCount": 12
}
FieldTypeNullableDescription
idintegernoWishlist row ID
productIdintegernoProduct ID
addedAtISO timestampnoAdded time
productTitlestringnoProduct title from products.title
productSlugstringnoProduct slug from products.slug
productThumbnailstringyesProduct thumbnail URL
productTypestringyesProduct type name from productTypes.name
productKindenumyesProduct kind (physical, digital, care_package)
unitMrpintegernoMRP in paisa
unitSpintegernoSelling price in paisa
discountintegernoDerived: mrp - sp
averageRatingfloatyesAverage rating from approved reviews. Null if no reviews.
reviewCountintegernoCount of approved reviews

5.5 DeleteWishlistItemsResponseDto

{
  "deletedCount": 2
}
FieldTypeDescription
deletedCountintegerNumber of removed wishlist rows

6. Endpoint Reference

6.1 POST /api/wishlist/items

Purpose

Add a sellable product to the authenticated customer's wishlist.

Request

Headers:

  • Authorization: Bearer <jwt>
  • Content-Type: application/json

Body:

{
  "productId": 101
}

Success Response

HTTP 200

{
  "message": "Product added to wishlist",
  "data": {
    "id": 1,
    "productId": 101,
    "addedAt": "2026-04-23T10:30:00.000Z",
    "productTitle": "Lenovo thinkpad t450s",
    "productSlug": "lenovo-thinkpad-t450s",
    "productThumbnail": "https://cdn.example.com/thumb.jpg",
    "productType": "laptop",
    "productKind": "physical",
    "unitMrp": 20000000,
    "unitSp": 195000,
    "discount": 19805000,
    "averageRating": 4.2,
    "reviewCount": 12
  }
}

Error Responses

HTTPerrorCodeMessageWhen
404WISHLIST_PRODUCT_NOT_FOUNDProduct not found or not availableProduct missing or not sellable
400WISHLIST_ALREADY_EXISTSProduct already in wishlistDuplicate save attempt

6.2 GET /api/wishlist/items

Purpose

Return customer wishlist items in newest-first order.

Request

Headers:

  • Authorization: Bearer <jwt>

Query:

  • page (optional)
  • size (optional)
  • pagination (optional)

Success Response (pagination enabled)

HTTP 200

{
  "message": "Wishlist items fetched",
  "data": [
    {
      "id": 2,
      "productId": 102,
      "addedAt": "2026-04-23T11:10:00.000Z",
      "productTitle": "Dell XPS 15",
      "productSlug": "dell-xps-15",
      "productThumbnail": "https://cdn.example.com/dell-thumb.jpg",
      "productType": "laptop",
      "productKind": "physical",
      "unitMrp": 150000,
      "unitSp": 135000,
      "discount": 15000,
      "averageRating": 4.5,
      "reviewCount": 24
    },
    {
      "id": 1,
      "productId": 101,
      "addedAt": "2026-04-23T10:30:00.000Z",
      "productTitle": "Lenovo thinkpad t450s",
      "productSlug": "lenovo-thinkpad-t450s",
      "productThumbnail": "https://cdn.example.com/lenovo-thumb.jpg",
      "productType": "laptop",
      "productKind": "physical",
      "unitMrp": 20000000,
      "unitSp": 195000,
      "discount": 19805000,
      "averageRating": 4.2,
      "reviewCount": 12
    }
  ],
  "count": 2,
  "currentPage": 1,
  "totalPage": 1
}

Success Response (pagination disabled)

HTTP 200

{
  "message": "Wishlist items fetched",
  "data": [
    {
      "id": 2,
      "productId": 102,
      "addedAt": "2026-04-23T11:10:00.000Z",
      "productTitle": "Dell XPS 15",
      "productSlug": "dell-xps-15",
      "productThumbnail": "https://cdn.example.com/dell-thumb.jpg",
      "productType": "laptop",
      "productKind": "physical",
      "unitMrp": 150000,
      "unitSp": 135000,
      "discount": 15000,
      "averageRating": 4.5,
      "reviewCount": 24
    }
  ]
}

6.3 DELETE /api/wishlist/items

Purpose

Remove one or multiple products from customer's wishlist.

Request

Headers:

  • Authorization: Bearer <jwt>
  • Content-Type: application/json

Body:

{
  "productIds": [101, 102]
}

Success Response

HTTP 200

{
  "message": "Products removed from wishlist",
  "data": {
    "deletedCount": 2
  }
}

Error Responses

HTTPerrorCodeMessageWhen
404WISHLIST_ITEM_NOT_FOUNDProducts not found in wishlistNone of submitted product IDs matched user rows

Behavior note:

  • Partial match delete is allowed. If at least one product matches, endpoint succeeds and returns deleted count.

7. Error Code Reference

Error CodeHTTPDescription
WISHLIST_PRODUCT_NOT_FOUND404Add request product missing or not sellable
WISHLIST_ALREADY_EXISTS400Product already saved in same customer wishlist
WISHLIST_ITEM_NOT_FOUND404Delete request has zero matching wishlist rows

8. Integration Recipes

8.1 Save product recipe

  1. Call POST /api/wishlist/items.
  2. If 200, set UI state to saved.
  3. If WISHLIST_ALREADY_EXISTS, keep UI as saved.

8.2 Render wishlist screen

  1. Initial call: GET /api/wishlist/items?page=1&size=20.
  2. For full non-paginated mode: pagination=false.
  3. Render rows in descending addedAt order.

8.3 Bulk remove recipe

  1. Collect selected product IDs.
  2. Call DELETE /api/wishlist/items.
  3. Remove deleted entries from local state based on result.

9. Integration Diagram

10. Payload Cheatsheet

EndpointRequestSuccess
POST /items{ productId }{ id, productId, addedAt, productTitle, productSlug, productThumbnail, productType, productKind, unitMrp, unitSp, discount, averageRating, reviewCount }
GET /itemspage,size,paginationWishlistItemResponseDto[] (+ optional pagination metadata)
DELETE /items{ productIds[] }{ deletedCount }

11. See Also

Inventory Module Feature List

Inventory feature surfaces, stock lifecycle behavior, and production-readiness checklist.

Wishlist Backend Documentation

Wishlist backend module composition, schema, service contracts, invariants, and operational notes.

On this page

Wishlist Module API & Integration Guide1. How to Read / Quick Metadata2. High-Level API Overview3. Core Concepts and Terminology4. Route Summary5. DTO Contracts5.1 AddWishlistItemDto5.2 WishlistQueryDto5.3 DeleteWishlistItemsDto5.4 WishlistItemResponseDto5.5 DeleteWishlistItemsResponseDto6. Endpoint Reference6.1 POST /api/wishlist/itemsPurposeRequestSuccess ResponseError Responses6.2 GET /api/wishlist/itemsPurposeRequestSuccess Response (pagination enabled)Success Response (pagination disabled)6.3 DELETE /api/wishlist/itemsPurposeRequestSuccess ResponseError Responses7. Error Code Reference8. Integration Recipes8.1 Save product recipe8.2 Render wishlist screen8.3 Bulk remove recipe9. Integration Diagram10. Payload Cheatsheet11. See Also