Catalog Product - API & Integration Guide

1. How to Read / Quick Metadata

• Module: Catalog / Product
• Admin auth: JwtAuthGuard + RoleGuard + @Permissions(Products_*)
• Customer/mobile auth: public endpoints (@Public())
• Surfaces:
  • Admin: /api/admin/products
  • Customer: /api/products
  • Mobile: /api/mobile/products

Audience: Mobile/web frontend developers Scope: Product discovery, detail endpoints

2. High-Level Overview

Product APIs provide admin lifecycle management and public browse/detail surfaces for published sellable products. Product detail accepts historical slugs and resolves to the current canonical product.

3. Core Concepts and Terminology

• Sellable visibility: customer APIs only return isSellable=true and status=published.
• Canonical slug: current slug returned in payload.
• Historical slug: old slug stored in product_slug_history and still resolvable.
• Featured list endpoint: curated subset exposed by GET /products/featured.
• Availability endpoint: live stock status exposed by GET /products/:slug/availability (uncached for UI stock correctness).

4. Route Summary

Admin

Customer + Mobile

Route Details

List Products

Product Detail

Product Availability

Availability payload:

• canAddToCart: boolean
• stockStatus: "in_stock" | "low_stock" | "out_of_stock"
• availableQuantity: number | null
• maxPurchasableQuantity: number

Computation rules:

• status !== published or isSellable=false => out-of-stock (canAddToCart=false)
• trackInventory=false or allowOversell=true => in stock with availableQuantity=null, maxPurchasableQuantity=99
• tracked inventory with availableQuantity <= 0 => out-of-stock
• tracked inventory with availableQuantity > 0 => in_stock or low_stock by threshold
• missing product_inventory row for physical product => out-of-stock (safe default)

5. Query Parameters

5.1 Admin list (GET /api/admin/products)

5.2 Customer list (GET /api/products)

5.3 Featured list (GET /api/products/featured)

5.4 Discovery endpoints

All discovery endpoints accept page, size, and pagination from the base QueryDto. No sort/order parameters — results are always sorted by createdAt descending.

6. Response Shape Examples

6.1 Product list item (with average rating)

{
  "id": 101,
  "title": "Dell XPS 15 Laptop",
  "slug": "dell-xps-15-laptop",
  "shortSummary": "High-performance laptop with OLED display.",
  "thumbnailUrl": "https://cdn.example.com/products/dell-xps-15/thumbnail.jpg",
  "productTypeId": 1,
  "productType": {
    "id": 1,
    "name": "Laptop",
    "slug": "laptop"
  },
  "productKind": "physical",
  "mrp": 150000,
  "sp": 135000,
  "discount": 15000,
  "isBestSeller": true,
  "averageRating": 4.2,
  "reviewCount": 12,
  "categoryId": 3,
  "category": {
    "name": "Laptops",
    "slug": "laptops"
  },
  "brand": {
    "id": 2,
    "name": "Dell",
    "slug": "dell",
    "imageUrl": "https://cdn.example.com/brands/dell.png"
  }
}

• averageRating is null when no approved reviews exist.
• reviewCount is 0 when no approved reviews exist.
• category is omitted when categoryId is null.
• brand is null when the product has no brand association.

6.2 Product detail response example

{
  "id": 101,
  "title": "Hand-Painted Green Tara Thangka",
  "slug": "hand-painted-green-tara-thangka",
  "shortSummary": "Traditional Green Tara thangka painted by Kathmandu artisans.",
  "description": "Authentic Green Tara thangka created using natural pigments on cotton canvas.",
  "productKind": "physical",
  "productTypeId": 1,
  "productType": {
    "id": 1,
    "name": "Thangka",
    "slug": "thangka"
  },
  "isBestSeller": true,
  "specifications": {
    "material": "Cotton canvas",
    "pigment": "Natural mineral"
  },
  "mrp": 15000,
  "sp": 12000,
  "discount": 3000,
  "currency": "USD",
  "totalReviews": 12,
  "averageRating": 4.5,
  "reviewStatus": "Reviews available",
  "thumbnailUrl": "https://cdn.example.com/products/thangka/thumbnail.jpg",
  "galleryUrls": [
    "https://cdn.example.com/products/thangka/gallery-1.jpg",
    "https://cdn.example.com/products/thangka/gallery-2.jpg"
  ],
  "isSellable": true,
  "categoryId": 3,
  "category": {
    "id": 3,
    "name": "Thangka Paintings",
    "slug": "thangka-paintings"
  },
  "brand": null,
  "tags": [
    { "id": 7, "name": "Handcrafted in Nepal", "slug": "handcrafted-in-nepal" }
  ],
  "createdAt": "2026-02-21T10:00:00.000Z"
}

7. Enums

• productKind: physical | digital | care_package
• productStatus (admin flows): draft | published | unlisted | archived
• Sort enums follow DTO-level allowlists (admin/customer differ).

8. Integration Diagram

9. Caching

GET /products/:slug/availability is intentionally uncached so stock actions (Add to Cart, Purchase Now) use live inventory status.

Write invalidation happens on admin create/update/delete via prefix invalidation. All discovery caches (new-arrivals, popular, trending, best-sellers) are invalidated on the same mutation events as the main product list cache.

10. Error Handling

11. Endpoint Reference + Payload Cheatsheet

11.1 Payload Cheatsheet Table (Every Endpoint)

11.1.1 Admin List Endpoint Query Variations

11.1.2 Customer/Mobile List Endpoint Query Variations

11.1.3 Featured Products Query Variations

11.1.3.1 Discovery Endpoints Query Variations

11.1.4 Create Product Request Variations

11.1.5 Update Product Request Variations

11.1.6 Product Status Flow States

11.1.7 Product Kind Availability Behavior

11.1.8 Error Response Variations

11.1.9 Cache Key Patterns

11.1.10 Rate Limit Patterns

11.1.11 DTO Field Reference

CreateProductDto

| Field | Type | Required | Validation | Notes | |---|---|---|---|---|---| | title | string | Yes | 1-200 chars | Product title | | slug | string | Yes | 1-100 chars, URL-safe | URL slug | | description | string | No | Max 5000 chars | Full description | | shortSummary | string | No | Max 500 chars | Brief summary | | productKind | enum | Yes | physical | digital | care_package | Determines availability behavior and fulfillment type | | productTypeId | integer | Yes | Positive | FK to product_type.id | | brandId | integer | No | Positive | Brand reference — nullable FK to brand.id | | specifications | object | No | JSON object | Flexible per-product-type specs (e.g. processor, ram, coverage) | | isBestSeller | boolean | Yes | boolean | Bestseller product flag | | mrp | number | Yes | Positive integer | Maximum retail price (integer minor units) | | sp | number | Yes | Positive integer, not more than mrp | Selling price (integer minor units) | | categoryId | integer | Yes | Positive | Category reference | | tagIds | number[] | No | Valid unique positive tag IDs | Tag references | | thumbnailUrl | string | No | Valid URL | Thumbnail image | | galleryUrls | string[] | No | Valid URLs | Product gallery images | | metadata | object | No | JSON object | Product metadata | | mainFileUrl | string | No | Valid URL | Main downloadable/media file URL | | previewFileUrl | string | No | Valid URL | Preview file URL | | attachments | object[] | No | name/url/type fields | Additional asset attachments | | isSellable | boolean | No | boolean | Sellable visibility | | status | enum | No | draft|published|unlisted|archived | Initial status |

UpdateProductDto

QueryProductsDto / QueryProductsAdminDto

ProductListItemDto

ProductResponseDto

FetchNewArrivalsDto

FetchDiscoveryDto (shared by popular/trending)

12. Testing Scenarios

12.1 Suggested Test Scenarios

• Admin creates product with all fields, publishes it, and product appears in customer list.
• Product slug changed in admin; old slug still resolves to canonical detail via historical slug fallback.
• Customer list only returns isSellable=true and status=published products; draft products hidden.
• Customer with search query "tara" returns matching products by title, shortSummary, or description.
• Featured products endpoint returns only active slots with in-window date ranges.
• 429 rate limit exceeded on customer list/search with sliding window Redis keys.
• New arrivals endpoint with withinDays=7 returns only products created within the last 7 days, sorted newest first.
• Popular endpoint excludes products with expired isBestSellerExpiresAt, even when isBestSeller=true.
• Trending endpoint excludes products with expired trendingExpiresAt, even when isTrending=true.
• Brand filter (?brandId=2) correctly scopes discovery endpoint results.
• Filter by minRating=4 on customer list returns only products with average approved rating >= 4.
• Sort by rating on customer list returns products ordered by descending average rating.
• PRODUCT_BRAND_NOT_FOUND returned for invalid brand ID in discovery filters.
• PRODUCT_INVALID_WITHIN_DAYS returned for withinDays value outside 1-365 range.

13. Discovery Endpoints — Detail

13.1 New Arrivals

• Endpoint: GET /api/products/new-arrivals
• Auth: Public
• Purpose: Surface recently created products, ideal for "New In" or "Just Arrived" sections.
• Core logic: createdAt >= NOW() - withinDays INTERVAL, sorted by createdAt DESC.
• Parameters: withinDays (1-365, default 30), categoryId, brandId, page, size.
• DTO: FetchNewArrivalsDto
• Cache prefix: catalog:products:new-arrivals:

Cache key incorporates withinDays, categoryId, brandId, page, and size.

13.2 Popular

• Endpoint: GET /api/products/popular
• Auth: Public
• Purpose: Surface products flagged as best sellers, ideal for "Popular" or "Best Sellers" sections.
• Core logic: isBestSeller = true AND (isBestSellerExpiresAt IS NULL OR isBestSellerExpiresAt > NOW()), sorted by createdAt DESC.
• Parameters: categoryId, brandId, page, size.
• DTO: FetchDiscoveryDto
• Cache prefix: catalog:products:popular:

13.3 Trending

• Endpoint: GET /api/products/trending
• Auth: Public
• Purpose: Surface products flagged as trending, ideal for "Trending Now" sections.
• Core logic: isTrending = true AND (trendingExpiresAt IS NULL OR trendingExpiresAt > NOW()), sorted by createdAt DESC.
• Parameters: categoryId, brandId, page, size.
• DTO: FetchDiscoveryDto
• Cache prefix: catalog:products:trending:

13.4 Best Sellers

• Endpoint: GET /api/products/best-sellers
• Auth: Public
• Purpose: Same semantics as Popular — returns isBestSeller=true products with valid expiry.
• Difference: Separate cache prefix (catalog:products:best-sellers:) allows independent cache management.

13.5 Brand-Series Detail

• Endpoint: GET /api/brand-series/:slug
• Auth: Public
• Purpose: Returns brand series detail with nested product listing for that series.
• Resolution: Series slug resolved through brand_series_slug_history for historical slug support.

See Also

• Feature Guide: See Catalog Product - Feature List Section 17 (Release/QA Checklist) for product lifecycle and Section 13-16 for filter, sort, rating, brand discovery, and new arrivals/popular/trending feature descriptions.
• Backend Reference: See Catalog Product - Backend Documentation Section 9 for system architecture diagram.
• Brand Module: See Catalog Brand - Feature List for brand list/detail and slug history capabilities.
• Brand Series Module: See Brand Series - Feature List for series discovery endpoints.